 与 Local(stdio) 双模式配置、源码原理与调试)
ChatDev 2.0 MCP 工具接入实战指南Remote(HTTP) 与 Local(stdio) 双模式配置、源码原理与调试【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/Dennis_Huang/ChatDev本篇技术指南系统讲解 ChatDev 2.0DevAll中 MCPModel Context Protocol工具的两种接入模式面向托管服务的mcp_remoteHTTP与面向本地可执行程序的mcp_localstdio。你将掌握两种模式的配置字段、完整 YAML 写法、FastMCP 示例服务器的启动与接入方式并深入到 tool_manager.py 与 tooling.py 的源码层理解工具发现、进程常驻、结果归一化等底层机制从而能在自己的多 Agent 工作流中快速接入 MCP 工具并排查问题。MCP Remote 模式配置界面MCP Local 模式配置界面1. 模式总览先选对mcp_remote还是mcp_localMCP 工具在 ChatDev 2.0 中被明确拆分为两种独立模式分别映射到tooling.type: mcp_remote与tooling.type: mcp_local。文档明确说明旧的type: mcpschema 已不再支持YAML 与文档中应全部迁移到新写法。模式Tooling type适用场景关键字段Remotemcp_remote已部署的 HTTP(S) MCP 服务器如 FastMCP、Claude Desktop Connector、自建网关server、headers、timeoutLocalmcp_local通过 stdio 握手的本地可执行程序Blender MCP、CLI 工具等command、args、cwd、env等进程字段从源码看这两种模式与本地函数工具type: function一起注册在 entity/configs/node/tooling.py 的tooling_type_registry中对应三种配置类FunctionToolConfig、McpRemoteConfig、McpLocalConfig。tooling.type的可选值由该注册表动态生成Web UI 下拉框中也会按注册元数据展示每种类型的简介。2. Remote(HTTP) 模式McpRemoteConfig字段详解mcp_remote适用于已托管在 HTTP(S) 端点上的 MCP 服务器。其配置类定义于 entity/configs/node/tooling.py字段说明server必填MCP HTTP(S) 端点例如https://api.example.com/mcp。headers可选附加 HTTP 请求头如Authorization以 key-value 映射形式给出。timeout可选单次工具调用超时时间秒。cache_ttl可选高级MCP 工具清单缓存秒数0表示关闭缓存以支持热更新。tool_sources可选高级仅保留meta.source在该列表中的 MCP 工具省略时默认[mcp_tools]。YAML 示例nodes: - id: remote_mcp type: agent config: tooling: type: mcp_remote config: server: https://mcp.mycompany.com/mcp headers: Authorization: Bearer ${MY_MCP_TOKEN} timeout: 15配置解析逻辑位于McpRemoteConfig.from_dictserver为必填字符串headers会被强制转换为Dict[str, str]timeout与cache_ttl必须是数值否则抛出ConfigError。仓库内的yaml_instance/demo_mcp.yaml就是一个完整的远程 MCP 用例其中server指向本机http://127.0.0.1:8001/mcpAgent 节点先调用 MCP 工具获取随机数再据此创作诗歌。底层调用链与失败语义在 runtime/node/agent/tool/tool_manager.py 中_fetch_mcp_tools_http使用fastmcp的StreamableHttpTransport建立连接并调用client.list_tools()拉取工具清单单次请求超时未显式配置时使用默认值DEFAULT_MCP_HTTP_TIMEOUT 10.0秒拉取工具清单会自动重试 3 次初始延迟 0.5 秒、指数退避0.5s → 1.0s若服务器最终不可达错误会被立即抛出——文档明确指出不存在本地回退no local fallback。工具执行路径_execute_mcp_remote_tool每次调用都会新建Client连接目标端点、携带配置的headers随后调用client.call_tool(tool_name, arguments)。也就是说Remote 模式是无状态、按请求建连的 HTTP 调用模型适合将鉴权与网络策略集中在网关一侧。3. Local(stdio) 模式McpLocalConfig字段详解mcp_local适用于本地可执行程序DevAll 会以子进程方式启动它并通过 stdio 传输 MCP 数据帧。配置类定义于 entity/configs/node/tooling.pycommand/args可执行文件与参数如uvx blender-mcp。command必填args为字符串列表默认为空。cwd可选工作目录。env/inherit_env定制子进程环境inherit_env默认为true表示先继承父进程环境再覆盖env中的条目。将inherit_env设为false则从空环境开始。startup_timeout等待wait_for_log命中的最长秒数默认10.0。wait_for_log对子进程 stdout 做正则匹配、用于判定“就绪”的日志模式。cache_ttl工具清单缓存秒数默认0不缓存。YAML 示例nodes: - id: local_mcp type: agent config: tooling: type: mcp_local config: command: uvx args: - blender-mcp cwd: ${REPO_ROOT} wait_for_log: MCP ready startup_timeout: 8进程常驻与线程模型mcp_local与 Remote 模式最大的不同在于进程生命周期管理。在 tool_manager.py 中_StdioClientWrapper为每个配置以其cache_key区分维护一个独立客户端使用StdioTransport(command..., args..., env..., cwd..., keep_aliveTrue)保持子进程常驻每个包装器创建独立的asyncio事件循环并运行在守护线程中初始化通过run_coroutine_threadsafe同步等待完成所有 list/call 操作通过asyncio.Lock串行化避免并发帧交错进程退出时由 DevAll 调用close()关闭客户端并回收线程。这与文档“运行期间 DevAll 会保持该进程常驻并通过 stdio 传输 MCP 数据帧”的描述完全对应。工具的本地模式也因此天然适合连接 Blender MCP 这类需要长连接的桌面软件——仓库中的 blender_3d_builder_hub.yaml 等真实工作流即采用uvx blender-mcp的本地模式接入。4. 外层ToolingConfigtype/config/prefix 与工具命名无论哪种模式tooling节点都统一由ToolingConfigentity/configs/node/tooling.py承载包含三个字段字段说明type工具适配器类型必须是tooling_type_registry中已注册的值function、mcp_remote、mcp_local等。config由所选类型校验的具体配置块必须提供。prefix可选为来自该工具源的所有工具名添加前缀避免命名冲突例如mcp1。prefix的作用在 tool_manager.py 的 get_tool_specs 中体现合并工具清单时会对最终名称做去重发现重复即抛出ConfigError并提示“请使用唯一的前缀”。当同一个工作流接入多个 MCP 服务器且可能存在同名工具时务必为每个工具源配置不同的prefix。5. FastMCP 示例服务器从零接入的最小闭环仓库提供了一开箱即用的示例服务器 mcp_example/mcp_server.py全文如下from fastmcp import FastMCP import random from datetime import datetime from typing import Dict, Optional # Initialize MCP server mcp FastMCP( Company Simple MCP Server, # api_route/mcp/, debugTrue ) mcp.tool def rand_num(a: int, b: int) - int: Generate a random number between a and b. num random.randint(a, b) print(num) return num if __name__ __main__: print(Starting simple MCP server...) print(Run with: uv run fastmcp run simple_server.py --transport streamable-http --port 8001) # mcp.run(transportstreamable-http, host127.0.0.1, port8001) mcp.run()启动命令uv run fastmcp run mcp_example/mcp_server.py --transport streamable-http --port 8010Remote 模式将server指向http://127.0.0.1:8010/mcp即可仓库示例demo_mcp.yaml使用 8001 端口可自行对齐。Local 模式将command设置为uv run fastmcp run ...的调用方式并保持transportstdio。值得注意仓库中的服务器脚本启动时会在 stdout 打印Starting simple MCP server...等就绪信息——这正是为wait_for_log准备的匹配目标。在本地模式接入时可以设置wait_for_log: Starting simple MCP serverDevAll 会等待该日志出现后才判定进程就绪并继续拉取工具清单。6. 从 MCP 结果到对话消息结果归一化机制MCP 工具可能返回文本、图片、音频、嵌入资源等多种内容块。ChatDev 2.0 在 tool_manager.py 中实现了完整的归一化链_normalize_mcp_result → _convert_mcp_content_to_blocksTextContent→ 文本块ImageContent/AudioContent→ base64 解码后经AttachmentStore落盘注册为图片/音频附件EmbeddedResourceTextResourceContents/BlobResourceContents→ 按 MIME 类型转成文本或二进制附件块ResourceLink→ 数据块保留 URI 与描述。二进制内容会按tool_name 块序号 MIME 推断的扩展名生成文件名元数据中记录source: mcp_tool与tool_name便于在 Web UI 工具追踪与结构化日志中回溯。没有AttachmentStore时则以占位文本说明二进制内容被省略保证消息流不中断。7. 安全与运维要点网络暴露Remote 模式应置于 HTTPS 反向代理之后并结合 API Key / ACL 鉴权Local 模式进程仍可访问宿主机文件系统请限制脚本运行权限并保持沙箱化。资源回收Local 模式子进程由 DevAll 负责终止务必确保脚本能优雅处理 SIGTERM/SIGKILL。日志定位为wait_for_log输出清晰的“ready”日志行便于超时时快速定位启动问题。鉴权Remote 模式通过headers传递 TokenLocal 模式可在env中注入密钥切勿把密钥提交进仓库。示例中${MY_MCP_TOKEN}、${REPO_ROOT}这类占位符由仓库的变量解析机制在加载时替换。多会话若 MCP 服务器是单租户不支持多客户端并发应限制并发如max_concurrency1并在 YAML 中复用同一份配置。8. 调试检查清单连通性先行Remote 模式用curl或fastmcp client探测 HTTP 端点Local 模式先手动运行二进制确认 stdout 中出现能被wait_for_log匹配的日志。启动 DevAll 观察工具发现可加--reload参数启动观察后端日志是否打印工具清单若拉取失败Remote 模式会重试 3 次后抛出错误Local 模式则会卡在startup_timeout后失败。调用失败排查在 Web UI 中查看工具请求/响应轨迹工具名前缀、source: mcp_tool元数据可辅助定位或在logs/下按 session 检索结构化日志。按上述顺序排查即可覆盖从“工具发现失败”到“工具调用结果异常”的绝大多数 MCP 接入问题。【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/Dennis_Huang/ChatDev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ChatDev 2.0 MCP 工具接入实战指南：Remote(HTTP) 与 Local(stdio) 双模式配置、源码原理与调试
ChatDev 2.0 MCP 工具接入实战指南Remote(HTTP) 与 Local(stdio) 双模式配置、源码原理与调试【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/Dennis_Huang/ChatDev本篇技术指南系统讲解 ChatDev 2.0DevAll中 MCPModel Context Protocol工具的两种接入模式面向托管服务的mcp_remoteHTTP与面向本地可执行程序的mcp_localstdio。你将掌握两种模式的配置字段、完整 YAML 写法、FastMCP 示例服务器的启动与接入方式并深入到 tool_manager.py 与 tooling.py 的源码层理解工具发现、进程常驻、结果归一化等底层机制从而能在自己的多 Agent 工作流中快速接入 MCP 工具并排查问题。MCP Remote 模式配置界面MCP Local 模式配置界面1. 模式总览先选对mcp_remote还是mcp_localMCP 工具在 ChatDev 2.0 中被明确拆分为两种独立模式分别映射到tooling.type: mcp_remote与tooling.type: mcp_local。文档明确说明旧的type: mcpschema 已不再支持YAML 与文档中应全部迁移到新写法。模式Tooling type适用场景关键字段Remotemcp_remote已部署的 HTTP(S) MCP 服务器如 FastMCP、Claude Desktop Connector、自建网关server、headers、timeoutLocalmcp_local通过 stdio 握手的本地可执行程序Blender MCP、CLI 工具等command、args、cwd、env等进程字段从源码看这两种模式与本地函数工具type: function一起注册在 entity/configs/node/tooling.py 的tooling_type_registry中对应三种配置类FunctionToolConfig、McpRemoteConfig、McpLocalConfig。tooling.type的可选值由该注册表动态生成Web UI 下拉框中也会按注册元数据展示每种类型的简介。2. Remote(HTTP) 模式McpRemoteConfig字段详解mcp_remote适用于已托管在 HTTP(S) 端点上的 MCP 服务器。其配置类定义于 entity/configs/node/tooling.py字段说明server必填MCP HTTP(S) 端点例如https://api.example.com/mcp。headers可选附加 HTTP 请求头如Authorization以 key-value 映射形式给出。timeout可选单次工具调用超时时间秒。cache_ttl可选高级MCP 工具清单缓存秒数0表示关闭缓存以支持热更新。tool_sources可选高级仅保留meta.source在该列表中的 MCP 工具省略时默认[mcp_tools]。YAML 示例nodes: - id: remote_mcp type: agent config: tooling: type: mcp_remote config: server: https://mcp.mycompany.com/mcp headers: Authorization: Bearer ${MY_MCP_TOKEN} timeout: 15配置解析逻辑位于McpRemoteConfig.from_dictserver为必填字符串headers会被强制转换为Dict[str, str]timeout与cache_ttl必须是数值否则抛出ConfigError。仓库内的yaml_instance/demo_mcp.yaml就是一个完整的远程 MCP 用例其中server指向本机http://127.0.0.1:8001/mcpAgent 节点先调用 MCP 工具获取随机数再据此创作诗歌。底层调用链与失败语义在 runtime/node/agent/tool/tool_manager.py 中_fetch_mcp_tools_http使用fastmcp的StreamableHttpTransport建立连接并调用client.list_tools()拉取工具清单单次请求超时未显式配置时使用默认值DEFAULT_MCP_HTTP_TIMEOUT 10.0秒拉取工具清单会自动重试 3 次初始延迟 0.5 秒、指数退避0.5s → 1.0s若服务器最终不可达错误会被立即抛出——文档明确指出不存在本地回退no local fallback。工具执行路径_execute_mcp_remote_tool每次调用都会新建Client连接目标端点、携带配置的headers随后调用client.call_tool(tool_name, arguments)。也就是说Remote 模式是无状态、按请求建连的 HTTP 调用模型适合将鉴权与网络策略集中在网关一侧。3. Local(stdio) 模式McpLocalConfig字段详解mcp_local适用于本地可执行程序DevAll 会以子进程方式启动它并通过 stdio 传输 MCP 数据帧。配置类定义于 entity/configs/node/tooling.pycommand/args可执行文件与参数如uvx blender-mcp。command必填args为字符串列表默认为空。cwd可选工作目录。env/inherit_env定制子进程环境inherit_env默认为true表示先继承父进程环境再覆盖env中的条目。将inherit_env设为false则从空环境开始。startup_timeout等待wait_for_log命中的最长秒数默认10.0。wait_for_log对子进程 stdout 做正则匹配、用于判定“就绪”的日志模式。cache_ttl工具清单缓存秒数默认0不缓存。YAML 示例nodes: - id: local_mcp type: agent config: tooling: type: mcp_local config: command: uvx args: - blender-mcp cwd: ${REPO_ROOT} wait_for_log: MCP ready startup_timeout: 8进程常驻与线程模型mcp_local与 Remote 模式最大的不同在于进程生命周期管理。在 tool_manager.py 中_StdioClientWrapper为每个配置以其cache_key区分维护一个独立客户端使用StdioTransport(command..., args..., env..., cwd..., keep_aliveTrue)保持子进程常驻每个包装器创建独立的asyncio事件循环并运行在守护线程中初始化通过run_coroutine_threadsafe同步等待完成所有 list/call 操作通过asyncio.Lock串行化避免并发帧交错进程退出时由 DevAll 调用close()关闭客户端并回收线程。这与文档“运行期间 DevAll 会保持该进程常驻并通过 stdio 传输 MCP 数据帧”的描述完全对应。工具的本地模式也因此天然适合连接 Blender MCP 这类需要长连接的桌面软件——仓库中的 blender_3d_builder_hub.yaml 等真实工作流即采用uvx blender-mcp的本地模式接入。4. 外层ToolingConfigtype/config/prefix 与工具命名无论哪种模式tooling节点都统一由ToolingConfigentity/configs/node/tooling.py承载包含三个字段字段说明type工具适配器类型必须是tooling_type_registry中已注册的值function、mcp_remote、mcp_local等。config由所选类型校验的具体配置块必须提供。prefix可选为来自该工具源的所有工具名添加前缀避免命名冲突例如mcp1。prefix的作用在 tool_manager.py 的 get_tool_specs 中体现合并工具清单时会对最终名称做去重发现重复即抛出ConfigError并提示“请使用唯一的前缀”。当同一个工作流接入多个 MCP 服务器且可能存在同名工具时务必为每个工具源配置不同的prefix。5. FastMCP 示例服务器从零接入的最小闭环仓库提供了一开箱即用的示例服务器 mcp_example/mcp_server.py全文如下from fastmcp import FastMCP import random from datetime import datetime from typing import Dict, Optional # Initialize MCP server mcp FastMCP( Company Simple MCP Server, # api_route/mcp/, debugTrue ) mcp.tool def rand_num(a: int, b: int) - int: Generate a random number between a and b. num random.randint(a, b) print(num) return num if __name__ __main__: print(Starting simple MCP server...) print(Run with: uv run fastmcp run simple_server.py --transport streamable-http --port 8001) # mcp.run(transportstreamable-http, host127.0.0.1, port8001) mcp.run()启动命令uv run fastmcp run mcp_example/mcp_server.py --transport streamable-http --port 8010Remote 模式将server指向http://127.0.0.1:8010/mcp即可仓库示例demo_mcp.yaml使用 8001 端口可自行对齐。Local 模式将command设置为uv run fastmcp run ...的调用方式并保持transportstdio。值得注意仓库中的服务器脚本启动时会在 stdout 打印Starting simple MCP server...等就绪信息——这正是为wait_for_log准备的匹配目标。在本地模式接入时可以设置wait_for_log: Starting simple MCP serverDevAll 会等待该日志出现后才判定进程就绪并继续拉取工具清单。6. 从 MCP 结果到对话消息结果归一化机制MCP 工具可能返回文本、图片、音频、嵌入资源等多种内容块。ChatDev 2.0 在 tool_manager.py 中实现了完整的归一化链_normalize_mcp_result → _convert_mcp_content_to_blocksTextContent→ 文本块ImageContent/AudioContent→ base64 解码后经AttachmentStore落盘注册为图片/音频附件EmbeddedResourceTextResourceContents/BlobResourceContents→ 按 MIME 类型转成文本或二进制附件块ResourceLink→ 数据块保留 URI 与描述。二进制内容会按tool_name 块序号 MIME 推断的扩展名生成文件名元数据中记录source: mcp_tool与tool_name便于在 Web UI 工具追踪与结构化日志中回溯。没有AttachmentStore时则以占位文本说明二进制内容被省略保证消息流不中断。7. 安全与运维要点网络暴露Remote 模式应置于 HTTPS 反向代理之后并结合 API Key / ACL 鉴权Local 模式进程仍可访问宿主机文件系统请限制脚本运行权限并保持沙箱化。资源回收Local 模式子进程由 DevAll 负责终止务必确保脚本能优雅处理 SIGTERM/SIGKILL。日志定位为wait_for_log输出清晰的“ready”日志行便于超时时快速定位启动问题。鉴权Remote 模式通过headers传递 TokenLocal 模式可在env中注入密钥切勿把密钥提交进仓库。示例中${MY_MCP_TOKEN}、${REPO_ROOT}这类占位符由仓库的变量解析机制在加载时替换。多会话若 MCP 服务器是单租户不支持多客户端并发应限制并发如max_concurrency1并在 YAML 中复用同一份配置。8. 调试检查清单连通性先行Remote 模式用curl或fastmcp client探测 HTTP 端点Local 模式先手动运行二进制确认 stdout 中出现能被wait_for_log匹配的日志。启动 DevAll 观察工具发现可加--reload参数启动观察后端日志是否打印工具清单若拉取失败Remote 模式会重试 3 次后抛出错误Local 模式则会卡在startup_timeout后失败。调用失败排查在 Web UI 中查看工具请求/响应轨迹工具名前缀、source: mcp_tool元数据可辅助定位或在logs/下按 session 检索结构化日志。按上述顺序排查即可覆盖从“工具发现失败”到“工具调用结果异常”的绝大多数 MCP 接入问题。【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/Dennis_Huang/ChatDev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考