{"record":{"id":"5585331b20322344","repo":"moeru-ai/airi","slug":"mcp-tools-are-not-available-in-this-runtime","errorCode":null,"errorMessage":"MCP tools are not available in this runtime.","messagePattern":"MCP tools are not available in this runtime\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/stage-ui/src/tools/mcp.ts","lineNumber":137,"sourceCode":"            isError: true,\n            content: [{ type: 'text', text: errorMessageFromValue(error) }],\n          }\n        }\n      },\n      // NOTICE: `arguments` is z.string() (JSON) because z.unknown() produces `{}` (no `type` key)\n      // and z.record() emits `propertyNames`, both rejected by OpenAI.\n      parameters: z.object({\n        name: z.string().describe('Tool name in \"<serverName>::<toolName>\" format'),\n        arguments: z.string().describe('JSON object of tool arguments, e.g. {\"query\":\"hello\",\"limit\":10}'),\n      }).strict(),\n    }),\n  ]\n}\n\nfunction createUnavailableMcpToolRuntime(): McpToolRuntime {\n  return {\n    async listTools() {\n      throw new Error('MCP tools are not available in this runtime.')\n    },\n    async callTool() {\n      throw new Error('MCP tools are not available in this runtime.')\n    },\n  }\n}\n\n/**\n * Builds the default stage-ui MCP tool set without depending on runtime singletons.\n *\n * Use when:\n * - Shared code needs the MCP tool schema before a concrete runtime registers live implementations\n *\n * Expects:\n * - Runtime-specific callers override these tools through `useLlmToolsStore`\n *\n * Returns:\n * - MCP tool definitions with an unavailable-runtime fallback","sourceCodeStart":119,"sourceCodeEnd":155,"githubUrl":"https://github.com/moeru-ai/airi/blob/677329427f32468c74b17f3ec47eeca4e05bec65/packages/stage-ui/src/tools/mcp.ts#L119-L155","documentation":"stage-ui ships default MCP tool schemas via mcp(), but the default runtime is createUnavailableMcpToolRuntime(), whose listTools throws this. A concrete runtime (e.g. Electron main over IPC) is expected to build real tools with createMcpTools(runtime) and register them through useLlmToolsStore to override the defaults. Inside createMcpTools the throw is caught and '' is returned to the model, so the raw error mainly reaches direct runtime callers and tests.","triggerScenarios":"The LLM invokes builtIn_mcpListTools while only the default mcp() tool set is registered — stage-web or a test environment where no runtime wired an McpToolRuntime bridge.","commonSituations":"Running the shared toolset in a new runtime integration before implementing the bridge; unit tests importing the default tools; MCP enabled in web where it is Electron-only.","solutions":["In runtime bootstrap, implement McpToolRuntime (listTools/callTool) and register createMcpTools(runtime) via useLlmToolsStore so it overrides the defaults.","If the runtime cannot support MCP, exclude the default mcp() tools from the tool list instead of shipping them.","In tests, pass a stub runtime to createMcpTools rather than calling mcp()."],"exampleFix":"// before\nconst tools = await mcp() // default unavailable runtime\n\n// after\nconst runtime: McpToolRuntime = electronMcpRuntime // real bridge\nconst tools = await Promise.all(createMcpTools(runtime))\nawait useLlmToolsStore().setTools('mcp', tools)","handlingStrategy":"validation","validationCode":"const mcpSupported = isStageTamagotchi() // or your runtime capability flag\nconst tools = mcpSupported\n  ? await Promise.all(createMcpTools(runtime))\n  : [] // do not register the unavailable defaults","typeGuard":null,"tryCatchPattern":"try {\n  return await runtime.listTools()\n}\ncatch (e) {\n  if (errorMessageFrom(e)?.includes('not available in this runtime'))\n    return [] // treat as zero MCP tools\n  throw e\n}","preventionTips":["Never register mcp() defaults in runtimes without a bridge.","Probe runtime capabilities at bootstrap and filter the tool list accordingly.","Keep MCP behind a runtime flag in shared code."],"tags":["mcp","tools","runtime","capability","electron"],"backgroundTag":"missing-runtime-capability","analyzedSha":"677329427f32468c74b17f3ec47eeca4e05bec65","analyzedAt":"2026-08-18T17:29:58.153Z","contentChangedAt":"2026-08-18T17:29:58.153Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}