feat(ai): Harden Neural Link MCP Server (#8016)

tobiu · tobiu · commit 76638974ed58 · 2025-12-28T19:36:59.000+01:00
- Implement HealthService for WebSocket and session monitoring
- Add startup health checks and logging in Server.mjs
- Update ConnectionService to expose server status
- Enhance OpenAPI specs with health endpoint and detailed descriptions
diff --git a/ai/mcp/server/neural-link/Server.mjs b/ai/mcp/server/neural-link/Server.mjs
@@ -5,6 +5,7 @@ import Base from '../../../../src/core/Base.mjs';
 import aiConfig from './config.mjs';
 import logger from './logger.mjs';
 import ConnectionService from './services/ConnectionService.mjs';
+import HealthService from './services/HealthService.mjs';
 import { listTools, callTool } from './services/toolService.mjs';
 
 /**
@@ -56,18 +57,35 @@ class Server extends Base {
         // 3. Setup Handlers
         this.setupRequestHandlers();
 
-        // 4. Start Connection Service (WebSocket)
-        if (!ConnectionService.isReady) {
-            // Ensure initialized
-        }
+        // 4. Wait for Connection Service
+        await ConnectionService.ready();
+
+        // 5. Perform Health Check & Log Status
+        const health = await HealthService.healthcheck();
+        this.logStartupStatus(health);
 
-        // 5. Connect Transport (Stdio)
+        // 6. Connect Transport (Stdio)
         this.transport = new StdioServerTransport();
         await this.mcpServer.connect(this.transport);
 
         logger.info('Neural Link MCP Server started');
     }
 
+    /**
+     * Logs the health status of the server during startup.
+     * @param {Object} health The health check result object.
+     */
+    logStartupStatus(health) {
+        if (health.status === 'unhealthy') {
+            logger.warn('⚠️  [Startup] Neural Link is unhealthy. Server will start but tools will fail until resolved.');
+            health.details.forEach(detail => logger.warn(`    ${detail}`));
+        } else {
+            logger.info('✅ [Startup] Neural Link health check passed');
+            logger.info(`   - Active Sessions: ${health.server.activeSessions}`);
+            logger.info(`   - Connected Windows: ${health.server.connectedWindows}`);
+        }
+    }
+
     setupRequestHandlers() {
         // List Tools Handler
         this.mcpServer.server.setRequestHandler(ListToolsRequestSchema, async (request) => {
@@ -91,8 +109,24 @@ class Server extends Base {
         // Call Tool Handler
         this.mcpServer.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const { name, arguments: args } = request.params;
+
             try {
                 logger.debug(`[MCP] Calling tool: ${name} with params:`, JSON.stringify(request.params));
+
+                // Health Check Gate
+                if (name !== 'healthcheck') {
+                    const health = await HealthService.healthcheck();
+                    if (health.status !== 'healthy') {
+                         return {
+                            content: [{
+                                type: 'text',
+                                text: `Cannot execute ${name}: Neural Link is unhealthy.\nDetails: ${health.details.join(', ')}`
+                            }],
+                            isError: true
+                        };
+                    }
+                }
+
                 const result = await callTool(name, args);
 
                 return {
diff --git a/ai/mcp/server/neural-link/openapi.yaml b/ai/mcp/server/neural-link/openapi.yaml
@@ -3,12 +3,49 @@ info:
   title: Neo.mjs Neural Link MCP Server
   version: 1.0.0
 paths:
+  /health:
+    post:
+      summary: Health Check
+      operationId: healthcheck
+      x-annotations:
+        readOnlyHint: true
+      description: |
+        Checks the health of the Neural Link server, including WebSocket connectivity and active sessions.
+
+        **When to Use:**
+        Use this as a first-step diagnostic tool to ensure the Neural Link bridge to the browser is operational.
+      tags: [Health]
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties: {}
+      responses:
+        '200':
+          description: Server is healthy
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthCheckResponse'
+        '503':
+          description: Server is unhealthy
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
   /component/property/get:
     post:
       summary: Get Component Property
       operationId: get_component_property
       x-pass-as-object: true
-      description: Retrieves a property from a component by its ID.
+      description: |
+        Retrieves a property from a component by its ID.
+
+        **When to Use:**
+        To inspect the current state of a component (e.g., `width`, `store`, `value`).
+      tags: [Component]
       requestBody:
         required: true
         content:
@@ -40,7 +77,12 @@ paths:
       summary: Get Component Tree
       operationId: get_component_tree
       x-pass-as-object: true
-      description: Retrieves the full component tree of the application.
+      description: |
+        Retrieves the full component tree of the application.
+
+        **When to Use:**
+        To understand the structure of the UI, find component IDs, or debug hierarchy issues.
+      tags: [Component]
       requestBody:
         content:
           application/json:
@@ -72,7 +114,12 @@ paths:
       summary: Get Component VDOM Tree
       operationId: get_vdom_tree
       x-pass-as-object: true
-      description: Retrieves the VDOM tree of a component.
+      description: |
+        Retrieves the VDOM tree of a component.
+
+        **When to Use:**
+        To inspect the Virtual DOM structure of a component for rendering issues.
+      tags: [Component]
       requestBody:
         content:
           application/json:
@@ -103,7 +150,12 @@ paths:
       summary: Get Component VNode Tree
       operationId: get_vnode_tree
       x-pass-as-object: true
-      description: Retrieves the VNode tree of a component.
+      description: |
+        Retrieves the VNode tree of a component.
+
+        **When to Use:**
+        To inspect the actual DOM-aligned VNodes (after VDOM processing). Useful for deep rendering debugging.
+      tags: [Component]
       requestBody:
         content:
           application/json:
@@ -134,7 +186,12 @@ paths:
       summary: Get Drag State
       operationId: get_drag_state
       x-pass-as-object: true
-      description: Retrieves the state of the DragCoordinator.
+      description: |
+        Retrieves the state of the DragCoordinator.
+
+        **When to Use:**
+        To debug drag-and-drop operations, checking what is being dragged and where.
+      tags: [Inspection]
       requestBody:
         content:
           application/json:
@@ -157,7 +214,12 @@ paths:
       summary: Reload Page
       operationId: reload_page
       x-pass-as-object: true
-      description: Reloads the application page.
+      description: |
+        Reloads the application page.
+
+        **When to Use:**
+        To force a full reload of the connected application window.
+      tags: [Lifecycle]
       requestBody:
         content:
           application/json:
@@ -183,7 +245,12 @@ paths:
     post:
       summary: Get Worker Topology
       operationId: get_worker_topology
-      description: Retrieves the topology of all connected App Workers.
+      description: |
+        Retrieves the topology of all connected App Workers.
+
+        **When to Use:**
+        To discover connected workers, their session IDs, and environments.
+      tags: [Topology]
       requestBody:
         content:
           application/json:
@@ -217,7 +284,12 @@ paths:
     post:
       summary: Get Window Topology
       operationId: get_window_topology
-      description: Retrieves the topology of all connected windows.
+      description: |
+        Retrieves the topology of all connected windows.
+
+        **When to Use:**
+        To map logical window IDs to physical browser windows and their dimensions.
+      tags: [Topology]
       requestBody:
         content:
           application/json:
@@ -250,7 +322,12 @@ paths:
       summary: Set Component Property
       operationId: set_component_property
       x-pass-as-object: true
-      description: Sets a property on a component by its ID.
+      description: |
+        Sets a property on a component by its ID.
+
+        **When to Use:**
+        To modify the runtime state of a component (e.g., change text, toggle visibility).
+      tags: [Component]
       requestBody:
         required: true
         content:
@@ -275,6 +352,33 @@ paths:
 
 components:
   schemas:
+    HealthCheckResponse:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: [healthy, unhealthy, degraded]
+        timestamp:
+          type: string
+          format: date-time
+        server:
+          type: object
+          properties:
+            port:
+              type: integer
+            activeSessions:
+              type: integer
+            connectedWindows:
+              type: integer
+        details:
+          type: array
+          items:
+            type: string
+        version:
+          type: string
+        uptime:
+          type: number
+
     GetComponentPropertyRequest:
       type: object
       required:
@@ -335,4 +439,4 @@ components:
       properties:
         error:
           type: string
-          description: Error message
+          description: Error message
diff --git a/ai/mcp/server/neural-link/services/ConnectionService.mjs b/ai/mcp/server/neural-link/services/ConnectionService.mjs
@@ -349,6 +349,27 @@ class ConnectionService extends Base {
         return Array.from(this.sessionData.values())
     }
 
+    /**
+     * Returns the current status of the server.
+     * @returns {Object}
+     */
+    getStatus() {
+        const windows = [];
+
+        for (const meta of this.sessionData.values()) {
+            if (meta.windows) {
+                for (const win of meta.windows.values()) {
+                    windows.push(win)
+                }
+            }
+        }
+
+        return {
+            sessions: this.sessions.size,
+            windows
+        }
+    }
+
     /**
      * Reloads the application page.
      * @param {Object} opts            The options object.
diff --git a/ai/mcp/server/neural-link/services/HealthService.mjs b/ai/mcp/server/neural-link/services/HealthService.mjs
@@ -0,0 +1,71 @@
+import Base              from '../../../../../src/core/Base.mjs';
+import ConnectionService from './ConnectionService.mjs';
+import logger            from '../logger.mjs';
+
+/**
+ * @summary Monitors the health of the Neural Link MCP Server.
+ *
+ * This service checks the status of the WebSocket server and the active connections
+ * to the App Worker(s). It provides a `healthcheck` tool that agents can use
+ * to verify if the runtime bridge is operational.
+ *
+ * @class Neo.ai.mcp.server.neural-link.services.HealthService
+ * @extends Neo.core.Base
+ * @singleton
+ */
+class HealthService extends Base {
+    static config = {
+        /**
+         * @member {String} className='Neo.ai.mcp.server.neural-link.services.HealthService'
+         * @protected
+         */
+        className: 'Neo.ai.mcp.server.neural-link.services.HealthService',
+        /**
+         * @member {Boolean} singleton=true
+         * @protected
+         */
+        singleton: true
+    }
+
+    /**
+     * Checks the health of the Neural Link server.
+     * @returns {Promise<Object>} The health status payload.
+     */
+    async healthcheck() {
+        try {
+            const status = ConnectionService.getStatus();
+            const details = [];
+
+            if (status.sessions === 0) {
+                details.push('No active App Worker sessions');
+            } else {
+                details.push(`${status.sessions} active App Worker session(s)`);
+                details.push(`${status.windows.length} connected window(s)`);
+            }
+
+            return {
+                status   : 'healthy',
+                timestamp: new Date().toISOString(),
+                server   : {
+                    port            : ConnectionService.port,
+                    activeSessions  : status.sessions,
+                    connectedWindows: status.windows.length
+                },
+                details,
+                version  : process.env.npm_package_version || '1.0.0',
+                uptime   : process.uptime()
+            };
+        } catch (error) {
+            logger.error('[HealthService] Unexpected error during health check:', error);
+            return {
+                status : 'unhealthy',
+                details: [`Unexpected error: ${error.message}`],
+                error  : 'Health check failed unexpectedly',
+                message: error.message,
+                code   : 'HEALTH_CHECK_ERROR'
+            };
+        }
+    }
+}
+
+export default Neo.setupClass(HealthService);
diff --git a/ai/mcp/server/neural-link/services/toolService.mjs b/ai/mcp/server/neural-link/services/toolService.mjs
@@ -2,6 +2,7 @@ import path              from 'path';
 import {fileURLToPath}   from 'url';
 import ToolService       from '../../../ToolService.mjs';
 import ConnectionService from './ConnectionService.mjs';
+import HealthService     from './HealthService.mjs';
 
 const __filename      = fileURLToPath(import.meta.url);
 const __dirname       = path.dirname(__filename);
@@ -15,6 +16,7 @@ const serviceMapping = {
     get_vnode_tree        : ConnectionService.getVnodeTree.bind(ConnectionService),
     get_window_topology   : ConnectionService.getWindowTopology.bind(ConnectionService),
     get_worker_topology   : ConnectionService.getWorkerTopology.bind(ConnectionService),
+    healthcheck           : HealthService.healthcheck.bind(HealthService),
     reload_page           : ConnectionService.reloadPage.bind(ConnectionService),
     set_component_property: ConnectionService.setComponentProperty.bind(ConnectionService)
 };
