MCP 服务器

KaaS 暴露一个 Model Context Protocol 服务器，让任何支持 MCP 的客户端（Claude Code、Codex、openclaw 等）通过单一的 ask 工具查询编译后的 wiki。

工具：ask

向编译后的 KaaS wiki 提问。返回基于 wiki 文章的带引用 Markdown 答案。

参数

参数	类型	必填	说明
query	string	是	自然语言问题
paths	string[]	否	用于定向检索的 wiki 文章路径（跳过主索引导航，直接读取指定页面全文）
model	string	否	聊天模型覆盖（默认使用配置的 LLM_MODEL）

返回值

JSON 对象：

{
  "answer": "Markdown 文本，包含内联 [标题](路径) 引用...\n\nSources:\n- [文章标题](wiki/path.md)",
  "sources": [
    {"title": "文章标题", "path": "wiki/path.md"}
  ],
  "cost_usd": 0.003
}

字段	类型	说明
answer	string	Markdown 答案，包含内联 [标题](路径) 引用和 Sources: 尾注
sources	array	结构化的引用文章列表（title + path）
cost_usd	number	本次查询的预估 LLM 费用

---

传输方式

stdio（默认）

客户端以子进程方式启动 MCP 服务器。完全自包含 — 无网络暴露面，无需认证。

kb-ai mcp [--kb-dir /path/to/data]

Claude Code 配置：

claude mcp add kaas -- kb-ai mcp --kb-dir /path/to/data

所需环境变量：

变量	说明
KAAS_KB_DIR	知识库根目录（或使用 --kb-dir 标志）
LLM_API_KEY	LLM 提供商 API 密钥
LLM_BASE_URL	LLM 提供商 base URL
LLM_MODEL	模型名称

---

streamable-http（远程）

当 [ai.mcp] enabled = true 时，通过 Go 后端的 /mcp 端点发布。

URL: http://<host>:8080/mcp

Claude Code 配置：

claude mcp add --transport http kaas http://host:8080/mcp

认证: 当设置了 KAAS_MCP_TOKEN 时，客户端必须包含：

Authorization: Bearer <token>

未携带有效 token 的请求将收到 401 Unauthorized 响应。

---

配置

etc/kaas.toml 中的相关配置：

[ai.mcp]
enabled = false          # 设为 true 以暴露 /mcp 端点
token = ""               # Bearer token（空 = 无认证）
timeout_sec = 120        # tools/call 超时时间（秒）

环境变量覆盖：

变量	说明	默认值
KAAS_MCP_ENABLED	启用 /mcp 端点	false
KAAS_MCP_TOKEN	Bearer token 认证	（空 = 无认证）

---

工作原理

1. 客户端发送 tools/call 请求，name: "ask" 加上查询参数。
2. MCP 服务器运行与 chat API 相同的 LLM 迭代检索：读取主索引，选择相关 wiki 页面，加载完整文章内容。
3. LLM 生成带有内联 [标题](路径) 引用的答案。
4. 完整答案（含 Sources: 尾注）和结构化来源列表作为工具结果返回。