refactor: address code review feedback — extract helper, use Zod schemas, fix type safety

- Extract formatToolOutput() static helper for output transformation
- Replace `as any` casts in tool handler with explicit Record<string,unknown>
- Use Zod schemas for prompt argsSchema (z.string().describe() vs raw objects)
- Add zod@^4.3.6 dependency aligned with @objectstack/spec
- Document duck-typing pattern for IAIService.toolRegistry access

Agent-Logs-Url: https://github.com/objectstack-ai/framework/sessions/5eb90a65-846f-4f24-947f-1c0e7ea5090e

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/plugins/plugin-mcp-server/package.json

@@ -20,7 +20,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@objectstack/core": "workspace:*",
-    "@objectstack/spec": "workspace:*"
+    "@objectstack/spec": "workspace:*",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@types/node": "^25.5.2",

packages/plugins/plugin-mcp-server/src/mcp-server-runtime.ts

@@ -4,7 +4,8 @@ import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mc
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import type { Logger, IMetadataService, IDataEngine, AIToolDefinition } from '@objectstack/spec/contracts';
 import type { Agent } from '@objectstack/spec';
-import type { ToolRegistry } from './types.js';
+import type { ToolRegistry, ToolExecutionResult } from './types.js';
+import { z } from 'zod';
 
 /**
  * Configuration for the MCP Server Runtime.
@@ -91,6 +92,22 @@ export class MCPServerRuntime {
     return this.started;
   }
 
+  // ── Helpers ─────────────────────────────────────────────────────
+
+  /**
+   * Extract the text value from a ToolExecutionResult's output.
+   *
+   * The output may be a `{ type: 'text', value: string }` object (from the
+   * Vercel AI SDK ToolResultPart) or any serialisable value.
+   */
+  private static formatToolOutput(result: ToolExecutionResult): string {
+    const output = result.output;
+    if (output && typeof output === 'object' && 'value' in output) {
+      return String((output as { value: unknown }).value);
+    }
+    return JSON.stringify(output ?? '');
+  }
+
   // ── Tool Bridge ────────────────────────────────────────────────
 
   /**
@@ -133,9 +150,10 @@ export class MCPServerRuntime {
         },
       },
       async (extra) => {
-        // MCP SDK passes the raw arguments when no inputSchema is defined
-        // We need to extract them from the request
-        const args = (extra as any)?.arguments ?? (extra as any)?.params?.arguments ?? {};
+        // The MCP SDK passes tool arguments via the extra.arguments property
+        // when registerTool is called without an inputSchema.
+        const rawExtra = extra as Record<string, unknown>;
+        const args = (rawExtra.arguments ?? {}) as Record<string, unknown>;
 
         try {
           const result = await toolRegistry.execute({
@@ -145,9 +163,7 @@ export class MCPServerRuntime {
             input: args,
           });
 
-          const outputText = result.output && typeof result.output === 'object' && 'value' in result.output
-            ? String(result.output.value)
-            : JSON.stringify(result.output ?? '');
+          const outputText = MCPServerRuntime.formatToolOutput(result);
 
           if (result.isError) {
             return {
@@ -370,22 +386,10 @@ export class MCPServerRuntime {
         description: 'Load an agent\'s system prompt with optional UI context. ' +
           'Use the agentName argument to select which agent\'s instructions to use.',
         argsSchema: {
-          agentName: {
-            type: 'string' as any,
-            description: 'Name of the agent to load (e.g. "data_chat", "metadata_assistant")',
-          },
-          objectName: {
-            type: 'string' as any,
-            description: 'Current object the user is viewing',
-          },
-          recordId: {
-            type: 'string' as any,
-            description: 'Currently selected record ID',
-          },
-          viewName: {
-            type: 'string' as any,
-            description: 'Current view name',
-          },
+          agentName: z.string().describe('Name of the agent to load (e.g. "data_chat", "metadata_assistant")'),
+          objectName: z.string().optional().describe('Current object the user is viewing'),
+          recordId: z.string().optional().describe('Currently selected record ID'),
+          viewName: z.string().optional().describe('Current view name'),
         },
       },
       async (args) => {

packages/plugins/plugin-mcp-server/src/plugin.ts

@@ -79,6 +79,10 @@ export class MCPServerPlugin implements Plugin {
     if (!this.runtime) return;
 
     // ── Bridge tools from AIService ──
+    // The IAIService contract does not formally include `toolRegistry` because
+    // it is an implementation detail of AIService.  We use duck-typing here to
+    // avoid a hard dependency on @objectstack/service-ai while still bridging
+    // tools when the full AIService implementation is present.
     try {
       const aiService = ctx.getService<IAIService & { toolRegistry?: ToolRegistry }>('ai');
       if (aiService?.toolRegistry) {