OpenHuman MCP Registry 架构解析：从 Smithery 浏览到 Agent 工具暴露的完整链路

OpenHuman MCP Registry 架构解析从 Smithery 浏览到 Agent 工具暴露的完整链路【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman本指南以 OpenHuman 仓库中 mcp-registry.md 文档为主体结合 src/openhuman/mcp/registry/ 模块源码、配置定义与 RPC 处理器实现深入讲解 OpenHuman 中Model Context ProtocolMCP客户端支持中面向用户的动态部分如何在 Smithery 与官方 modelcontextprotocol 注册中心浏览 MCP 服务器、将安装选择持久化到 SQLite、监督本地子进程与 HTTP 远端连接的生命周期以及如何把已安装服务器的工具暴露给 Agent 的统一工具注册表。读完本文你将掌握 MCP Registry 的模块布局、双注册中心适配、安装/连接/重连/升级凭证的完整工作流以及其 RPC 命名空间与安全性设计。模块定位动态的、面向用户的 MCP 客户端半边OpenHuman 的 MCP 客户端支持被分为两半静态半边由 src/openhuman/mcp/config_servers/ 与 src/openhuman/mcp/http_client/ 组成提供 HTTP stdio 传输原语并读取config.toml中[[mcp_client.servers]]声明的静态服务器集合Agent 通过通用桥接工具访问这一集合。动态半边即本文主题src/openhuman/mcp/registry/Rust 模块路径为mcp_registry。它让用户浏览上游注册中心Smithery 与官方 modelcontextprotocol 注册中心、安装选中的服务器、把选择持久化到 SQLite并对以本地子进程或 HTTP 远端端点方式启动的服务器监督连接生命周期。已安装服务器的工具经由统一工具注册表crate::openhuman::tools::registry暴露给 Agent。该模块不携带任何传输实现——stdio 与 HTTP MCP 客户端原语都在兄弟模块mcp_client中这里只负责生命周期、调度、持久化与注册中心 HTTP 适配。命名注意重要Rust 模块路径是mcp_registry但 RPC 命名空间与磁盘上的 SQLite 文件名仍然是mcp_clients以保持与既有前端代码和用户存储状态的向后兼容。追踪调用点时请同时搜索两个名字。当前源码中mod.rs 的文档注释再次强调了这一点注册表本身已迁移到tinymcpcrate这里保留的是“属于这个应用”的部分。数据流总览原文档给出的架构流程如下┌───────────────────────────────────────────────┐ Registries ───► registries/ registry.rs (10-min SQLite cache)│ └────────────────────┬──────────────────────────┘ │ browse / install ▼ ┌──────────────────────┐ Frontend (Skills UI) ─►│ ops.rs / schemas.rs │ RPC controllers └──────────┬───────────┘ │ ▼ ┌──────────────────────┐ │ store.rs │ mcp_clients.db (SQLite) │ InstalledServer rows│ └──────────┬───────────┘ │ at boot ▼ ┌──────────────────────┐ │ boot.rs │ spawn_installed_servers └──────────┬───────────┘ │ for each local-spawn ▼ ┌──────────────────────┐ │ connections.rs │ wraps http_client:: │ (global registry) │ McpStdioClient └──────────┬───────────┘ │ surfaces tools to ▼ tool_registry (agents)服务器传输模型Stdio与HttpRemote一个InstalledServer携带一个transport: Transport判别器定义在types.rs共有两个变体Stdio由npx、uvx或直接二进制见types::CommandKind启动的本地子进程通过stdio JSON-RPC通信。HttpRemote { url }托管的服务器Smithery 列出的大多数服务器属于此类由mcp::http_client::McpHttpClient通过可流式 HTTP 拨号。connections.rs 中的connections模块按传输类型分派。值得强调的是手动安装对话框mcp_clients_install与设置代理路径mcp_setup_install_and_connect都通过setup_ops::pick_connection选择最佳连接优先级已发布的 stdio → 任意 stdio → 已发布的 http_remote → 任意 http_remote并用setup_ops::build_install_transport构建传输因此两条路径行为完全一致——也就是说HTTP-remote 列表不仅可以通过设置代理安装也能直接从 UI 安装。启动时生成spawn_installed_serversboot::spawn_installed_servers从bootstrap_core_runtime调用因此核心一启动所有已安装服务器就会立即被连接。源码中该函数的实现体现了两个关键设计绝不阻塞启动服务器连接失败只记录日志并被跳过tracing::warn!一个损坏的 MCP 安装不能阻止桌面应用启动。启动连接结束时记录connected/failed/skipped三组计数。生命周期日志生命周期日志订阅器bus::init与其他领域订阅器一起在register_domain_subscribers中注册使连接事件可被观察。模块布局每个文件的职责路径职责types.rs数据结构InstalledServer、McpTool、ConnStatus、Smithery DTO 等。当前源码中这些类型已迁移到tinymcp_bus契约并在mod.rs的types模块中按原路径重导出以保持调用方拼写不变store.rsSQLite 持久化mcp_clients.db对InstalledServer行做 CRUD。当前仅保留一个直通入口store::set_cached端到端测试播种上游响应缓存用registry.rs多注册中心调度registry_search并行扇出 合并、registry_get按来源前缀路由或首个命中registries/上游注册中心适配器Smitherysmithery.rs 官方 modelcontextprotocol 注册中心mcp_official.rs。每个都优先读取配置中的 authTOML 中mcp_client.registry_auth配置未设时回退到环境变量connections.rs全局进程内连接注册表。包装crate::openhuman::mcp::config_servers::McpStdioClient这里没有独立的 stdio 客户端实现boot.rs启动时生成spawn_installed_servers由bootstrap_core_runtime调用setup.rs/setup_ops.rs“设置代理”支持引导用户配置刚安装的服务器环境变量、密钥、首次连接的小型 Agentops.rsRPC 处理器实现install、uninstall、list、browse、enable/disable 等schemas.rs控制器 schema 处理器分派。从mod.rs重导出为all_mcp_registry_controller_schemas/all_mcp_registry_registered_controllersbus.rsDomainEvent订阅器负责生命周期日志supervisor_events.rs把tinymcp::TickReport翻译为该领域的事件McpServerProbeTimedOut、McpServerTransportDropped、McpServerReconnected、McpServerReconnectFailed、McpServerParkedtools.rsAgent 面向的工具浏览/列表/调用 MCP 工具helpers.rs各 RPC 处理器共享的工具函数encode、inject_required_env_keys、require、resolve公共表面刻意收窄的导出mod.rs的导出刻意保持窄小pub use schemas::{ all_controller_schemas as all_mcp_registry_controller_schemas, all_registered_controllers as all_mcp_registry_registered_controllers, schemas as mcp_registry_schemas, }; pub use types::{ConnStatus, InstalledServer, McpTool};其余模块boot、bus、connections、store、setup、setup_ops、supervisor、types对 crate 内调用方是pub mod但不被重导出ops、registries、registry、schemas是私有的通过 schema 处理器触达。全部模块都受#[cfg(feature mcp)]特性门控特性关闭时编译stub门面。从注册与调用方看对应 src/core/all.rsall_mcp_registry_registered_controllers()与all_mcp_registry_controller_schemas()在src/core/all.rs中注册src/core/jsonrpc.rs在启动时调用boot::spawn_installed_serverssrc/openhuman/tools/registry/ops.rs通过connections把 MCP 工具暴露给 Agent。调用关系调用进入Calls intocrate::openhuman::mcp::config_servers::McpStdioClient真正的 stdio 传输。crate::openhuman::tools::registry已安装服务器的工具落在这里Agent 与原生工具一同可见。memory_store/ workspace SQLitemcp_clients.db持久化。Smithery.ai HTTP注册中心浏览。被谁调用Called bybootstrap_core_runtime经由boot::spawn_installed_servers。前端 Skills UI 的MCP标签页/skills?tabmcpMcpServersTab通过ops.rs走openhuman.mcp_clients_*RPC 命名空间。setup_ops.rs中的设置代理用于首次连接引导。RPC 表面两个命名空间16 个控制器all_controller_schemas()返回 16 个控制器10 个mcp_clients 6 个mcp_setup全部在 schemas.rs 中定义 schema 与handle_*分派分派实现拆分为schemas_part_01.rs与schemas_part_02.rs。mcp_clients命名空间ops.rs方法作用registry_search并行搜索多个注册中心并合并结果。transport参数被接受但忽略目录不再按传输过滤安装时由选择器根据服务器实际提供的连接方式决定registry_get获取服务器完整详情追加required_env_keys。一次调用同时返回详情与必需环境变量键避免安装对话框两次往返目录installed_list列出已安装服务器省略环境变量值install从注册中心安装存储环境变量值发布McpServerInstalled事件uninstall断开连接 删除connect/disconnect上下线服务器连接分别发布McpServerConnected/McpServerDisconnected事件set_enabled启用/禁用禁用时发布带reason: Some(disabled)的断开事件status每服务器连接摘要tool_call在已连接的服务器上调用工具发布McpClientToolExecuted事件update_env替换存储的环境变量并更新服务器行的env_keys、断开并重连——API 密钥轮换无需卸载重装。结果按状态分类connected重连成功返回过滤后的工具列表、disabled、unauthorized只返回原因代码而非原始 401 消息避免泄漏 OAuth 元数据 URL、disconnected携带错误信息detect_auth/oauth_begin认证探测与浏览器 OAuth 开始返回authorize_url对应src/core/jsonrpc.rs中的 OAuth 回调完成逻辑registry_settings_get/registry_settings_set暴露 Smithery / 官方注册中心凭据getter 只报告*_set布尔值密钥值只写不读永不返回mcp_setup命名空间setup_ops.rs这是“设置代理”的 RPC 表面让一个 LLM 引导非技术用户走完 搜索 → 收集密钥 → 干跑测试 → 安装并连接原始密钥值通过不透明的secret://hex引用隔离在 Agent 上下文之外。方法作用search/getregistry的薄包装request_secret铸造secret://hex引用发布McpSetupSecretRequested事件阻塞等待 UI 提交超时上限 5 分钟submit_secretUI 侧兑现待处理的引用引用未知或已提交时报错test_connection干跑拨号候选stdio 草式子进程或 HTTP-remote、列出工具、拆除——不持久化任何内容。拨号失败以ok: false 原因返回而非错误因为“弄清它是否可用”这个操作本身成功了Agent 需要原因来告诉用户修什么install_and_connect提交持久化安装 把密钥引用消费进mcp_client_env然后连接返回连接成功或已安装未连接request_secret与submit_secret的实现setup_ops.rs展示了密钥安全的核心密钥保存在进程本地内存 vault而非 SQLite带 5 分钟请求超时与 15 分钟空闲 GC原始值只经过submit_secret与test_connection/install_and_connect中的即时解析绝不回显到响应或日志consume_refs只在值持久化后才移除引用。Agent 工具与提示注入过滤该模块自身不直接定义Toolimpl。设置代理工具位于 src/openhuman/tools/impl/network/mcp_setup.rs是对mcp::registry::setup_ops的薄包装MCP 浏览/列表/调用工具McpListServersTool、McpListToolsTool等在 src/openhuman/tools/ops.rs 中接入已连接工具表面tool_registry通过connections::all_connected_tools()拉取实时工具。一个值得注意的纵深设计是提示注入过滤mod.rs 中的tools_safe_for_agenttinymcp原样返回远端工具定义而检测器、规则与命中含义属于本应用的安全模型。工具描述触发规则时被丢弃丢弃行为以规则代码记录并发布McpToolRejected事件——违规文本本身绝不重新输出因为载荷正是危险之物。ops.rs中的connect、update_env、install_and_connect在返回工具列表前都会调用这一过滤。持久化与重连监督SQLite 三表结构SQLite 位于{workspace_dir}/mcp_clients/mcp_clients.dbstore.rs共三张表mcp_servers已安装服务器元数据不含环境变量值transport/deployment_url通过幂等的增量迁移添加迁移前行默认stdio。mcp_client_env每服务器环境变量键值对值永不序列化进任何响应、永不记录对mcp_servers级联删除ON DELETE CASCADE。mcp_registry_cache注册中心 HTTP 响应体带10 分钟 TTL避免反复浏览时冲击上游注册中心。进程内连接注册表是OnceLockRwLockHashMapserver_id, Connection每次进程独立、非持久。重连监督器supervisor模块mod.rs运行后台重连循环每 60 秒对每个已打开 workspace 的 host 驱动一次tinymcp::Supervisor::tick——探测每个已连接传输对掉线/从未连接的启用服务器按每服务器指数退避重连。关键实现细节首 tick 延迟一个完整间隔避免与启动连接过程竞争错过 tick 采用MissedTickBehavior::Delay而非连发每轮循环结束interval.reset()从本轮结束时刻起计避免慢于间隔的循环导致连发探测每个 tick 的TickReport交给supervisor_events转为领域事件供开发者 Event Log 流式显示通知桥把“持续离线 / 恢复 / 停放”转成用户通知应答成功的探测刻意不产生事件。注册中心凭据配置config-first、env 回退注册中心浏览的鉴权配置定义在 src/openhuman/config/schema/tools/mcp.rs 的McpRegistryAuthConfigTOML 键mcp_client.registry_auth每个字段都是配置优先、环境变量回退让只设置环境变量的 CI/Docker 部署无需改动配置字段环境变量回退说明smithery_api_keySMITHERY_API_KEYSmithery API 密钥mcp_official_baseMCP_OFFICIAL_REGISTRY_BASE官方注册中心 Base URL 覆盖非密钥mcp_official_tokenMCP_OFFICIAL_REGISTRY_TOKEN官方注册中心 Bearer Token该设计解决的是命中 Smithery 速率限制或需要认证官方注册中心端点的用户场景。官方注册中心的游标走查受MAX_CURSOR_WALK_PAGES50 页上限约束避免深度分页缓存未命中时放大请求。测试策略该领域的惯例是内联单测单元测试位于store.rs、connections.rs、setup.rs的#[cfg(test)]块内当前仓库中还有ops_tests.rs、setup_ops_tests.rs、schemas_tests.rs、bus_tests.rs、supervisor_events_tests.rs、tools_tests.rs等内联测试兄弟文件没有每文件独立*_tests.rs的惯例。此外 tests/mcp_registry_e2e.rs 与src/bin/test_mcp_stub.rs提供 E2E 桩服务器端到端测试可通过store::set_cached播种上游响应缓存从而在不触达真实目录的情况下演练一次安装。常见坑位速查mcp_clientsvsmcp_registryRPC 命名空间与数据库文件名保留旧名mcp_clients仅 Rust 模块路径是mcp_registry追踪调用点时两个名字都要搜。统一安装传输mcp_clients_install与mcp_setup_install_and_connect共用pick_connection/build_install_transport偏好顺序为 已发布 stdio → 任意 stdio → 已发布 http_remote → 任意 http_remote。HTTP-remote 环境变量HTTP-remote 安装的环境变量通常是 OAuth token由McpHttpClient自己的 auth 配置拾取不由本模块在拨号时注入。all_connected_tools注意它目前把server_id放在qualified_name槽位——需要真实限定名的调用方必须重新 joinstore::list_servers。启动尽力而为行为异常的服务器只记录并跳过绝不停滞核心启动。相关文档mcp/registry/mod.rs权威 rustdoc本页内容的镜像来源。mcp/registry/README.md该模块更详细的职责、RPC 控制器、事件与持久化说明。src/openhuman/mcp/config_servers/ 与 src/openhuman/mcp/http_client/传输库 静态配置声明的服务器集合。agent-harness.mdAgent 如何最终通过tool_registry调用 MCP 工具。架构总览)本模块在更大系统中的位置。【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考