foliko 1.0.74 → 1.0.76

package/src/executors/mcp-executor.js

@@ -1,729 +1,741 @@
-/**
- * MCPExecutor MCP 执行器
- * 使用 @ai-sdk/mcp 连接到 MCP 服务器
- */
-
-const { Plugin } = require('../core/plugin-base')
-const { spawn } = require('child_process')
-const fs = require('fs')
-const path = require('path')
-const { z } = require('zod')
-const {createMCPClient} = require('@ai-sdk/mcp')
-const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');
-
-/**
- * MCP 客户端包装器
- */
-class MCPClientWrapper {
-  constructor(options = {}) {
-    this.serverName = options.serverName || 'unknown'
-    this.command = options.command
-    this.args = options.args || []
-    this.env = options.env || {}
-    this.timeout = options.timeout || 30000
-    this.priority = 11
-    this.client = null
-    this.connected = false
-    this.tools = []
-  }
-
-  /**
-   * 连接 MCP 服务器
-   */
-  async connect() {
-    if (this.connected) return
-
-    try {
-      // 动态导入 @ai-sdk/mcp
-      let createMCPClient
-
-      try {
-        const mcpModule = require('@ai-sdk/mcp')
-        createMCPClient = mcpModule.createMCPClient || mcpModule.experimental_createMCPClient
-      } catch (err) {
-        throw new Error('@ai-sdk/mcp not installed. Please run: npm install @ai-sdk/mcp')
-      }
-
-      if (!createMCPClient) {
-        throw new Error('createMCPClient not available')
-      }
-
-      // 解析命令路径
-      const { which, shellResolve } = this._resolveCommand(this.command)
-
-      // 使用正确的子路径导入
-      try {
-        const { Experimental_StdioMCPTransport } = require('@ai-sdk/mcp/mcp-stdio')
-        const transport = new Experimental_StdioMCPTransport({
-          command: which || this.command,
-          args: shellResolve ? [shellResolve, ...this.args] : this.args,
-          env: { ...process.env, ...this.env }
-        })
-        this.client = await createMCPClient({ transport })
-      } catch (transportErr) {
-        console.error(`[MCPExecutor] Transport error:`, transportErr.message)
-        throw transportErr
-      }
-
-      // 获取工具列表
-      // 新版 API: tools() 是函数
-      if (typeof this.client.tools === 'function') {
-        const toolsObject = await this.client.tools()
-        this.tools = Object.entries(toolsObject)
-          .filter(([, tool]) => tool != null)
-          .map(([name, tool]) => ({ ...tool, name }))
-      } else if (this.client.tools && typeof this.client.tools.list === 'function') {
-        // 旧版 API: tools.list()
-        const listResult = await this.client.tools.list()
-        this.tools = listResult.tools || []
-      }
-
-      this.connected = true
-      console.log(`[MCPExecutor] Connected to ${this.serverName} with ${this.tools.length} tools`)
-    } catch (err) {
-      console.error(`[MCPExecutor] Failed to connect to ${this.serverName}:`, err.message)
-      // 不抛出错误，让框架继续运行
-    }
-  }
-
-  /**
-   * 解析命令路径
-   */
-  _resolveCommand(cmd) {
-    const isWindows = process.platform === 'win32'
-    const ext = isWindows ? '.cmd' : ''
-    const withExt = cmd + ext
-
-    // 检查命令是否直接存在
-    try {
-      const result = spawn.sync(withExt, ['--version'], {
-        stdio: 'ignore',
-        timeout: 2000
-      })
-      if (result.error?.code !== 'ENOENT') {
-        return { which: withExt, shellResolve: null }
-      }
-    } catch (e) {
-      // ignore
-    }
-
-    // 尝试解析 npm 全局 bin 目录
-    const globalCommands = isWindows
-      ? [
-          path.join(process.env.APPDATA || '', 'npm', withExt),
-          path.join(process.env.PROGRAMDATA || 'C:\\ProgramData', 'npm', withExt)
-        ]
-      : ['/usr/local/bin/' + cmd, '/usr/bin/' + cmd]
-
-    for (const cmdPath of globalCommands) {
-      try {
-        if (fs.existsSync(cmdPath)) {
-          return { which: cmdPath, shellResolve: null }
-        }
-      } catch (e) {
-        // ignore
-      }
-    }
-
-    return { which: cmd, shellResolve: null }
-  }
-
-  /**
-   * 调用工具
-   */
-  async callTool(toolName, args) {
-    if (!this.connected) {
-      await this.connect()
-    }
-
-    if (!this.client) {
-      throw new Error('MCP client not initialized')
-    }
-
-    try {
-      // 新版 API: tools() 返回对象
-      let toolsObject
-      if (typeof this.client.tools === 'function') {
-        toolsObject = await this.client.tools()
-      } else if (this.client.tools && typeof this.client.tools.list === 'function') {
-        // 旧版 API
-        const listResult = await this.client.tools.list()
-        toolsObject = listResult.tools || {}
-      } else {
-        throw new Error('Cannot get tools from MCP client')
-      }
-
-      const tool = toolsObject[toolName]
-      if (!tool) {
-        throw new Error(`Tool not found: ${toolName}`)
-      }
-
-      const result = await tool.execute(args)
-      return result
-    } catch (err) {
-      console.error(`[MCPExecutor] Tool call failed: ${toolName}:`, err.message)
-      throw err
-    }
-  }
-
-  /**
-   * 断开连接
-   */
-  async disconnect() {
-    if (this.client) {
-      try {
-        await this.client.destroy()
-      } catch (e) {
-        // ignore
-      }
-      this.client = null
-      this.connected = false
-      this.tools = []
-    }
-  }
-}
-
-/**
- * MCPExecutorPlugin
- */
-class MCPExecutorPlugin extends Plugin {
-  constructor(config = {}) {
-    super()
-    this.name = 'mcp-executor'
-    this.version = '1.0.0'
-    this.description = 'MCP (Model Context Protocol) 执行器'
-    this.priority = 11
-    this.system = true
-
-    this._framework = null
-    // serverName -> { client, tools: [{ name, description, inputSchema }], toolObjects: { toolName: actualTool } }
-    this._clients = new Map()
-    this._config = config
-  }
-
-  install(framework) {
-    this._framework = framework
-    return this
-  }
-
-  async start(framework) {
-    // 先连接所有 MCP 服务器
-    if (this._config.servers) {
-      for (const serverConfig of this._config.servers) {
-        await this.addServer(serverConfig)
-      }
-    }
-
-    // 注册 mcp_tool_schema 工具 - 直接返回可用的调用示例
-    framework.registerTool({
-      name: 'mcp_tool_schema',
-      description: '查询工具的调用示例，直接复制 example 或 fullExample 字段使用',
-      inputSchema: z.object({
-        server: z.string().describe('MCP 服务器名称'),
-        tool: z.string().describe('工具名称')
-      }),
-      execute: async (args) => {
-        const { server, tool } = args
-        const clientInfo = this._clients.get(server)
-        if (!clientInfo) {
-          return { success: false, error: `MCP server '${server}' not found` }
-        }
-
-        const toolInfo = clientInfo.tools.find(t => t.name === tool)
-        if (!toolInfo) {
-          return { success: false, error: `Tool '${tool}' not found` }
-        }
-
-        const schema = this._extractSchema(toolInfo.inputSchema)
-        const props = schema.properties || {}
-        const required = schema.required || []
-
-        // 生成示例值的辅助函数
-        const generateExample = (prop, depth = 0) => {
-          if (!prop) return null
-          const type = prop.type || (prop.properties ? 'object' : 'string')
-
-          if (type === 'string') {
-            return prop.description?.split('.')[0] || `${prop.title || '值'}`
-          } else if (type === 'number' || type === 'integer') {
-            return prop.default || 0
-          } else if (type === 'boolean') {
-            return false
-          } else if (type === 'array') {
-            // 数组类型：提供单个示例元素
-            if (prop.items) {
-              const itemExample = generateExample(prop.items, depth + 1)
-              return depth === 0 ? [itemExample] : itemExample
-            }
-            return ['示例']
-          } else if (type === 'object' || prop.properties) {
-            // 对象类型：递归生成嵌套结构
-            const obj = {}
-            const objProps = prop.properties || {}
-            for (const [key, val] of Object.entries(objProps)) {
-              obj[key] = generateExample(val, depth + 1)
-            }
-            return obj
-          }
-          return null
-        }
-
-        // 生成可直接使用的调用示例
-        const exampleArgs = {}
-        for (const key of required) {
-          const prop = props[key]
-          if (prop) {
-            exampleArgs[key] = generateExample(prop)
-          }
-        }
-
-        return {
-          success: true,
-          result: {
-            name: toolInfo.name,
-            description: toolInfo.description,
-            required,
-            // 各参数的详细说明
-            parameters: Object.fromEntries(
-              required.map(key => [key, {
-                type: props[key]?.type || 'string',
-                description: props[key]?.description || '',
-                example: generateExample(props[key])
-              }])
-            ),
-            // 直接返回可以复制使用的调用示例
-            example: JSON.stringify(exampleArgs, null, 2),
-            fullExample: `mcp_call({ server: "${server}", tool: "${tool}", args_json: ${JSON.stringify(JSON.stringify(exampleArgs))} })`
-          }
-        }
-      }
-    })
-
-    // 注册 mcp_call 工具
-    framework.registerTool({
-      name: 'mcp_call',
-      description: '调用 MCP 服务器工具。args_json 是包含实际参数的 JSON 字符串，如 \'{"url": "https://news.baidu.com"}\'',
-      inputSchema: z.object({
-        server: z.string().describe('MCP 服务器名称'),
-        tool: z.string().describe('工具名称'),
-        args_json: z.string().describe('参数 JSON 字符串，如 {"url": "https://..."}，fetch 工具必填 url')
-      }),
-      execute: async (args) => {
-        const { server, tool, args_json } = args
-        console.log(`[MCPExecutor] mcp_call: server=${server}, tool=${tool}, args_json=${args_json}`)
-
-        const clientInfo = this._clients.get(server)
-        if (!clientInfo) {
-          return { success: false, error: `MCP server '${server}' not found` }
-        }
-
-        // 解析 args_json
-        let finalArgs = {}
-        if (args_json) {
-          try {
-            finalArgs = JSON.parse(args_json)
-          } catch (e) {
-            return { success: false, error: `args_json 格式错误，不是有效的 JSON: ${args_json}` }
-          }
-        }
-
-        // 检查参数是否为空
-        if (!finalArgs || Object.keys(finalArgs).length === 0) {
-          const toolInfo = clientInfo.tools.find(t => t.name === tool)
-          if (toolInfo) {
-            const schema = this._extractSchema(toolInfo.inputSchema)
-            const required = schema.required || []
-            return {
-              success: false,
-              error: `参数为空！必须提供: ${required.join(', ')}`,
-              hint: `正确格式: {"${required[0]}": "具体值"}`
-            }
-          }
-        }
-
-        try {
-          // 使用缓存的工具对象
-          const mcpTool = clientInfo.toolObjects?.[tool]
-          if (!mcpTool) {
-            return { success: false, error: `Tool '${tool}' not found on server '${server}'` }
-          }
-          const execResult = await mcpTool.execute(finalArgs)
-          return { success: true, result: execResult }
-        } catch (err) {
-          console.error(`[MCPExecutor] Tool '${tool}' failed:`, err.message)
-          return { success: false, error: err.message }
-        }
-      }
-    })
-
-    // 注册 mcp_list_servers 工具
-    framework.registerTool({
-      name: 'mcp_list_servers',
-      description: '列出已连接的 MCP 服务器及其工具',
-      inputSchema: z.object({}),
-      execute: async () => {
-        const servers = []
-        for (const [name, info] of this._clients) {
-          servers.push({
-            name,
-            tools: info.tools.map(t => ({ name: t.name, description: t.description }))
-          })
-        }
-        return { success: true, servers }
-      }
-    })
-
-    // 注册 mcp_reload 工具
-    framework.registerTool({
-      name: 'mcp_reload',
-      description: '重新加载 MCP 服务器配置。当配置文件 .agent/mcp_config.json 修改后使用此工具重载配置',
-      inputSchema: z.object({}),
-      execute: async () => {
-        console.log('[MCPExecutor] mcp_reload called')
-        try {
-          const fs = require('fs')
-          const path = require('path')
-          const configPath = path.resolve('.agent/mcp_config.json')
-
-          console.log('[MCPExecutor] Reading config from:', configPath)
-          if (!fs.existsSync(configPath)) {
-            return { success: false, error: `配置文件不存在: ${configPath}` }
-          }
-
-          const configContent = fs.readFileSync(configPath, 'utf8')
-          const config = JSON.parse(configContent)
-          console.log('[MCPExecutor] Config loaded, reloading...')
-
-          await this.reloadConfig(config)
-          console.log('[MCPExecutor] Reload complete')
-
-          return { success: true, message: 'MCP 配置已重载', servers: Object.keys(config.mcpServers || {}) }
-        } catch (err) {
-          console.error('[MCPExecutor] Reload error:', err)
-          return { success: false, error: `重载失败: ${err.message}` }
-        }
-      }
-    })
-
-    // 监听 agent 创建事件，附加 MCP 信息到系统提示词
-    framework.on('agent:created', (agent) => {
-      if (!this._mainAgent) {
-        this._mainAgent = agent
-      }
-      this._refreshAgentMCPPrompt(agent)
-    })
-
-    // 等待框架就绪后，刷新所有已有 agent 的 MCP 提示词
-    if (framework._ready) {
-      this._refreshAllAgentsMCPPrompt(framework)
-    } else {
-      framework.once('framework:ready', () => {
-        this._refreshAllAgentsMCPPrompt(framework)
-      })
-    }
-
-    return this
-  }
-
-  /**
-   * 刷新所有 agent 的 MCP 提示词（包括子 agent）
-   */
-  _refreshAllAgentsMCPPrompt(framework) {
-    const visited = new Set()
-
-    const traverse = (agent) => {
-      if (!agent || visited.has(agent)) return
-      visited.add(agent)
-      this._refreshAgentMCPPrompt(agent)
-
-      // 递归处理子 agent
-      const subAgents = agent.getSubAgents?.() || agent._subAgents || new Map()
-      for (const [name, subAgentInfo] of subAgents) {
-        traverse(subAgentInfo.agent)
-      }
-    }
-
-    for (const agent of framework._agents || []) {
-      traverse(agent)
-    }
-  }
-
-  /**
-   * 刷新单个 agent 的 MCP 提示词
-   */
-  _refreshAgentMCPPrompt(agent) {
-    // 检查是否已刷新过（通过检查系统提示词是否已包含 MCP 描述）
-    const existingPrompt = agent._originalPrompt || ''
-    if (existingPrompt.includes('[MCP Servers]')) {
-      return
-    }
-
-    const mcpDesc = this._buildMCPServersDescription()
-    if (!mcpDesc) return
-
-    // 将 MCP 描述追加到系统提示词
-    agent.setSystemPrompt(existingPrompt + '\n\n' + mcpDesc)
-  }
-
-  /**
-   * 从 inputSchema 中提取实际 schema
-   */
-  _extractSchema(inputSchema) {
-    if (!inputSchema) return {}
-    // 处理 {jsonSchema: {...}} 格式
-    if (inputSchema.jsonSchema) return inputSchema.jsonSchema
-    // 处理直接是 schema 的格式
-    return inputSchema
-  }
-
-  /**
-   * 构建 MCP 服务器描述
-   */
-  _buildMCPServersDescription() {
-    if (this._clients.size === 0) {
-      return ''
-    }
-
-    let desc = '【MCP Servers - 可用工具服务】\n'
-    desc += '你可以通过 mcp_call 工具调用以下 MCP 服务器的工具。\n\n'
-
-    for (const [serverName, info] of this._clients) {
-      desc += `【${serverName}】\n`
-      for (const tool of info.tools) {
-        const schema = this._extractSchema(tool.inputSchema)
-        const props = schema.properties || {}
-        const required = schema.required || []
-
-        // 简化参数列表
-        let paramStr = ''
-        if (Object.keys(props).length > 0) {
-          const params = Object.entries(props).map(([key, prop]) => {
-            const isRequired = required.includes(key)
-            return `${key}${isRequired ? '(必填)' : ''}`
-          })
-          paramStr = ` 参数: ${params.join(', ')}`
-        }
-
-        // 截取描述的第一句
-        const shortDesc = tool.description?.split('.')[0] || '无描述'
-        desc += `- ${tool.name}: ${shortDesc}${paramStr}\n`
-      }
-      desc += '\n'
-    }
-
-    desc += '调用格式：mcp_call({ server: "服务器", tool: "工具", args_json: \'{"参数": "值"}\' })\n'
-    desc += '复杂参数时先用 mcp_tool_schema 查询完整参数结构\n'
-    return desc.trim()
-  }
-
-  _getParentAgent() {
-    // 优先返回已缓存的主 agent
-    if (this._mainAgent) {
-      return this._mainAgent
-    }
-
-    // 尝试从 framework 获取
-    if (this._framework._mainAgent) {
-      this._mainAgent = this._framework._mainAgent
-      return this._mainAgent
-    }
-
-    // 查找最后一个创建的 agent 作为父 agent
-    const agents = this._framework._agents || []
-    if (agents.length > 0) {
-      this._mainAgent = agents[agents.length - 1]
-      return this._mainAgent
-    }
-
-    return null
-  }
-
-  /**
-   * 带超时的 Promise
-   */
-  _withTimeout(promise, ms, name) {
-    return Promise.race([
-      promise,
-      new Promise((_, reject) =>
-        setTimeout(() => reject(new Error(`${name} timeout (${ms}ms)`)), ms)
-      )
-    ])
-  }
-
-  /**
-   * 添加 MCP 服务器
-   */
-  async addServer(config) {
-    const { name, command, args = [], env, url, type, headers = {}, authProvider } = config
-    if (this._clients.has(name)) {
-      console.warn(`[MCPExecutor] Server '${name}' already exists, skipping`)
-      return
-    }
-    console.log(`[MCPExecutor] Connecting to ${name}...`)
-    let client
-    try {
-      if (['sse', 'http'].includes(type)) {
-        client = await this._withTimeout(
-          createMCPClient({
-            transport: {
-              type: type,
-              url: url,
-              headers: headers,
-              authProvider: authProvider,
-              redirect: 'error',
-              env: env
-            },
-          }),
-          10000,
-          `createMCPClient ${name}`
-        )
-      } else {
-        client = await this._withTimeout(
-          createMCPClient({
-            transport: new StdioClientTransport({
-              command: command,
-              args: args,
-              env: env
-            }),
-          }),
-          10000,
-          `createMCPClient ${name}`
-        )
-      }
-    } catch (err) {
-      console.error(`[MCPExecutor] Failed to create client '${name}':`, err.message)
-      return
-    }
-
-    // 获取 MCP 服务器的工具列表
-    let mcpTools
-    try {
-      mcpTools = await this._withTimeout(client.tools(), 10000, `client.tools ${name}`)
-    } catch (err) {
-      console.error(`[MCPExecutor] Failed to get tools from '${name}':`, err.message)
-      return
-    }
-
-    // 提取工具信息和实际工具对象
-    const toolsInfo = []
-    const toolObjects = {} // 缓存实际工具对象
-    if (mcpTools && typeof mcpTools === 'object') {
-      for (const [toolName, tool] of Object.entries(mcpTools)) {
-        if (!tool) continue
-        toolObjects[toolName] = tool // 保存实际工具对象
-        toolsInfo.push({
-          name: toolName,
-          description: tool.description || '',
-          inputSchema: tool.inputSchema || {}
-        })
-      }
-    }
-
-    // 保存客户端、工具信息和实际工具对象
-    this._clients.set(name, {
-      client,
-      tools: toolsInfo,
-      toolObjects // 实际工具对象，供 mcp_call 直接调用
-    })
-
-    console.log(`[MCPExecutor] Added server '${name}' with ${toolsInfo.length} tools`)
-  }
-
-  /**
-   * 移除 MCP 服务器
-   */
-  async removeServer(name) {
-    const clientInfo = this._clients.get(name)
-    if (clientInfo) {
-      try {
-        // 添加超时保护，避免 close/destroy 阻塞
-        const closePromise = clientInfo.client.close?.() || clientInfo.client.destroy?.()
-        if (closePromise && typeof closePromise.then === 'function') {
-          await Promise.race([
-            closePromise,
-            new Promise(resolve => setTimeout(() => resolve(), 3000))
-          ])
-        }
-      } catch (e) {
-        // ignore
-      }
-      this._clients.delete(name)
-    }
-  }
-
-  /**
-   * 获取所有服务器
-   */
-  getServers() {
-    return Array.from(this._clients.entries()).map(([name, info]) => ({
-      name,
-      tools: info.tools.map(t => t.name)
-    }))
-  }
-
-  reload(framework) {
-    console.log('[MCPExecutor] Reloading...')
-    this._framework = framework
-  }
-
-  /**
-   * 重新加载 MCP 配置
-   * @param {Object} config - 新的配置对象，包含 mcpServers
-   */
-  async reloadConfig(config) {
-    console.log('[MCPExecutor] reloadConfig start')
-    const newServers = config?.mcpServers || {}
-
-    // 1. 先快速清理所有旧服务器（不等待 close 完成）
-    console.log('[MCPExecutor] Clearing old servers...')
-    for (const [name, clientInfo] of this._clients) {
-      try {
-        // 不等待 close，直接删除
-        clientInfo.client.close?.()?.catch?.(() => {})
-      } catch (e) {}
-    }
-    this._clients.clear()
-
-    // 2. 并行添加新服务器
-    console.log('[MCPExecutor] Adding new servers...')
-    const addPromises = Object.entries(newServers).map(async ([name, serverConfig]) => {
-      const normalizedConfig = {
-        name,
-        type: serverConfig.type,
-        url: serverConfig.url,
-        headers: serverConfig.headers,
-        authProvider: serverConfig.authProvider,
-        command: serverConfig.command,
-        args: serverConfig.args,
-        env: serverConfig.env
-      }
-      await this.addServer(normalizedConfig)
-    })
-
-    await Promise.all(addPromises)
-    console.log('[MCPExecutor] reloadConfig complete')
-
-    // 3. 刷新所有 agent 的 MCP 提示词
-    if (this._framework) {
-      this._refreshAllAgentsMCPPrompt(this._framework)
-    }
-  }
-
-  async uninstall(framework) {
-    // 断开所有 MCP 连接
-    for (const [name, clientInfo] of this._clients) {
-      try {
-        await clientInfo.client.close?.() || clientInfo.client.destroy?.()
-      } catch (e) {
-        // ignore
-      }
-    }
-    this._clients.clear()
-    this._framework = null
-  }
-}
-
-module.exports = {
-  MCPExecutorPlugin,
-  MCPClientWrapper
-}
+/**
+ * MCPExecutor MCP 执行器
+ * 使用 @ai-sdk/mcp 连接到 MCP 服务器
+ */
+
+const { Plugin } = require('../core/plugin-base');
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { z } = require('zod');
+const { createMCPClient } = require('@ai-sdk/mcp');
+const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');
+
+/**
+ * MCP 客户端包装器
+ */
+class MCPClientWrapper {
+  constructor(options = {}) {
+    this.serverName = options.serverName || 'unknown';
+    this.command = options.command;
+    this.args = options.args || [];
+    this.env = options.env || {};
+    this.timeout = options.timeout || 30000;
+    this.priority = 11;
+    this.client = null;
+    this.connected = false;
+    this.tools = [];
+  }
+
+  /**
+   * 连接 MCP 服务器
+   */
+  async connect() {
+    if (this.connected) return;
+
+    try {
+      // 动态导入 @ai-sdk/mcp
+      let createMCPClient;
+
+      try {
+        const mcpModule = require('@ai-sdk/mcp');
+        createMCPClient = mcpModule.createMCPClient || mcpModule.experimental_createMCPClient;
+      } catch (err) {
+        throw new Error('@ai-sdk/mcp not installed. Please run: npm install @ai-sdk/mcp');
+      }
+
+      if (!createMCPClient) {
+        throw new Error('createMCPClient not available');
+      }
+
+      // 解析命令路径
+      const { which, shellResolve } = this._resolveCommand(this.command);
+
+      // 使用正确的子路径导入
+      try {
+        const { Experimental_StdioMCPTransport } = require('@ai-sdk/mcp/mcp-stdio');
+        const transport = new Experimental_StdioMCPTransport({
+          command: which || this.command,
+          args: shellResolve ? [shellResolve, ...this.args] : this.args,
+          env: { ...process.env, ...this.env },
+        });
+        this.client = await createMCPClient({ transport });
+      } catch (transportErr) {
+        log.error(` Transport error:`, transportErr.message);
+        throw transportErr;
+      }
+
+      // 获取工具列表
+      // 新版 API: tools() 是函数
+      if (typeof this.client.tools === 'function') {
+        const toolsObject = await this.client.tools();
+        this.tools = Object.entries(toolsObject)
+          .filter(([, tool]) => tool != null)
+          .map(([name, tool]) => ({ ...tool, name }));
+      } else if (this.client.tools && typeof this.client.tools.list === 'function') {
+        // 旧版 API: tools.list()
+        const listResult = await this.client.tools.list();
+        this.tools = listResult.tools || [];
+      }
+
+      this.connected = true;
+      log.info(` Connected to ${this.serverName} with ${this.tools.length} tools`);
+    } catch (err) {
+      log.error(` Failed to connect to ${this.serverName}:`, err.message);
+      // 不抛出错误，让框架继续运行
+    }
+  }
+
+  /**
+   * 解析命令路径
+   */
+  _resolveCommand(cmd) {
+    const isWindows = process.platform === 'win32';
+    const ext = isWindows ? '.cmd' : '';
+    const withExt = cmd + ext;
+
+    // 检查命令是否直接存在
+    try {
+      const result = spawn.sync(withExt, ['--version'], {
+        stdio: 'ignore',
+        timeout: 2000,
+      });
+      if (result.error?.code !== 'ENOENT') {
+        return { which: withExt, shellResolve: null };
+      }
+    } catch (e) {
+      // ignore
+    }
+
+    // 尝试解析 npm 全局 bin 目录
+    const globalCommands = isWindows
+      ? [
+          path.join(process.env.APPDATA || '', 'npm', withExt),
+          path.join(process.env.PROGRAMDATA || 'C:\\ProgramData', 'npm', withExt),
+        ]
+      : ['/usr/local/bin/' + cmd, '/usr/bin/' + cmd];
+
+    for (const cmdPath of globalCommands) {
+      try {
+        if (fs.existsSync(cmdPath)) {
+          return { which: cmdPath, shellResolve: null };
+        }
+      } catch (e) {
+        // ignore
+      }
+    }
+
+    return { which: cmd, shellResolve: null };
+  }
+
+  /**
+   * 调用工具
+   */
+  async callTool(toolName, args) {
+    if (!this.connected) {
+      await this.connect();
+    }
+
+    if (!this.client) {
+      throw new Error('MCP client not initialized');
+    }
+
+    try {
+      // 新版 API: tools() 返回对象
+      let toolsObject;
+      if (typeof this.client.tools === 'function') {
+        toolsObject = await this.client.tools();
+      } else if (this.client.tools && typeof this.client.tools.list === 'function') {
+        // 旧版 API
+        const listResult = await this.client.tools.list();
+        toolsObject = listResult.tools || {};
+      } else {
+        throw new Error('Cannot get tools from MCP client');
+      }
+
+      const tool = toolsObject[toolName];
+      if (!tool) {
+        throw new Error(`Tool not found: ${toolName}`);
+      }
+
+      const result = await tool.execute(args);
+      return result;
+    } catch (err) {
+      log.error(` Tool call failed: ${toolName}:`, err.message);
+      throw err;
+    }
+  }
+
+  /**
+   * 断开连接
+   */
+  async disconnect() {
+    if (this.client) {
+      try {
+        await this.client.destroy();
+      } catch (e) {
+        // ignore
+      }
+      this.client = null;
+      this.connected = false;
+      this.tools = [];
+    }
+  }
+}
+
+/**
+ * MCPExecutorPlugin
+ */
+class MCPExecutorPlugin extends Plugin {
+  constructor(config = {}) {
+    super();
+    this.name = 'mcp-executor';
+    this.version = '1.0.0';
+    this.description = 'MCP (Model Context Protocol) 执行器';
+    this.priority = 11;
+    this.system = true;
+
+    this._framework = null;
+    // serverName -> { client, tools: [{ name, description, inputSchema }], toolObjects: { toolName: actualTool } }
+    this._clients = new Map();
+    this._config = config;
+  }
+
+  install(framework) {
+    this._framework = framework;
+    return this;
+  }
+
+  async start(framework) {
+    // 先连接所有 MCP 服务器
+    if (this._config.servers) {
+      for (const serverConfig of this._config.servers) {
+        await this.addServer(serverConfig);
+      }
+    }
+
+    // 注册 mcp_tool_schema 工具 - 直接返回可用的调用示例
+    framework.registerTool({
+      name: 'mcp_tool_schema',
+      description: '查询工具的调用示例，直接复制 example 或 fullExample 字段使用',
+      inputSchema: z.object({
+        server: z.string().describe('MCP 服务器名称'),
+        tool: z.string().describe('工具名称'),
+      }),
+      execute: async (args) => {
+        const { server, tool } = args;
+        const clientInfo = this._clients.get(server);
+        if (!clientInfo) {
+          return { success: false, error: `MCP server '${server}' not found` };
+        }
+
+        const toolInfo = clientInfo.tools.find((t) => t.name === tool);
+        if (!toolInfo) {
+          return { success: false, error: `Tool '${tool}' not found` };
+        }
+
+        const schema = this._extractSchema(toolInfo.inputSchema);
+        const props = schema.properties || {};
+        const required = schema.required || [];
+
+        // 生成示例值的辅助函数
+        const generateExample = (prop, depth = 0) => {
+          if (!prop) return null;
+          const type = prop.type || (prop.properties ? 'object' : 'string');
+
+          if (type === 'string') {
+            return prop.description?.split('.')[0] || `${prop.title || '值'}`;
+          } else if (type === 'number' || type === 'integer') {
+            return prop.default || 0;
+          } else if (type === 'boolean') {
+            return false;
+          } else if (type === 'array') {
+            // 数组类型：提供单个示例元素
+            if (prop.items) {
+              const itemExample = generateExample(prop.items, depth + 1);
+              return depth === 0 ? [itemExample] : itemExample;
+            }
+            return ['示例'];
+          } else if (type === 'object' || prop.properties) {
+            // 对象类型：递归生成嵌套结构
+            const obj = {};
+            const objProps = prop.properties || {};
+            for (const [key, val] of Object.entries(objProps)) {
+              obj[key] = generateExample(val, depth + 1);
+            }
+            return obj;
+          }
+          return null;
+        };
+
+        // 生成可直接使用的调用示例
+        const exampleArgs = {};
+        for (const key of required) {
+          const prop = props[key];
+          if (prop) {
+            exampleArgs[key] = generateExample(prop);
+          }
+        }
+
+        return {
+          success: true,
+          result: {
+            name: toolInfo.name,
+            description: toolInfo.description,
+            required,
+            // 各参数的详细说明
+            parameters: Object.fromEntries(
+              required.map((key) => [
+                key,
+                {
+                  type: props[key]?.type || 'string',
+                  description: props[key]?.description || '',
+                  example: generateExample(props[key]),
+                },
+              ])
+            ),
+            // 直接返回可以复制使用的调用示例
+            example: JSON.stringify(exampleArgs, null, 2),
+            fullExample: `mcp_call({ server: "${server}", tool: "${tool}", args_json: ${JSON.stringify(JSON.stringify(exampleArgs))} })`,
+          },
+        };
+      },
+    });
+
+    // 注册 mcp_call 工具
+    framework.registerTool({
+      name: 'mcp_call',
+      description:
+        '调用 MCP 服务器工具。args_json 是包含实际参数的 JSON 字符串，如 \'{"url": "https://news.baidu.com"}\'',
+      inputSchema: z.object({
+        server: z.string().describe('MCP 服务器名称'),
+        tool: z.string().describe('工具名称'),
+        args_json: z
+          .string()
+          .describe('参数 JSON 字符串，如 {"url": "https://..."}，fetch 工具必填 url'),
+      }),
+      execute: async (args) => {
+        const { server, tool, args_json } = args;
+        log.info(` mcp_call: server=${server}, tool=${tool}, args_json=${args_json}`);
+
+        const clientInfo = this._clients.get(server);
+        if (!clientInfo) {
+          return { success: false, error: `MCP server '${server}' not found` };
+        }
+
+        // 解析 args_json
+        let finalArgs = {};
+        if (args_json) {
+          try {
+            finalArgs = JSON.parse(args_json);
+          } catch (e) {
+            return { success: false, error: `args_json 格式错误，不是有效的 JSON: ${args_json}` };
+          }
+        }
+
+        // 检查参数是否为空
+        if (!finalArgs || Object.keys(finalArgs).length === 0) {
+          const toolInfo = clientInfo.tools.find((t) => t.name === tool);
+          if (toolInfo) {
+            const schema = this._extractSchema(toolInfo.inputSchema);
+            const required = schema.required || [];
+            return {
+              success: false,
+              error: `参数为空！必须提供: ${required.join(', ')}`,
+              hint: `正确格式: {"${required[0]}": "具体值"}`,
+            };
+          }
+        }
+
+        try {
+          // 使用缓存的工具对象
+          const mcpTool = clientInfo.toolObjects?.[tool];
+          if (!mcpTool) {
+            return { success: false, error: `Tool '${tool}' not found on server '${server}'` };
+          }
+          const execResult = await mcpTool.execute(finalArgs);
+          return { success: true, result: execResult };
+        } catch (err) {
+          log.error(` Tool '${tool}' failed:`, err.message);
+          return { success: false, error: err.message };
+        }
+      },
+    });
+
+    // 注册 mcp_list_servers 工具
+    framework.registerTool({
+      name: 'mcp_list_servers',
+      description: '列出已连接的 MCP 服务器及其工具',
+      inputSchema: z.object({}),
+      execute: async () => {
+        const servers = [];
+        for (const [name, info] of this._clients) {
+          servers.push({
+            name,
+            tools: info.tools.map((t) => ({ name: t.name, description: t.description })),
+          });
+        }
+        return { success: true, servers };
+      },
+    });
+
+    // 注册 mcp_reload 工具
+    framework.registerTool({
+      name: 'mcp_reload',
+      description:
+        '重新加载 MCP 服务器配置。当配置文件 .agent/mcp_config.json 修改后使用此工具重载配置',
+      inputSchema: z.object({}),
+      execute: async () => {
+        log.info(' mcp_reload called');
+        try {
+          const fs = require('fs');
+          const path = require('path');
+          const configPath = path.resolve('.agent/mcp_config.json');
+
+          log.info(' Reading config from:', configPath);
+          if (!fs.existsSync(configPath)) {
+            return { success: false, error: `配置文件不存在: ${configPath}` };
+          }
+
+          const configContent = fs.readFileSync(configPath, 'utf8');
+          const config = JSON.parse(configContent);
+          log.info(' Config loaded, reloading...');
+
+          await this.reloadConfig(config);
+          log.info(' Reload complete');
+
+          return {
+            success: true,
+            message: 'MCP 配置已重载',
+            servers: Object.keys(config.mcpServers || {}),
+          };
+        } catch (err) {
+          log.error(' Reload error:', err);
+          return { success: false, error: `重载失败: ${err.message}` };
+        }
+      },
+    });
+
+    // 监听 agent 创建事件，附加 MCP 信息到系统提示词
+    framework.on('agent:created', (agent) => {
+      if (!this._mainAgent) {
+        this._mainAgent = agent;
+      }
+      this._refreshAgentMCPPrompt(agent);
+    });
+
+    // 等待框架就绪后，刷新所有已有 agent 的 MCP 提示词
+    if (framework._ready) {
+      this._refreshAllAgentsMCPPrompt(framework);
+    } else {
+      framework.once('framework:ready', () => {
+        this._refreshAllAgentsMCPPrompt(framework);
+      });
+    }
+
+    return this;
+  }
+
+  /**
+   * 刷新所有 agent 的 MCP 提示词（包括子 agent）
+   */
+  _refreshAllAgentsMCPPrompt(framework) {
+    const visited = new Set();
+
+    const traverse = (agent) => {
+      if (!agent || visited.has(agent)) return;
+      visited.add(agent);
+      this._refreshAgentMCPPrompt(agent);
+
+      // 递归处理子 agent
+      const subAgents = agent.getSubAgents?.() || agent._subAgents || new Map();
+      for (const [name, subAgentInfo] of subAgents) {
+        traverse(subAgentInfo.agent);
+      }
+    };
+
+    for (const agent of framework._agents || []) {
+      traverse(agent);
+    }
+  }
+
+  /**
+   * 刷新单个 agent 的 MCP 提示词
+   */
+  _refreshAgentMCPPrompt(agent) {
+    // 检查是否已刷新过（通过检查系统提示词是否已包含 MCP 描述）
+    const existingPrompt = agent._originalPrompt || '';
+    if (existingPrompt.includes('[MCP Servers]')) {
+      return;
+    }
+
+    const mcpDesc = this._buildMCPServersDescription();
+    if (!mcpDesc) return;
+
+    // 将 MCP 描述追加到系统提示词
+    agent.setSystemPrompt(existingPrompt + '\n\n' + mcpDesc);
+  }
+
+  /**
+   * 从 inputSchema 中提取实际 schema
+   */
+  _extractSchema(inputSchema) {
+    if (!inputSchema) return {};
+    // 处理 {jsonSchema: {...}} 格式
+    if (inputSchema.jsonSchema) return inputSchema.jsonSchema;
+    // 处理直接是 schema 的格式
+    return inputSchema;
+  }
+
+  /**
+   * 构建 MCP 服务器描述
+   */
+  _buildMCPServersDescription() {
+    if (this._clients.size === 0) {
+      return '';
+    }
+
+    let desc = '【MCP Servers - 可用工具服务】\n';
+    desc += '你可以通过 mcp_call 工具调用以下 MCP 服务器的工具。\n\n';
+
+    for (const [serverName, info] of this._clients) {
+      desc += `【${serverName}】\n`;
+      for (const tool of info.tools) {
+        const schema = this._extractSchema(tool.inputSchema);
+        const props = schema.properties || {};
+        const required = schema.required || [];
+
+        // 简化参数列表
+        let paramStr = '';
+        if (Object.keys(props).length > 0) {
+          const params = Object.entries(props).map(([key, prop]) => {
+            const isRequired = required.includes(key);
+            return `${key}${isRequired ? '(必填)' : ''}`;
+          });
+          paramStr = ` 参数: ${params.join(', ')}`;
+        }
+
+        // 截取描述的第一句
+        const shortDesc = tool.description?.split('.')[0] || '无描述';
+        desc += `- ${tool.name}: ${shortDesc}${paramStr}\n`;
+      }
+      desc += '\n';
+    }
+
+    desc +=
+      '调用格式：mcp_call({ server: "服务器", tool: "工具", args_json: \'{"参数": "值"}\' })\n';
+    desc += '复杂参数时先用 mcp_tool_schema 查询完整参数结构\n';
+    return desc.trim();
+  }
+
+  _getParentAgent() {
+    // 优先返回已缓存的主 agent
+    if (this._mainAgent) {
+      return this._mainAgent;
+    }
+
+    // 尝试从 framework 获取
+    if (this._framework._mainAgent) {
+      this._mainAgent = this._framework._mainAgent;
+      return this._mainAgent;
+    }
+
+    // 查找最后一个创建的 agent 作为父 agent
+    const agents = this._framework._agents || [];
+    if (agents.length > 0) {
+      this._mainAgent = agents[agents.length - 1];
+      return this._mainAgent;
+    }
+
+    return null;
+  }
+
+  /**
+   * 带超时的 Promise
+   */
+  _withTimeout(promise, ms, name) {
+    return Promise.race([
+      promise,
+      new Promise((_, reject) =>
+        setTimeout(() => reject(new Error(`${name} timeout (${ms}ms)`)), ms)
+      ),
+    ]);
+  }
+
+  /**
+   * 添加 MCP 服务器
+   */
+  async addServer(config) {
+    const { name, command, args = [], env, url, type, headers = {}, authProvider } = config;
+    if (this._clients.has(name)) {
+      log.warn(` Server '${name}' already exists, skipping`);
+      return;
+    }
+    log.info(` Connecting to ${name}...`);
+    let client;
+    try {
+      if (['sse', 'http'].includes(type)) {
+        client = await this._withTimeout(
+          createMCPClient({
+            transport: {
+              type: type,
+              url: url,
+              headers: headers,
+              authProvider: authProvider,
+              redirect: 'error',
+              env: env,
+            },
+          }),
+          10000,
+          `createMCPClient ${name}`
+        );
+      } else {
+        client = await this._withTimeout(
+          createMCPClient({
+            transport: new StdioClientTransport({
+              command: command,
+              args: args,
+              env: env,
+            }),
+          }),
+          10000,
+          `createMCPClient ${name}`
+        );
+      }
+    } catch (err) {
+      log.error(` Failed to create client '${name}':`, err.message);
+      return;
+    }
+
+    // 获取 MCP 服务器的工具列表
+    let mcpTools;
+    try {
+      mcpTools = await this._withTimeout(client.tools(), 10000, `client.tools ${name}`);
+    } catch (err) {
+      log.error(` Failed to get tools from '${name}':`, err.message);
+      return;
+    }
+
+    // 提取工具信息和实际工具对象
+    const toolsInfo = [];
+    const toolObjects = {}; // 缓存实际工具对象
+    if (mcpTools && typeof mcpTools === 'object') {
+      for (const [toolName, tool] of Object.entries(mcpTools)) {
+        if (!tool) continue;
+        toolObjects[toolName] = tool; // 保存实际工具对象
+        toolsInfo.push({
+          name: toolName,
+          description: tool.description || '',
+          inputSchema: tool.inputSchema || {},
+        });
+      }
+    }
+
+    // 保存客户端、工具信息和实际工具对象
+    this._clients.set(name, {
+      client,
+      tools: toolsInfo,
+      toolObjects, // 实际工具对象，供 mcp_call 直接调用
+    });
+
+    log.info(` Added server '${name}' with ${toolsInfo.length} tools`);
+  }
+
+  /**
+   * 移除 MCP 服务器
+   */
+  async removeServer(name) {
+    const clientInfo = this._clients.get(name);
+    if (clientInfo) {
+      try {
+        // 添加超时保护，避免 close/destroy 阻塞
+        const closePromise = clientInfo.client.close?.() || clientInfo.client.destroy?.();
+        if (closePromise && typeof closePromise.then === 'function') {
+          await Promise.race([
+            closePromise,
+            new Promise((resolve) => setTimeout(() => resolve(), 3000)),
+          ]);
+        }
+      } catch (e) {
+        // ignore
+      }
+      this._clients.delete(name);
+    }
+  }
+
+  /**
+   * 获取所有服务器
+   */
+  getServers() {
+    return Array.from(this._clients.entries()).map(([name, info]) => ({
+      name,
+      tools: info.tools.map((t) => t.name),
+    }));
+  }
+
+  reload(framework) {
+    log.info(' Reloading...');
+    this._framework = framework;
+  }
+
+  /**
+   * 重新加载 MCP 配置
+   * @param {Object} config - 新的配置对象，包含 mcpServers
+   */
+  async reloadConfig(config) {
+    log.info(' reloadConfig start');
+    const newServers = config?.mcpServers || {};
+
+    // 1. 先快速清理所有旧服务器（不等待 close 完成）
+    log.info(' Clearing old servers...');
+    for (const [name, clientInfo] of this._clients) {
+      try {
+        // 不等待 close，直接删除
+        clientInfo.client.close?.()?.catch?.(() => {});
+      } catch (e) {}
+    }
+    this._clients.clear();
+
+    // 2. 并行添加新服务器
+    log.info(' Adding new servers...');
+    const addPromises = Object.entries(newServers).map(async ([name, serverConfig]) => {
+      const normalizedConfig = {
+        name,
+        type: serverConfig.type,
+        url: serverConfig.url,
+        headers: serverConfig.headers,
+        authProvider: serverConfig.authProvider,
+        command: serverConfig.command,
+        args: serverConfig.args,
+        env: serverConfig.env,
+      };
+      await this.addServer(normalizedConfig);
+    });
+
+    await Promise.all(addPromises);
+    log.info(' reloadConfig complete');
+
+    // 3. 刷新所有 agent 的 MCP 提示词
+    if (this._framework) {
+      this._refreshAllAgentsMCPPrompt(this._framework);
+    }
+  }
+
+  async uninstall(framework) {
+    // 断开所有 MCP 连接
+    for (const [name, clientInfo] of this._clients) {
+      try {
+        (await clientInfo.client.close?.()) || clientInfo.client.destroy?.();
+      } catch (e) {
+        // ignore
+      }
+    }
+    this._clients.clear();
+    this._framework = null;
+  }
+}
+
+module.exports = {
+  MCPExecutorPlugin,
+  MCPClientWrapper,
+};