算力舱手册

Appearance

知识库 MCP ​

Knowledge 应用提供了 MCP 接口，可以让 Codex、Claude Code、Cherry Studio 这类支持 MCP 的客户端直接访问知识库中的文件、网页和检索能力。

使用前提 ​

  • 请先安装最新版知识库，安装方式见 安装方式。
  • 本页内容基于当前知识库仓库版本 1.3.40。
  • 如果您在桌面 MCP 客户端中使用，建议先为对应用户生成访问 token。

服务入口 ​

  • Knowledge 应用地址：
  • MCP 地址：
  • 协议：Streamable HTTP

鉴权方式 ​

  1. ssh 登录微服。
  2. 执行下面的命令，为需要访问知识库的用户生成 token：
bash
hc api_auth_token gen --uid <uid>
  1. 在 MCP 客户端配置中通过 Lzc-Api-Auth-Token 传入这个 token。

工具说明 ​

知识库 MCP 按 rag、fs、ws 三个命名空间组织工具。很多 MCP 客户端会把它们显示为 rag_search、fs_ls、ws_ls 这样的名字。

rag ​

  • rag_search：搜索知识库中的相关片段。
  • rag_summarize：对指定文件或网页做摘要分析。
  • rag_read：分页读取文件或网页内容。

fs ​

  • fs_ls：列出知识库文件目录。
  • fs_search：按关键词搜索文件或目录。
  • fs_find：按文件名查找文件。
  • fs_traverse：递归遍历目录。
  • fs_get_info：查看文件或目录详情。
  • fs_get_stats：查看文件系统统计信息。
  • fs_sync：同步知识库文件状态。
  • fs_mkdir、fs_rm、fs_mv、fs_update_meta：创建、删除、移动、更新元数据。

ws ​

  • ws_ls：列出网页知识目录。
  • ws_search：搜索保存的网页。
  • ws_get_stats：查看网页知识统计信息。
  • ws_mkdir、ws_delete、ws_update_meta：管理网页目录和元数据。

fs_mkdir、fs_rm、fs_mv、fs_update_meta、ws_mkdir、ws_delete、ws_update_meta 这类写操作会修改知识库内容，建议仅在确认范围正确时使用。

MCP 样例 ​

注意将下面配置中的 xxx 替换为您的微服名称。

Claude Code 配置 ​

编辑 Claude Code 配置文件 ~/.claude.json，添加如下 MCP 服务器配置：

json
{
  "mcpServers": {
    "knowledge": {
      "type": "http",
      "url": "https://knowledge.xxx.heiyu.space/mcp/",
      "headers": {
        "Lzc-Api-Auth-Token": "<token>"
      }
    }
  }
}

Codex 配置 ​

编辑 Codex 配置文件 ~/.codex/config.toml，添加如下 MCP 服务器配置：

toml
[mcp_servers]

[mcp_servers.knowledge]
type = "http"
url = "https://knowledge.xxx.heiyu.space/mcp/"

[mcp_servers.knowledge.http_headers]
Lzc-Api-Auth-Token = "<token>"

AI 对话客户端配置 ​

以 Cherry Studio 配置为例，在 设置 -> MCP 服务器 中添加如下配置：

  • 名称：knowledge
  • 类型：可流式传输的 HTTP（streamableHttp）
  • URL：https://knowledge.xxx.heiyu.space/mcp/
  • Header：Lzc-Api-Auth-Token: <token>

保存后启用 MCP 服务器，即可在工具列表中看到知识库相关工具。

常见使用场景 ​

  • 在 Codex 中查询“知识库里关于某个主题的文档结论”。
  • 让客户端先列出 / 或某个目录下的文件，再按目录范围做检索。
  • 对某个文档目录执行摘要，再继续深入读取命中的片段。
  • 搜索已经保存到知识库中的网页内容，而不是重新联网抓取。

参数说明 ​

  • <uid>：需要访问知识库的用户 ID。
  • <token>：通过 hc api_auth_token gen 生成的访问令牌。
  • <微服名称>：当前微服名称，对应 knowledge.<微服名称>.heiyu.space。