OpenHuman MCP Registry 深度指南多目录搜索、SQLite 持久化与 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/openhumanOpenHuman 的mcp/registry模块是 MCPModel Context Protocol客户端支持的动态、面向用户一侧它并行浏览 Smithery.ai 与官方 modelcontextprotocol/registry 两大上游目录将用户选择的安装持久化到 SQLite按 stdio 子进程 / HTTP-remote 两种传输监管每台服务器的连接生命周期并把已连接服务器的工具汇入统一工具注册表供 Agent 调用。本文以 mcp/registry/README.md 为主线结合当前仓库源码完整梳理其模块边界、双命名空间 RPC 表面、Agent 工具面、事件模型、持久化与安全设计帮助你理解并复用这套目录浏览 → 安装 → 连接 → 调用的完整链路。模块定位MCP 客户端的动态与面向用户一面在 OpenHuman 的 MCP 家族mcp/README.md中server/是开放给外部的 stdio/HTTP MCP 服务器config_servers/是用户 TOML 配置中静态声明的服务器集合 stdio 传输http_client/是 Streamable HTTP 传输原语而registry/负责所有动态、用户驱动的安装与连接管理搜索多个上游 MCP 服务器目录并并行合并结果详情抓取回路由到来源目录将已安装服务器记录不含环境值、每台服务器的环境值、带 TTL 的目录响应缓存持久化到 SQLite以server_id为键建立、跟踪、拆除实时 MCP 连接并按每条安装记录的Transportstdio 子进程或 HTTP-remote分派启动时非阻塞地拉起所有已安装的本地服务器通过 JSON-RPCmcp_clients_*暴露安装/连接/状态/工具调用生命周期运行独立的设置 Agent 表面mcp_setup_*采用带外密钥收集使凭据永不进入 LLM 上下文提供 AIconfig_assist流程引导用户填写必需的环境变量发布生命周期DomainEvent用于可观测性。命名说明mcp_clients与mcp_registry从 mod.rs 可以看到一条重要的兼容性约定RPC 命名空间和 SQLite 数据库文件名仍为mcp_clients向后兼容只有 Rust 模块路径是mcp_registry。这样做的目的是让既有前端代码和磁盘上已有的状态在演进过程中无需改动。实现现状底层已抽取到tinymcp从源码结构看该模块的底层实现经历了一次抽取目录适配、SQLite 存储、实时连接表、子进程监督循环、浏览器登录流、设置密钥库已迁移到外部 cratetinymcp通过 vendor 子模块引入见 Cargo.toml 中tinymcp { path vendor/tinymcp/... }的说明。本地mcp/registry保留的是属于应用本身的部分见 mod.rs 模块注释ops/setup_ops—— 两个命名空间的 RPC 处理器逐一委托给 host.rs 持有的tinymcp::McpRegistry服务事件发布 ——tinymcp只在返回值里报告结果、不发布任何事件DomainEvent是本应用的词汇因此发布发生在ops.rs/setup_ops.rs这一层远程工具定义的提示注入扫描tools_safe_for_agent—— 检测器、规则和命中含义属于本应用的安全模型config_assist的 Agent 轮次 —— 运行轮次需要 Agent、工具面和审批门这些都在本应用内。源码地图关键文件与模块划分文件职责mod.rs模块文档与导出connections、store、boot、supervisor、oauth等应用侧封装tools_safe_for_agent注入扫描host.rsMcpHost持有者动态目录 静态服务器集 审计日志按工作区懒加载服务代理决策、身份与 OAuth 重定向 URI 解析ops.rsmcp_clients_*RPC 处理器实现 resolve_commandconfig_assist推理调用setup_ops.rsmcp_setup_*RPC 处理器search/get/request_secret/submit_secret/test_connection/install_and_connectschemas.rs schemas_part_01.rs / schemas_part_02.rs控制器 Schema 与handle_*分派mcp_clients与mcp_setup两个命名空间tools.rsAgent 面工具mcp_registry_*薄封装ops.rsbus.rsMcpClientEventSubscriber—— 记录生命周期事件init()在启动时注册supervisor_events.rs将tinymcp::TickReport翻译成本领域事件#5931供开发者 Event Log 与通知桥使用helpers.rsencode/require/resolve/inject_required_env_keys等共享助手README 中记载的store.rs、registry.rs、registries/smithery.rs、mcp_official.rs、connections.rs、setup.rs等核心实现文件当前位于tinymcpcrate 内本地mcp/registry通过host::for_config(config)拿到对应工作区的服务实例后逐层委托。RPC 表面mcp_clients与mcp_setup双命名空间从 schemas_part_01.rs 的all_controller_schemas()可见当前注册的控制器覆盖两个命名空间mcp_clients手动管理面与mcp_setup设置 Agent 面。README 记载早期版本为 10 6 共 16 个控制器当前代码中mcp_clients面已扩展到 16 个方法加上mcp_setup的 6 个方法共注册 22 个控制器。mcp_clients手动安装与生命周期管理实现在 ops.rs每个函数与一个 schema 处理器一一对应方法作用registry_search搜索目录。接受query、transport、page默认 1、page_size默认 20。transport参数被接受但忽略目录不再按传输过滤因为安装时选择器会根据服务器实际提供的能力挑选连接参数保留是为了让前端同一版本内的调用无需改动registry_get获取服务器完整详情附带required_env_keys安装对话框一次调用即可拿到两样东西避免两次目录往返installed_list列出已安装服务器环境值被省略不进入任何响应install从目录安装stdio 传统路径存储环境值发布McpServerInstalled已安装时返回already_installed: trueuninstall断开 删除返回removed布尔值connect/disconnect使服务器连接上线/下线connect返回经过安全扫描的工具列表并发布McpServerConnectedset_enabled启用/禁用禁用时发布带reason: disabled的McpServerDisconnectedstatus每台服务器的连接摘要list_tools列出已连接服务器的工具未连接时返回请先 connect的提示tool_call在已连接服务器上调用工具返回{ result, is_error }并发布含elapsed_ms的McpClientToolExecutedupdate_env重配置替换已存储的环境值以及服务器行的env_keys、断开并重连——API 密钥轮换无需卸载/重装返回connected/disabled/unauthorized/disconnected四种状态未授权时只回传auth_hint原因码而绝不回传原始 401 消息避免泄漏 OAuth 元数据 URLdetect_auth认证方式检测为 OAuth 流程做准备oauth_begin发起浏览器 OAuth返回authorize_url回调路径由 host.rs 的oauth_redirect_uri()提供优先取核心实际绑定端口其次OPENHUMAN_CORE_PORT默认 7788registry_settings_get/registry_settings_set目录凭据读写Smithery / 官方目录。getter 只报告*_set布尔值密钥值只写不回set 同时写入配置文件并热更新运行中的服务config_assistAI 配置助手详见下文config_assistAI 引导填写必需环境变量mcp_clients_config_assistops.rs先用目录详情 必需环境变量名构造 system prompt然后运行一次真实的 Agent 轮次而非裸补全并把 Agent 工具面收敛到web_search_tool/web_fetch/curl三个工具#3648 相关设计约束凭证帮助轮次不得切入本地文件系统、shell 等无关能力轮次以AgentTurnOrigin::Cli标记避免审批门对未标记调用点默认失败返回{ reply: ..., suggested_env: { ... } }模型可把用户在对话里提供的值抽取为suggested_env未配置推理时回退为一条友好的引导文案提示到 Connections → API keys → LLM 配置。mcp_setup设置 Agent 引导流程实现在 setup_ops.rs目标是让 LLM 带领非技术用户走完搜索 → 密钥收集 → 干运行测试 → 安装并连接方法作用search/get目录搜索与详情的薄包装返回形状与mcp_clients对应方法一致request_secret铸造一个secret://hex不透明引用发布McpSetupSecretRequested然后阻塞最多 5 分钟等待 UI 提交等待逻辑留在本层因为提示由本层发布的事件渲染submit_secretUI 侧履行一个待定引用引用未知或已提交则报错test_connection干运行用已收集的密钥拨号候选stdio 临时子进程或 HTTP-remote、列出工具、拆除不持久化任何东西。拨号失败返回ok: false 原因而非报错——任务本身确认是否可行成功了Agent 需要原因来告诉用户修什么install_and_connect提交持久化安装 把密钥引用消费进mcp_client_env然后连接返回连接结果工具列表并发布McpServerInstalledMcpServerConnectedAgent 工具面mcp_registry_*与mcp_setup_*本模块自身不直接定义通用的 MCP 工具实现而是通过 tools.rs 提供一套独立的已安装注册表表面区别于 tools/impl/network/mcp.rs 的通用桥接工具工具权限级别默认状态作用mcp_registry_search只读开按query/transportstdio|hosted|all/page/page_size搜索目录mcp_registry_get只读开按qualified_name取服务器详情mcp_registry_installed_list只读开列出已安装服务器mcp_registry_status只读开已安装服务器的连接状态mcp_registry_list_tools只读开列出已连接服务器暴露的工具调用前需先连接mcp_registry_connect/disconnectExecute开连接/断开已安装服务器mcp_registry_tool_callExecute开在已连接服务器上调用工具server_idtool_nameargumentsmcp_registry_config_assistExecute开AI 配置引导mcp_registry_install/uninstallWrite默认关持久化安装/卸载写入安装状态 密钥通过tools/user_filter.rs的mcp_manage开关启用设置 Agent 工具mcp_setup_search、mcp_setup_get、mcp_setup_request_secret、mcp_setup_test_connection、mcp_setup_install_and_connect等位于 tools/impl/network/mcp_setup.rs同样是对setup_ops的薄包装。工具注册表通过connections::all_connected_tools()mod.rs 中connections模块拉取实时工具列表该函数当前把server_id放在qualified_name槽位返回需要真实限定名的调用方要再对store::list_servers做一次关联README 已明确标注此注意项。事件与可观测性发布经BUS.publish见 ops.rs 与 setup_ops.rs事件触发点McpServerInstalledops::install、setup_ops::install_and_connectMcpServerConnectedops::connect、ops::update_env重连成功、setup_ops::install_and_connectMcpServerDisconnectedops::disconnect、ops::set_enabled禁用McpClientToolExecutedops::tool_call携带success与elapsed_msMcpSetupSecretRequestedsetup_ops::request_secret订阅与监督事件business.rs 的McpClientEventSubscriber订阅域mcp_client仅记录McpServer*/McpClientToolExecuted事件日志用于可观测性无副作用init()在启动时注册事件总线未初始化时仅告警不崩溃。supervisor_events.rs 把重连监督器每轮 tick 的TickReport翻译成本领域事件#5931McpServerProbeTimedOut、McpServerTransportDropped、McpServerReconnected、McpServerReconnectFailed、McpServerParked。设计要点每个事件都盖有被 tick 的 workspace 戳——一个进程会监督它打开过的每个工作区通知桥必须把事件归档到事件所命名的工作区而不是桥注册时所在的工作区且只有在该工作区是活动工作区时才向已连接客户端播报socket 桥没有按客户端路由能力开发者 Event Log 以单行DomainEvent::log_detail摘要流式呈现信封不带 payload通知桥把持续掉线 / 恢复 / 停车转为用户通知应答的探测故意不构成事件每台服务器每分钟一行会把日志淹没tinymcp在 trace 级记录它这就够了。持久化SQLite 三表 进程内密钥库与连接表SQLite{workspace_dir}/mcp_clients/mcp_clients.dbmcp_servers—— 已安装服务器元数据不含环境值transport/deployment_url列通过幂等加性迁移加入迁移前的行默认stdiomcp_client_env—— 每台服务器的环境键值对值绝不序列化进任何响应、绝不打日志从mcp_servers级联删除ON DELETE CASCADEmcp_registry_cache—— 目录 HTTP 响应体缓存10 分钟 TTLSmithery 适配器复用该缓存。进程内状态设置 Agent 密钥库原setup.rs的SecretRef机制现由tinymcp持有进程本地内存映射非 SQLite5 分钟请求超时 15 分钟空闲 GC只有install_and_connect期间通过consume_refs→mcp_client_env提交后才会持久化连接注册表OnceLockRwLockHashMapserver_id, Connection进程内临时态本地mcp/registry通过 host.rs 按工作区访问——host::for_config(config)懒加载每个工作区自己的服务McpRegistry含动态目录、静态服务器集与审计日志AuditStore同一工作区的调用共享同一服务实例。配置详解mcp_client配置块config/schema/tools/mcp.rs[mcp_client] enabled true # 是否注册通用 MCP 桥接工具并暴露已配置的远程服务器 [mcp_client.client_identity] # initialize 握手时发送的客户端身份 name openhuman-core # 默认值 title OpenHuman Core MCP Client version CARGO_PKG_VERSION # 默认取包版本 [mcp_client.registry_auth] # 目录浏览 API 的认证/端点覆盖配置优先环境变量兜底 # smithery_api_key # 兜底环境变量 SMITHERY_API_KEY # mcp_official_base # 兜底环境变量 MCP_OFFICIAL_REGISTRY_BASE非密钥 # mcp_official_token # 兜底环境变量 MCP_OFFICIAL_REGISTRY_TOKENMcpRegistryAuthConfig的三个字段都是配置优先 环境变量回退让只设置环境变量的既有 CI/Docker 部署无需改动密钥经 RPC 只写不回getter 只返回*_set布尔值。每台静态服务器[[mcp_client.servers]]字段说明name稳定服务器 slugAgent 桥接工具使用endpointMCP 端点 URL无状态 Streamable HTTP / JSON 响应command/args/env/cwdstdio 传输子进程命令、参数、环境变量、工作目录命令非空即走 stdio否则走 HTTPdescription桥接工具输出中显示的可读描述enabled是否暴露给 MCP 桥接工具默认 trueallowed_tools/disallowed_tools工具白名单/黑名单传输前 fail-closed 拦截黑名单优先于白名单timeout_secs每请求超时默认 30 秒auth认证策略None/BearerToken/Basic/Header/Headers多头/QueryParamlegacygitbooks服务器当config.gitbooks.enabled且不存在显式名为gitbooks的服务器时自动播种显式配置优先。代理与身份MCP 流量走tool.mcp_client作用域键下的运行时代理策略host.rs 的proxy_for_mcp()结合 scope 设置、per-service 列表与 no-proxy 列表决定客户端身份默认值见上文可在配置中覆盖。安全设计凭据不落明文传输credentialed_endpoint_transport_allowedhost.rs——携带认证的服务器端点必须是 HTTPS 或回环地址localhost/127.0.0.1/::1否则该服务器被剔除并告警防止凭据以明文 HTTP 上线路由到第三方远程工具提示注入扫描tools_safe_for_agentmod.rs对每个远程工具描述运行scan_tool_definition命中规则的工具被丢弃只发布规则码McpToolRejected——被污染的描述文本本身绝不回发密钥值只在带外流动原始密钥只经submit_secret与test_connection/install_and_connect中的即时 resolve 使用绝不回显到响应、绝不记录日志consume_refs只在值已持久化后才移除引用HTTP-remote 环境变量由McpHttpClient自身的 auth 配置拾取典型为 OAuth token不由本模块在拨号时注入。启动、重连监督与可靠性启动连接boot::spawn_installed_serversmod.rs在核心启动时连接所有已启用的已安装服务器记录connected / failed / skipped统计尽力而为——某台异常服务器只记录日志并跳过绝不阻塞核心启动重连监督supervisor::run后台循环每 60 秒驱动tinymcp::Supervisor::tick覆盖进程打开过的每个工作区 host逐台探测已连接传输对掉线或从未连上的已启用服务器按每服务器指数退避重连退避周期本身在tinymcp内错过 tick 不突发tick 可能超过自身间隔MissedTickBehavior::Delay避免把错过的 tick 背靠背补齐、对刚探测过的服务器重复探测循环末尾interval.reset()从周期结束时刻起算下一次防止持续慢周期导致连轴转每个 tick 的TickReport交给supervisor_events::publish转为领域事件。实操要点与陷阱Notes / gotchas命名兼容RPC 命名空间与数据库文件名保持mcp_clients模块路径才是mcp_registry——排查问题时别被两个名字混淆统一安装传输手动安装对话框mcp_clients_install与设置 Agentmcp_setup_install_and_connect都经setup_ops::pick_connection选最佳连接、经build_install_transport构造传输偏好顺序为发布的 stdio → 任意 stdio → 发布的 http_remote → 任意 http_remote。因此 HTTP-remote 目录条目也能从 UI 安装不止设置 Agent 可用API 密钥轮换直接调mcp_clients_update_env即可存储新 env → 断开 → 重连无需卸载重装目录凭据写回mcp_clients_registry_settings_set同时写配置文件和热更新服务两者缺一不可文件保证重启存活服务保证下一次搜索即生效空白更新清除字段、缺省不动原值Smithery DTO 命名规范结果形状按线缆兼容命名为Smithery*非 Smithery 目录适配进同一形状并用source字段标记来源工具列表关联all_connected_tools当前在qualified_name槽位返回server_id需要真实限定名时必须对store::list_servers再关联一次官方目录游标遍历深页缓存未命中时顺序走页最多MAX_CURSOR_WALK_PAGES50页即放弃避免请求放大。测试与验证仓库为该模块准备了多层验证端到端tests/mcp_registry_e2e.rs 覆盖set_enabled→connect→update_env含密钥轮换与部分 env 场景等完整生命周期单元测试ops_tests.rs、setup_ops_tests.rs、schemas_tests.rs、tools_tests.rs、bus_tests.rs、supervisor_events_tests.rs与本模块各源文件同目录#[cfg(test)] #[path ...] mod tests;协议桩stub.rs 与 test_mcp_stub.rs 提供 MCP-less 构建下的编译面与 E2E 桩服务器上游缓存播种mod.rs 的store::set_cached供端到端测试直接向响应缓存写入一条上游响应从而在不触达真实目录的情况下演练安装流程。小结OpenHuman 的mcp/registry是理解用户驱动的 MCP 集成的完整范本双上游目录并行搜索、SQLite 三表持久化、stdio/HTTP 双传输连接生命周期、mcp_clientsmcp_setup双 RPC 命名空间、带外密钥收集与提示注入扫描构成了从搜索到调用的全链路安全闭环。当前实现把通用机制下沉到tinymcp本地保留事件、扫描与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考