feat(ai): Implement State Provider Inspection & Modification (#8187)

- ComponentService: Include stateProviderId in component tree (own provider only)
- DataService: Add inspectStateProvider and modifyStateProvider (client & server)
- Expose new tools via MCP and update OpenAPI spec

Author: tobiu

ai/mcp/server/neural-link/openapi.yaml

@@ -319,6 +319,64 @@ paths:
               schema:
                 type: object
 
+  /data/state/inspect:
+    post:
+      summary: Inspect State Provider
+      operationId: inspect_state_provider
+      x-pass-as-object: true
+      description: |
+        Inspects a specific state provider.
+
+        **When to Use:**
+        To view the hierarchical data of a StateProvider.
+      tags: [Data]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/InspectStateProviderRequest'
+      responses:
+        '200':
+          description: State provider data
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  id:
+                    type: string
+                  data:
+                    type: object
+
+  /data/state/modify:
+    post:
+      summary: Modify State Provider
+      operationId: modify_state_provider
+      x-pass-as-object: true
+      description: |
+        Modifies the data of a specific state provider.
+
+        **When to Use:**
+        To update application state stored in a StateProvider.
+      tags: [Data]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ModifyStateProviderRequest'
+      responses:
+        '200':
+          description: Modification successful
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+
   /drag/state:
     post:
       summary: Get Drag State
@@ -830,6 +888,34 @@ components:
           type: string
           description: The target App Worker Session ID
 
+    InspectStateProviderRequest:
+      type: object
+      required:
+        - providerId
+      properties:
+        providerId:
+          type: string
+          description: The ID of the state provider to inspect
+        sessionId:
+          type: string
+          description: The target App Worker Session ID
+
+    ModifyStateProviderRequest:
+      type: object
+      required:
+        - providerId
+        - data
+      properties:
+        providerId:
+          type: string
+          description: The ID of the state provider to modify
+        data:
+          type: object
+          description: The data object to merge into the provider
+        sessionId:
+          type: string
+          description: The target App Worker Session ID
+
     ErrorResponse:
       type: object
       properties:

ai/mcp/server/neural-link/services/DataService.mjs

@@ -25,6 +25,17 @@ class DataService extends Base {
         singleton: true
     }
 
+    /**
+     * Inspects a specific state provider.
+     * @param {Object} opts The options object.
+     * @param {String} opts.providerId The ID of the provider to inspect.
+     * @param {String} [opts.sessionId] The target session ID.
+     * @returns {Promise<Object>} The state data.
+     */
+    async inspectStateProvider({providerId, sessionId}) {
+        return await ConnectionService.call(sessionId, 'inspect_state_provider', {providerId});
+    }
+
     /**
      * Inspects a specific data store.
      * @param {Object} opts The options object.
@@ -57,6 +68,18 @@ class DataService extends Base {
     async getRecord({recordId, storeId, sessionId}) {
         return await ConnectionService.call(sessionId, 'get_record', {recordId, storeId});
     }
+
+    /**
+     * Modifies the data of a specific state provider.
+     * @param {Object} opts The options object.
+     * @param {String} opts.providerId The ID of the provider to modify.
+     * @param {Object} opts.data The data object to merge into the provider.
+     * @param {String} [opts.sessionId] The target session ID.
+     * @returns {Promise<void>}
+     */
+    async modifyStateProvider({data, providerId, sessionId}) {
+        return await ConnectionService.call(sessionId, 'modify_state_provider', {data, providerId});
+    }
 }
 
 export default Neo.setupClass(DataService);

ai/mcp/server/neural-link/services/toolService.mjs

@@ -24,8 +24,10 @@ const serviceMapping = {
     get_window_topology   : RuntimeService    .getWindowTopology   .bind(RuntimeService),
     get_worker_topology   : RuntimeService    .getWorkerTopology   .bind(RuntimeService),
     healthcheck           : HealthService     .healthcheck         .bind(HealthService),
+    inspect_state_provider: DataService       .inspectStateProvider.bind(DataService),
     inspect_store         : DataService       .inspectStore        .bind(DataService),
     list_stores           : DataService       .listStores          .bind(DataService),
+    modify_state_provider : DataService       .modifyStateProvider .bind(DataService),
     query_component       : ComponentService  .queryComponent      .bind(ComponentService),
     reload_page           : RuntimeService    .reloadPage          .bind(RuntimeService),
     set_component_property: ComponentService  .setComponentProperty.bind(ComponentService),

src/ai/Client.mjs

@@ -82,8 +82,10 @@ class Client extends Base {
             set_component       : me.services.component,
 
             get_record          : me.services.data,
+            inspect_state_provider: me.services.data,
             inspect_store       : me.services.data,
             list_stores         : me.services.data,
+            modify_state_provider: me.services.data,
 
             get_drag            : me.services.runtime,
             get_route           : me.services.runtime,

src/ai/client/ComponentService.mjs

@@ -150,6 +150,10 @@ class ComponentService extends Service {
             ntype    : component.ntype
         };
 
+        if (component.stateProvider) {
+            result.stateProviderId = component.stateProvider.id
+        }
+
         if (maxDepth === -1 || currentDepth < maxDepth) {
             const children = Neo.manager.Component.getChildren(component);
 

src/ai/client/DataService.mjs

@@ -46,6 +46,20 @@ class DataService extends Service {
         return record.toJSON();
     }
 
+    /**
+     * @param {Object} params
+     * @returns {Object}
+     */
+    inspectStateProvider(params) {
+        const provider = Neo.get(params.providerId);
+        if (!provider) throw new Error(`StateProvider not found: ${params.providerId}`);
+
+        return {
+            id  : provider.id,
+            data: provider.getHierarchyData()
+        }
+    }
+
     /**
      * @param {Object} params
      * @returns {Object}
@@ -88,6 +102,18 @@ class DataService extends Service {
             }))
         };
     }
+
+    /**
+     * @param {Object} params
+     * @returns {Object}
+     */
+    modifyStateProvider(params) {
+        const provider = Neo.get(params.providerId);
+        if (!provider) throw new Error(`StateProvider not found: ${params.providerId}`);
+
+        provider.setData(params.data);
+        return {success: true}
+    }
 }
 
 export default Neo.setupClass(DataService);