fix(stage-ui): outdated for mcp.ts

Author: nekomeowww

packages/stage-ui/src/tools/mcp.ts

@@ -1,45 +1,159 @@
+import type { Tool } from '@xsai/shared-chat'
+
+import { errorMessageFrom } from '@moeru/std'
 import { tool } from '@xsai/tool'
 import { z } from 'zod'
 
-import { getMcpToolBridge } from '../stores/mcp-tool-bridge'
-
-const tools = [
-  tool({
-    name: 'builtIn_mcpListTools',
-    description: 'List all available MCP tools. Call this first to discover tool names before calling builtIn_mcpCallTool.',
-    execute: async () => {
-      try {
-        return await getMcpToolBridge().listTools()
-      }
-      catch (error) {
-        console.warn('[builtIn_mcpListTools] failed to list tools:', error)
-        return ''
-      }
-    },
-    parameters: z.object({}).strict(),
-  }),
-  tool({
-    name: 'builtIn_mcpCallTool',
-    description: 'Call an MCP tool by name. Use builtIn_mcpListTools first to get available tool names.',
-    execute: async ({ name, arguments: argsJson }) => {
-      try {
-        const args = argsJson ? JSON.parse(argsJson) : {}
-        return await getMcpToolBridge().callTool({ name, arguments: args })
-      }
-      catch (error) {
-        return {
-          isError: true,
-          content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+/**
+ * Describes an MCP tool that can be exposed to the shared LLM runtime.
+ *
+ * Use when:
+ * - A runtime needs to list available MCP tools before exposing them to models
+ *
+ * Expects:
+ * - `name` is the fully-qualified tool name used for invocation
+ *
+ * Returns:
+ * - The MCP tool descriptor metadata reported by the runtime
+ */
+export interface McpToolDescriptor {
+  serverName: string
+  name: string
+  toolName: string
+  description?: string
+  inputSchema: Record<string, unknown>
+}
+
+/**
+ * Payload for invoking an MCP tool through a runtime-specific transport.
+ *
+ * Use when:
+ * - A runtime needs to forward a tool invocation into the MCP layer
+ *
+ * Expects:
+ * - `name` matches a descriptor returned from `listTools`
+ * - `arguments` is a JSON-compatible object when provided
+ *
+ * Returns:
+ * - The MCP tool call input envelope
+ */
+export interface McpCallToolPayload {
+  name: string
+  arguments?: Record<string, unknown>
+}
+
+/**
+ * Result returned from an MCP tool invocation.
+ *
+ * Use when:
+ * - An MCP runtime returns tool output back to the shared LLM layer
+ *
+ * Expects:
+ * - Error responses set `isError` when the tool execution failed
+ *
+ * Returns:
+ * - Structured and unstructured MCP tool output
+ */
+export interface McpCallToolResult {
+  content?: Array<Record<string, unknown>>
+  structuredContent?: Record<string, unknown>
+  toolResult?: unknown
+  isError?: boolean
+}
+
+/**
+ * Runtime contract for wiring MCP tool discovery and execution into `stage-ui`.
+ *
+ * Use when:
+ * - A concrete runtime such as Electron needs to provide MCP access without a singleton bridge
+ *
+ * Expects:
+ * - `listTools` and `callTool` are safe to call multiple times
+ *
+ * Returns:
+ * - An object that can back `createMcpTools`
+ */
+export interface McpToolRuntime {
+  listTools: () => Promise<McpToolDescriptor[]>
+  callTool: (payload: McpCallToolPayload) => Promise<McpCallToolResult>
+}
+
+/**
+ * Creates MCP proxy tools backed by a runtime-provided transport.
+ *
+ * Use when:
+ * - A runtime wants to register MCP tools into the shared LLM tool store
+ *
+ * Expects:
+ * - The runtime implements the `McpToolRuntime` contract
+ *
+ * Returns:
+ * - xsai tool definition promises for MCP listing and invocation
+ */
+export function createMcpTools(runtime: McpToolRuntime): Array<Promise<Tool>> {
+  return [
+    tool({
+      name: 'builtIn_mcpListTools',
+      description: 'List all available MCP tools. Call this first to discover tool names before calling builtIn_mcpCallTool.',
+      execute: async () => {
+        try {
+          return await runtime.listTools()
         }
-      }
+        catch (error) {
+          console.warn('[builtIn_mcpListTools] failed to list tools:', error)
+          return ''
+        }
+      },
+      parameters: z.object({}).strict(),
+    }),
+    tool({
+      name: 'builtIn_mcpCallTool',
+      description: 'Call an MCP tool by name. Use builtIn_mcpListTools first to get available tool names.',
+      execute: async ({ name, arguments: argsJson }) => {
+        try {
+          const args = argsJson ? JSON.parse(argsJson) : {}
+          return await runtime.callTool({ name, arguments: args })
+        }
+        catch (error) {
+          return {
+            isError: true,
+            content: [{ type: 'text', text: errorMessageFrom(error) ?? String(error) }],
+          }
+        }
+      },
+      // NOTICE: `arguments` is z.string() (JSON) because z.unknown() produces `{}` (no `type` key)
+      // and z.record() emits `propertyNames`, both rejected by OpenAI.
+      parameters: z.object({
+        name: z.string().describe('Tool name in "<serverName>::<toolName>" format'),
+        arguments: z.string().describe('JSON object of tool arguments, e.g. {"query":"hello","limit":10}'),
+      }).strict(),
+    }),
+  ]
+}
+
+function createUnavailableMcpToolRuntime(): McpToolRuntime {
+  return {
+    async listTools() {
+      throw new Error('MCP tools are not available in this runtime.')
+    },
+    async callTool() {
+      throw new Error('MCP tools are not available in this runtime.')
     },
-    // NOTICE: `arguments` is z.string() (JSON) because z.unknown() produces `{}` (no `type` key)
-    // and z.record() emits `propertyNames`, both rejected by OpenAI.
-    parameters: z.object({
-      name: z.string().describe('Tool name in "<serverName>::<toolName>" format'),
-      arguments: z.string().describe('JSON object of tool arguments, e.g. {"query":"hello","limit":10}'),
-    }).strict(),
-  }),
-]
-
-export const mcp = async () => Promise.all(tools)
+  }
+}
+
+/**
+ * Builds the default stage-ui MCP tool set without depending on runtime singletons.
+ *
+ * Use when:
+ * - Shared code needs the MCP tool schema before a concrete runtime registers live implementations
+ *
+ * Expects:
+ * - Runtime-specific callers override these tools through `useLlmToolsStore`
+ *
+ * Returns:
+ * - MCP tool definitions with an unavailable-runtime fallback
+ */
+export async function mcp(): Promise<Tool[]> {
+  return await Promise.all(createMcpTools(createUnavailableMcpToolRuntime()))
+}