OpenJarvis 外部 MCP 服务器集成实战：从 Home Assistant 到本地 Stdio 工具

【免费下载链接】OpenJarvisPersonal AI, On Personal Devices项目地址https://gitcode.com/gh_mirrors/op/OpenJarvis点击查看免费下载本指南围绕 OpenJarvis 的[tools.mcp]配置完整讲解如何将外部 Model Context ProtocolMCP服务器接入 Agent使其工具如 Home Assistant 的实体控制、数据库查询、自定义 CLI 服务无需编写一行自定义工具代码即可被调用。读完你将掌握config.toml的完整配置语法、Streamable HTTP 与 Stdio 两种传输的选型、include/exclude 工具过滤以及基于源码层面的错误处理与故障排查方法。为什么需要外部 MCP 服务器OpenJarvis 的内置工具覆盖了文件读写、代码执行、网络搜索等通用能力但真实场景中 Agent 往往需要访问私有的、领域特定的能力家里的智能家居设备、业务数据库、公司内部 API。传统做法是为每种服务编写自定义工具代码并重新发布维护成本高、扩展性差。MCP 提供了一条标准化的接入路径只要目标服务实现了 MCP 协议暴露tools/list与tools/callOpenJarvis 就能在启动时自动发现其工具并把它们包装成与内置工具完全同构的BaseTool让 Agent 以一致的方式调用——without writing custom tool code 正是该机制的核心价值。整个接入链路沉淀在src/openjarvis/mcp/目录下由客户端client.py、传输层transport.py、配置解析loader.py和协议封装protocol.py四个模块协作完成。工作原理一次完整的加载流程当 OpenJarvis 启动时会读取config.toml中的[tools.mcp]段对每个配置的服务器依次执行四个步骤建立连接根据服务器对象中提供的url或command字段选择对应的传输层——url走 Streamable HTTPcommand走 Stdio子进程。这一分流逻辑见 loader.pyif url: transport StreamableHTTPTransport(urlurl, tokentoken) elif command: transport StdioTransport(command[command] args)initialize 握手客户端以协议版本2025-03-26、clientInfo为openjarvis/0.1.0发送initialize请求随后按 MCP 规范补发notifications/initialized通知实现协议版本协商见 client.py。发现工具调用tools/list获取服务器暴露的工具清单每个工具依据其inputSchema生成一个ToolSpec。值得注意的实现细节是MCP 工具默认被赋予600 秒的超时上限而非通用的 30 秒因为 MCP 工具常包装扫描、pentest 等长耗时命令见 client.py。包装为 BaseTool通过MCPToolProvider.discover()将每个工具规格实例化为MCPToolAdapter使其被ToolExecutor当作普通内置工具调度执行见 mcp_adapter.py。整个加载过程遵循单点失败隔离原则某个服务器不可达或报错时仅记录一条 warning 并跳过该服务器其余服务器和内置工具照常加载。这一best-effort batch策略在 loader.py 中通过 per-server 的异常捕获实现。配置两种 servers 写法外部 MCP 服务器统一配置在config.toml的[tools.mcp]段下默认配置文件示例见 config.toml。servers字段接受两种形式内联 JSON 字符串或JSON 文件路径。内联 JSON 字符串适合服务器数量少、配置简短的场景[tools.mcp] enabled true servers [{name: homeassistant, url: http://172.16.3.1:9583/private_abc123}]⚠️关键易错点内联值必须是JSON 编码的字符串用 TOML 的单引号包裹而不是原生的 TOML 数组。在src/openjarvis/core/config.py的MCPConfig数据类中servers字段的类型就是str见 config.py这从类型层面强制了字符串这一形态。JSON 文件路径配置规模较大时把服务器对象放入与config.toml同目录的独立文件servers写文件名字符串[tools.mcp] enabled true servers mcp-servers.json[ { name: homeassistant, url: http://172.16.3.1:9583/private_abc123 }, { name: database, command: db-mcp-server, args: [--db, postgres://localhost/mydb] } ]文件解析规则路径解析逻辑在 config.py 的resolve_json_or_file中实现几条硬性约束值得注意相对路径以 config.toml 所在目录为基准且不得逃逸出该目录——若../越界会直接抛出ValueError安全约束防止配置引用任意文件绝对路径包括由~展开的路径同样受支持文件大小上限为 4 MiB超出即拒绝文件内容可以是服务器对象数组也可以是单个对象——单个对象会被自动包装成数组见resolve_mcp_serversconfig.py文件中的每个条目允许是字符串形式的 JSON 对象解析时统一转为 dict。服务器字段 Schema每个服务器对象支持以下字段字段类型必填说明namestring否日志中显示的可读名称缺省为unnamedurlstring否*Streamable HTTP 传输的服务器 URLcommandstring否*启动 stdio 型 MCP 服务器的命令argslist of strings否传给 stdio 命令的参数列表tokenstring否认证令牌通过Authorization: Bearer token头发送源码支持见 transport.pyinclude_toolslist of strings否工具白名单只加载列出的工具exclude_toolslist of strings否工具黑名单跳过列出的工具*url与command二选一必须提供一个。两者都缺失时该服务器被跳过并记录 warning见 loader.py。过滤顺序当include_tools与exclude_tools同时存在时先应用白名单、再用黑名单过滤。源码中的实现顺序与此一致loader.py。此外调用方还可以通过allowed_names传入外层过滤集例如 CLI 的--tools作用域在内层过滤之后再叠加一次。补充字段表中未列出的token字段在源码中确实生效。若服务器要求鉴权如 Home Assistant 的 MCP 插件在服务器对象中加token: your_token即可空字符串或不设置则不会发送 Authorization 头。实战示例Home Assistant 通过 Streamable HTTP 接入连接 Home Assistant 的 MCP 插件[tools.mcp] enabled true servers [{name: homeassistant, url: http://172.16.3.1:9583/private_abc123}]启动后自动发现全部 HA 工具实体控制、自动化、历史查询等并开放给 Agent。若插件要求令牌追加token: xxx字段即可。Stdio 本地服务器以子进程方式启动本地 MCP 服务器[tools.mcp] enabled true servers [{name: myserver, command: python, args: [-m, my_mcp_server]}]OpenJarvis 自动拉起进程通过 stdin/stdout 上的 JSON-RPC 行协议通信并在关闭时终止该进程。StdioTransport的实现细节包括独立线程持续排空 stderr防止子进程写满管道后阻塞 stdout 应答、专用 reader 线程读取 stdout、以及按请求 id 关联响应忽略无关的噪音行见 transport.py。多服务器并存[tools.mcp] enabled true servers [{name: homeassistant, url: http://172.16.3.1:9583/private_abc123}, {name: database, command: db-mcp-server, args: [--db, postgres://localhost/mydb]}]工具过滤服务器暴露工具过多时用白名单精简[tools.mcp] enabled true servers [{name: ha, url: http://172.16.3.1:9583/private_abc123, include_tools: [hassTurnOn, hassTurnOff, hassGetState]}]只想排除个别危险操作时用黑名单[tools.mcp] enabled true servers [{name: ha, url: http://172.16.3.1:9583/private_abc123, exclude_tools: [hassCreateBackup, hassDeleteBackup]}]两种传输类型选型Streamable HTTPurl字段基于httpx的持久会话发送 JSON-RPC 请求严格按照 MCP Streamable HTTP 规范全程追踪Mcp-Session-Id响应头并回传见 transport.py兼容服务器返回application/json或text/event-stream两种响应体SSE 场景自动提取最后一条data:行中的 JSON-RPC 载荷见 transport.py连接超时 10 秒请求超时 60 秒。适用场景远程 MCP 服务器、以 HTTP 端点运行的服务Home Assistant MCP 插件、云端托管 MCP 服务器。Stdiocommand字段以子进程方式运行命令通过 stdin/stdout 交换 JSON-RPC 行。默认响应超时为 600 秒。适用场景以 CLI 工具形式分发的本地 MCP 服务器、开发测试、需要访问本机文件系统的服务器。兼容性说明SSETransport是StreamableHTTPTransport的向后兼容别名两者指向同一实现见 transport.py。错误处理与容错机制OpenJarvis 对 MCP 故障的容忍度设计如下故障场景行为服务器不可达记录 warning 并跳过该服务器其余服务器与内置工具正常加载请求超时HTTP 请求 60 秒超时超时后跳过该服务器并告警配置非法serversJSON 解析失败、或条目缺url/command记录 warning 并跳过该条目工具发现失败tools/list异常被捕获跳过该服务器运行时调用失败返回successFalse的ToolResult并携带错误消息见 mcp_adapter.py需要特别强调的生命周期约束load_mcp_tools_from_config返回(tools, clients)二元组调用方必须持有clients引用建议挂在 Agent 实例上否则 MCP 传输会话会被垃圾回收、底层连接在调用中途关闭——这一坑在loader.py的模块文档中被明确标注见 loader.py。故障排查清单服务器未被发现确认[tools.mcp]下enabled true校验内联serversJSON 是否合法或 JSON 文件是否存在可读——最常见的错误是用 TOML 数组代替 JSON 字符串查看 OpenJarvis 日志中的Failed to discover external MCP toolswarning。连接被拒 / 超时先确认服务器可达curl -v http://host:port/检查 OpenJarvis 主机与 MCP 服务器之间的防火墙规则Docker 部署时确保两个容器在同一网络或使用宿主机 IP。工具不出现开启 debug 日志观察实际发现了哪些工具检查include_tools/exclude_tools过滤是否过于严格确认 MCP 服务器确实通过tools/list暴露了工具部分服务器只暴露 resources 或 prompts没有可调用的 tool。Stdio 服务器立即崩溃手动运行命令验证python -m my_mcp_server应启动并等待 stdin 输入检查 OpenJarvis 日志中透传的 stderr 输出_drain_stderr会以[cmd stderr]前缀记录确保 MCP 服务器的依赖已安装在同一个 Python 环境中。测试与验证用测试用例加深理解仓库在tests/mcp/下提供了覆盖完整的测试集是理解行为边界的绝佳教材test_discovery.py验证url配置走 HTTP 传输、command配置走 Stdio 传输、include/exclude 过滤生效以及全局禁用 MCP 时不会触发发现test_loader.py验证 token 正确传给 HTTP 传输而不会误传给 stdio 服务器、allowed_names外层过滤、per-server 的 include/excludetest_streamable_http_transport.py覆盖Mcp-Session-Id首包缺失/后续回传、带/不带 token 的 Authorization 头行为、连接错误与超时错误的包装test_mcp_tools_matrix.py矩阵化验证各类工具可通过 MCP 被发现。如果希望自行接入一个外部 MCP 服务器做冒烟验证可参考 examples/mcp 目录下的相关示例以及docs/user-guide中工具系统的配套说明将外部能力快速纳入 Agent 的工具箱。赞分享【免费下载链接】OpenJarvisPersonal AI, On Personal Devices项目地址https://gitcode.com/gh_mirrors/op/OpenJarvis点击查看免费下载相关推荐OpenJarvis集成MCP外部服务器零代码扩展AI能力完整教程OpenJarvis集成MCP外部服务器零代码扩展AI能力完整教程 OpenJarvis 是一款运行在个人设备上的私人 AI 助手它支持集成 MCP 外部服Mastra Agent 接入 Hacker News MCP Server本地 stdio 工具集成实战Mastra Agent 接入 Hacker News MCP Server本地 stdio 工具集成实战 本文以 Mastra 官方课程「Agent Too后端音视频前端Refly MCP服务器集成如何连接外部工具和服务Refly MCP服务器集成如何连接外部工具和服务 Refly 是一款开源的AI原生创作引擎通过其直观的自由画布界面结合多线程对话、工件、AI知识库人工智能AI 应用大模型AI AgentAgent 工作流AI 技能RAG上一篇tinfoleak在数字取证中的应用证据收集与分析流程下一篇PDF补丁丁覆盖5个高频场景的免费PDF编辑与书签管理工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考