ChatDev 2.0 DevAll MCP Tooling 实战指南Remote HTTP 与 Local stdio 双模式配置、FastMCP 集成与安全运维【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev本篇技术指南以 MCP Tooling 指南 为骨架系统讲解 ChatDev 2.0DevAll中 MCPModel Context Protocol工具绑定的完整配置体系mcp_remoteHTTP 远端与mcp_localstdio 本地进程两种模式、McpRemoteConfig/McpLocalConfig全部字段、FastMCP 示例服务器的搭建与接入以及安全、运维与调试的落地实践。读完本文你将能够在 YAML 工作流中为 Agent 节点接入任意标准 MCP 服务并理解工具清单加载、进程生命周期与结果归一化的底层实现。1. 双模式总览Remote (HTTP) 与 Local (stdio)MCP 工具在 DevAll 中被明确拆分为两种模式分别对应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等进程字段两种模式的取舍很清晰Remote 适合已上线、可被多个客户端共享的服务端点Local 适合需要拉起本地进程、与宿主机工具如 Blender直接交互的场景。在 Tooling 模块总览docs/user_guide/zh/modules/tooling/README.md中二者的定位进一步被区分为直连 HTTP 服务与拉起本地进程并通过 stdio 连接。从配置模型上看ToolingConfig的type字段通过tooling_type_registry注册表路由到对应的配置类——目前注册了function、mcp_remote、mcp_local三类见 entity/configs/node/tooling.py#L568-L582。type的枚举选项与描述会动态注入到配置 schema 中这意味着你在 Web UI 配置表单里看到的选项与 YAML 解析器接受的取值完全一致。2. McpRemoteConfig接入 HTTP(S) 远端 MCP 服务器2.1 字段说明字段说明server必填MCP HTTP(S) 端点例如https://api.example.com/mcp。headers可选附加 HTTP 头如Authorization。timeout可选单次工具调用超时时间秒。除上述文档字段外从源码 entity/configs/node/tooling.py#L310-L422 可以看到McpRemoteConfig还定义了以下高级字段cache_ttl工具清单缓存秒数默认0.0schema 描述为0 表示禁用缓存以便热更新。tool_sources仅包含meta.source命中列表的 MCP 工具省略时默认值为[mcp_tools]。2.2 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注意tooling在节点配置中是一个列表可同时挂载多个工具源每个条目包含type、config以及可选的prefix用于给该源的所有工具加前缀避免多源工具名冲突详见第 5 节。DevAll 会在列举/调用工具时连接该 URL并携带headers。若服务器不可达将直接抛出错误不再尝试本地回退——这是 Remote 模式与自动发现工具之间的明确契约。2.3 底层调用链工具清单的抓取实现在 runtime/node/agent/tool/tool_manager.py#L65-L91 的_fetch_mcp_tools_http使用 FastMCP 的StreamableHttpTransport建立 HTTP 传输headers会原样透传给每次请求未显式配置timeout时使用默认值DEFAULT_MCP_HTTP_TIMEOUT 10.0秒内置3 次重试重试间隔呈指数退避0.5s → 1s → 2s全部失败后抛出最后一次异常。工具清单抓取后缓存在_mcp_tool_cache中缓存键由cache_key()生成其载荷为server、排序后的headers与timeout的哈希见 entity/configs/node/tooling.py#L416-L422。也就是说只要这三者不变同一远端服务器不会重复握手。3. McpLocalConfig拉起本地 stdio MCP 进程3.1 字段说明mcp_local直接在config下声明进程参数command/args可执行文件与参数如uvx blender-mcp。cwd可选工作目录。env/inherit_env定制子进程环境默认继承父进程后再覆盖。startup_timeout等待wait_for_log命中的最长秒数。wait_for_logstdout 正则用于判定就绪。从源码 entity/configs/node/tooling.py#L425-L566 可以看到McpLocalConfig的默认值与校验规则args默认空列表且每一项必须是字符串inherit_env默认True若设为False子进程将以空环境启动仅在env中注入显式声明的变量实现见 tool_manager.py#L507-L518 的_StdioClientWrapperos.environ.copy() if config.inherit_env else {}再用config.env覆盖startup_timeout默认10.0秒另有cache_ttl字段语义与 Remote 一致。3.2 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运行期间 DevAll 会保持该进程常驻并通过 stdio 传输 MCP 数据帧。这在仓库的 3D 生成工作流中有真实落地案例yaml_instance/blender_3d_builder_simple.yaml#L219-L224 中的Procedural Architect与Reviewer节点都通过mcp_localuvx blender-mcp直接驱动本机 Blender。3.3 进程生命周期实现_StdioClientWrapperruntime/node/agent/tool/tool_manager.py#L507-L558是 Local 模式的核心StdioTransport以keep_aliveTrue建立传输客户端按launch_key由command/args/cwd/env/inherit_env/startup_timeout/wait_for_log计算见 tooling.py#L556-L566缓存在_mcp_stdio_clients中同一配置复用同一子进程每个 stdio 客户端在独立 daemon 线程中运行自己的 asyncio 事件循环list_tools/call_tool通过run_coroutine_threadsafe投递到该循环执行并用asyncio.Lock串行化调用进程终止由 DevAll 负责close()会向事件循环投递关闭协程并回收线程因此本地脚本必须能正确处理SIGTERM/SIGKILL避免留下僵尸进程或未落盘数据。4. FastMCP 示例服务器一键起一个 MCP 服务仓库自带一个极简的 FastMCP 示例服务器 mcp_example/mcp_server.pyfrom 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 8010接入方式有两种以 Remote 模式使用只需将server指向http://127.0.0.1:8010/mcp以 Local 模式使用可将command设置为uv run fastmcp run ...并保持transportstdiofastmcp run默认即 stdio 传输。一个与上文配套的完整 Remote 工作流示例是 yaml_instance/demo_mcp.yaml节点 A诗人通过mcp_remote挂载http://127.0.0.1:8001/mcp上的rand_num工具获取随机数并据此写诗节点 B评论家对诗歌进行批评分析两个节点通过edges串联。该示例同时展示了 MCP 工具与 LLM 角色分工的组合方式——把取数这类确定性操作外包给 MCP 工具让 Agent 专注于创作与推理。5. 工具清单与执行链路从 YAML 到 LLM 工具调用的源码路径5.1 配置解析YAML 中的tooling列表会被解析为ToolingConfigentity/configs/node/tooling.py#L585-L660依据type从tooling_type_registry取得对应配置类缺失config块或type非法时抛出ConfigErrorprefix可选——若多个工具源出现重名工具ToolManager会在构建 spec 时检测重复并抛出错误提示请使用唯一prefixtool_manager.py#L127-L143最终工具名形如mcp1_rand_num。5.2 工具清单spec构建get_tool_specstool_manager.py#L97-L145按类型分发mcp_remote→_build_mcp_remote_specs抓取远端工具列表将每个工具的name、description、inputSchema转换为 Provider 无关的ToolSpec并在元数据中记录source: mcp、server与mode: remotemcp_local→_build_mcp_local_specs走 stdio 客户端list_tools()元数据记录mode: local。这些 spec 最终注入到 LLM 的函数调用 schema 中由模型自主决定何时调用哪个工具。5.3 工具执行与结果归一化execute_tooltool_manager.py#L147-L174按类型分发到_execute_mcp_remote_tool/_execute_mcp_local_tool。值得关注的是返回值的归一化处理_normalize_mcp_result与_convert_mcp_content_to_blockstool_manager.py#L308-L423文本内容TextContent→ 直接转为文本消息块图片 / 音频ImageContent/AudioContent→ base64 解码后注册为附件依赖tool_context中的AttachmentStore即 utils/attachments.py生成带 mime 类型的附件消息块内嵌资源EmbeddedResource→ 文本资源保留 URI 与 mime 类型Blob 资源按 mime 推断为图片/音频/视频/文件资源链接ResourceLink→ 转为带 URI 的数据块。这意味着 MCP 服务器返回的富媒体结果如 Blender 渲染截图、音频片段可以无缝进入 Agent 的消息流与附件体系供后续节点或用户查看。6. 安全与运维实践网络暴露Remote 模式建议置于 HTTPS 反向代理之后并结合 API Key / ACLLocal 模式进程仍可访问宿主机文件请限制其权限例如以最小权限用户运行、避免cwd指向敏感目录。资源回收Local 模式由 DevAll 负责终止子进程务必确保脚本可以正确处理SIGTERM/SIGKILL及时清理临时文件与外部连接。日志定位为wait_for_log输出清晰的ready日志如示例中的Starting simple MCP server...便于在超时时快速排查是进程未启动、还是就绪判定失败。鉴权Remote 模式通过headers传递 Token如Authorization: Bearer ${MY_MCP_TOKEN}Local 模式可在env中注入密钥注意不要将密钥写入仓库——仓库采用环境变量占位符如${REPO_ROOT}、${API_KEY}的惯例可参考 yaml_instance/demo_mcp.yaml 与 utils/env_loader.py。多会话MCP 服务若不支持多客户端可在模型或工具层设置max_concurrency1并在 YAML 中复用同一配置——结合上文提到的 stdio 客户端按launch_key复用机制多个节点共享同一个本地进程可避免重复拉起。7. 调试步骤端点自检Remote 模式用 curl 或fastmcp client测试 HTTP 端点Local 模式先单独运行可执行文件确认 stdout 中出现与wait_for_log匹配的文本。启动观察启动 DevAll可加--reload观察后端日志是否打印工具清单——工具发现失败通常发生在这一阶段错误信息会直接指向握手失败原因。调用追踪若调用失败查看 Web UI 中的工具请求/响应或在logs/中搜索对应 session 的结构化日志核对是传输层错误、鉴权失败还是工具参数 schema 不匹配。8. 小结MCP Tooling 是 DevAll 连接外部工具生态的桥梁mcp_remote面向已部署的 HTTP(S) 服务配置简洁、共享方便mcp_local面向本地进程通过 stdio 常驻连接实现与 Blender 等桌面工具的深度集成。理解McpRemoteConfig/McpLocalConfig的字段语义、工具清单缓存与结果归一化机制是写出可上线、可排障的 Agent 工作流的前提。相关配置模型的完整定义可进一步查阅 entity/configs/node/tooling.py 与 runtime/node/agent/tool/tool_manager.py实战示例则见 yaml_instance/demo_mcp.yaml 与 yaml_instance/blender_3d_builder_simple.yaml。【免费下载链接】ChatDevChatDev 2.0: Dev All through LLM-powered Multi-Agent Collaboration项目地址: https://gitcode.com/GitHub_Trending/ch/ChatDev创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考