MCP 服务器

将 OpenHuman Core 作为 stdio Model Context Protocol 服务器运行，供本地 MCP 客户端使用。

OpenHuman Core 可以作为可选启用的 stdio MCP 服务器运行。本地 MCP 客户端，如 Claude Desktop、Cursor 或 Zed，随后可以使用其搜索、记忆和子代理工具。

openhuman-core mcp

该命令不会启动 HTTP JSON-RPC 服务器。它从 stdin 读取以换行分隔的 JSON-RPC 2.0 消息，并将 MCP 响应写入 stdout。日志输出到 stderr。添加 --verbose 以获取调试输出。

客户端来源

在 initialize，服务器会捕获 params.clientInfo.name 用于该 stdio 会话。它会按四个步骤规范化该名称：去除空白、转为小写、将每一段非 ASCII 字母数字字符替换为一个连字符，然后去掉首尾连字符。 Claude Desktop 变为 claude-desktop, Cursor 变为 cursor 和 Windsurf 变为 windsurf.

如果客户端省略 clientInfo.name，发送空值，或发送一个规范化后为空的名称，则该会话将使用纯粹的 mcp 源标签。具备写入能力的 MCP 工具会使用该标签作为记忆来源。未识别的客户端写作 mcp，而可识别的客户端写作 mcp:<client>.

工具

MCP 接口通过控制器注册表和核心安全策略进行路由。读取工具通过读取门禁。三个工具通过 act 门禁。其中两个， memory.learn 和 memory.forget，也会记录到 MCP 写入审计路径中。 agent.run_subagent 则不是，因为子代理自身会产生副作用的调用会改为通过审批门禁进行审计。

MCP 工具	底层 RPC	用途
web_search*	openhuman.tools_web_search	通过已配置提供方进行排名的网页搜索，带有回退机制。
web_answer*	openhuman.tools_web_answer	带有引用的有依据回答（默认使用 Gemini 和 Google 搜索）。
searxng_search*	openhuman.tools_searxng_search	搜索已配置的自托管 SearXNG 实例。
memory.recall	openhuman.memory_recall	提出一个问题；获取带引用的答案（只读）。
memory.fetch	openhuman.memory_fetch	查询的原始命中结果，带有元数据过滤器和游标（只读）。
memory.list	openhuman.memory_items_list	分页浏览已存储条目，按最新优先（只读）。
memory.learn	openhuman.memory_learn	存储一条学习内容（添加一个条目；非破坏性）。
memory.forget	openhuman.memory_forget	按 id 永久移除条目（破坏性；受 act 门禁控制）。
core.list_tools	以内层提供	OpenHuman 向其编排器公开的实时核心代理工具目录。
core.tool_instructions	以内层提供	注入到提示驱动代理中的 Markdown 工具使用说明块。
agent.list_subagents	以内层提供	核心可调度的已注册子代理定义。
agent.run_subagent	以内层提供	运行一个已注册子代理并返回其最终响应（受 act 门禁控制）。

标有 * 的工具仅在提供方能够提供时才会列出。 web_search 和 web_answer 它们的搜索角色需要一个可用的提供方，即已登录会话或使用你自己的密钥的提供方。 searxng_search 需要在搜索设置中启用 SearXNG。

参数：

• web_search: query，可选 max_results （1 到 20），以及可选的 provider （锁定一个提供方并禁用回退）。

• web_answer: query 以及可选的 depth (快速 或 深度).

• searxng_search: query 以及可选的 max_results （1 到 20）。

• memory.recall: question，以及可选的 filter 和 limit.

• memory.fetch: query，以及可选的 mode, filter, limit 和 cursor. mode 必须是当前活动内存引擎支持的类型之一。两个启动引擎（tinyhumans, cortexdb）仅支持 hybrid，因此除非你明确知道，否则请省略它。

• memory.list：可选的 filter, limit 和 cursor.

• memory.learn: text，以及可选的 kind (偏好, 事实, 流程, 更正, 其他）以及 confidence （0 到 1）。

• memory.forget: ids （1 到 100）。

limit 默认为 10，且上限为 100。 filter 可取以下任意值： workspace, 文件夹, file_path, language, repo, commit, url, thread_id, agent_id, kinds (document, conversation, learning), 来源, tags_any, observed_after 和 observed_before （RFC 3339）。记忆工具会作答 MEMORY_OFF 当没有可用的内存引擎时。参见 memory spec 了解该模型。

在 Connections > Search 中启用 SearXNG，在 config.toml，或使用环境变量：

[search.providers.searxng]
enabled = true
route = "direct"

[searxng]
enabled = true
base_url = "http://localhost:8080"
max_results = 10
default_language = "en"
timeout_seconds = 10

OPENHUMAN_SEARXNG_ENABLED=true
OPENHUMAN_SEARXNG_BASE_URL=http://localhost:8080
OPENHUMAN_SEARXNG_MAX_RESULTS=10
OPENHUMAN_SEARXNG_DEFAULT_LANGUAGE=en
OPENHUMAN_SEARXNG_TIMEOUT_SECONDS=10

资源

服务器将捆绑的提示资产作为静态资源公开。支持 resources/list 和 resources/read 的客户端无需运行任何工具即可读取代理人格和子代理提示模板。

能力声明

该 initialize 响应包含：

{
  "capabilities": {
    "tools": {},
    "resources": { "subscribe": false, "listChanged": false }
  }
}

URI 方案

URI	内容
openhuman://prompts/identity	IDENTITY.md （核心代理身份）
openhuman://prompts/soul	SOUL.md （核心代理人格和价值观）
openhuman://prompts/user	USER.md （用户资料上下文）
openhuman://prompts/agents/<id>	<id>/prompt.md 适用于 15 个内置子代理中的每一个

所有资源都具有 mimeType: "text/markdown".

目录一致性

一个单元测试（catalog_mirrors_builtins）会将资源目录与 BUILTINS 中 loader.rs的 BUILTINS 切片进行检查。添加一个没有对应目录项的内置子代理会导致 CI 失败。

资源模板

目录是静态的：每个 URI 都是具体的，没有模板化。 resources/templates/list 因此始终返回一个空的 resourceTemplates 数组。该处理程序存在的目的是让客户端在看到 resources 能力后去探测它时，能得到有效结果，而不是 -32601 Method not found.

资源冒烟测试

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"resources/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"resources/templates/list"}' \
  '{"jsonrpc":"2.0","id":4,"method":"resources/read","params":{"uri":"openhuman://prompts/identity"}}' \
  | openhuman-core mcp

工具注册表

HTTP JSON-RPC 服务器还公开一个只读工具注册表。代理和仪表板可利用它在不打开 MCP stdio 会话的情况下发现工具：

RPC 方法	用途
openhuman.tool_registry_list	列出 MCP stdio 工具和由控制器支持的工具，并提供稳定的 tool_id、路由、版本、输入/输出模式、允许的代理、标签、启用状态和健康状况。
openhuman.tool_registry_get	按以下项返回一条注册表记录： tool_id，例如 memory.recall 或 tools.web_search.
openhuman.tool_registry_diagnostics	返回已脱敏的清单计数、写入面候选项、策略面以及外部能力提供方诊断信息。

该注册表仅用于发现。它不会改变工具分发或权限检查。MCP 调用仍然通过 tools/call，而由控制器支持的工具仍然使用其各自的 JSON-RPC 方法。

外部能力提供方

你可以在 config.toml中记录受信任的外部能力提供方。这只是治理元数据。它不会安装包、运行远程代码或绕过 MCP 和控制器分发路径。

[[capability_providers]]
id = "Acme Tools"
display_name = "Acme Tools"
source_uri = "https://example.com/openhuman/acme-tools"
source_digest = "sha256:abc123"
trust_state = "trusted"
enabled = true

提供方 id 会在策略检查前规范化，因此 Acme Tools 变为 acme-tools。规范化后的重复项会被拒绝。只有同时具备以下两项时，提供方才有资格通过未来的准入检查： enabled = true 和 trust_state = "trusted"。在没有提供方配置时，注册表为空，且不会隐藏任何现有工具。

工具冒烟测试

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | openhuman-core mcp

响应应包含 capabilities.tools 来自 initialize 以及来自 tools/list。成功运行时会向 stdout 恰好写入两行紧凑的 JSON。 notifications/initialized 是一个通知，没有响应。

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{},"resources":{"subscribe":false,"listChanged":false}},"serverInfo":{"name":"openhuman-core","version":"<crate version>"},"instructions":"..."}}
{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"memory.recall",...},{"name":"memory.fetch",...},{"name":"memory.list",...},{"name":"memory.learn",...},{"name":"memory.forget",...}]}}