> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/mcp-server.md).

# MCP 服务器

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

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

```bash
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 接口通过控制器注册表和核心安全策略路由。读取工具通过读取门控。三个工具通过执行门控。其中两个， `memory.learn` 和 `memory.forget`，也会记录到 MCP 写入审计路径中。 `agent.run_subagent` 不在其中，因为其子代理自身的副作用调用会改为通过审批门控进行审计。

| MCP 工具                   | 后端 RPC                           | 用途                                      |
| ------------------------ | -------------------------------- | --------------------------------------- |
| `web_search`\*           | `openhuman.tools_web_search`     | 通过已配置的提供方进行排名式网页搜索，并带有回退机制。             |
| `web_answer`\*           | `openhuman.tools_web_answer`     | 带引用的有依据答案（默认使用 Gemini 和 Google Search）。 |
| `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` (`quick` 或 `deep`).
* `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` (`preference`, `fact`, `procedure`, `correction`, `other`）以及 `confidence` （0 到 1）。
* `memory.forget`: `ids` （1 到 100）。

`limit` 默认为 10，且上限为 100。 `filter` 可取以下任一值： `workspace`, `folder`, `file_path`, `language`, `repo`, `commit`, `url`, `thread_id`, `agent_id`, `kinds` (`document`, `conversation`, `learning`), `sources`, `tags_any`, `observed_after` 和 `observed_before` （RFC 3339）。记忆工具返回 `MEMORY_OFF` 当没有可用的记忆引擎时。参见 [记忆规范](https://github.com/tinyhumansai/openhuman/blob/main/docs/specs/memory-v2.md) 以了解该模型。

在 Connections > Search 下启用 SearXNG，位于 `config.toml`，或通过环境变量：

```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
```

```bash
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` 响应包含：

```json
{
  "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`。如果添加了一个内置子代理却没有对应的目录项，CI 会失败。

### 资源模板

该目录是静态的：每个 URI 都是具体的，没有任何模板。 `resources/templates/list` 因此总是返回一个空的 `resourceTemplates` 数组。处理程序存在的目的，是为了让那些在看到 `resources` 能力后再去探测它的客户端能够得到有效结果，而不是 `-32601 未找到方法`.

### 资源冒烟测试

```bash
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 和控制器的调度路径。

```toml
[[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"`。如果没有提供方配置，注册表为空，且不会隐藏现有工具。

## 工具冒烟测试

```bash
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",...}]}}
```