MCP 集成

将任何 Model Context Protocol (MCP) 客户端连接到 KaaS，直接从编程代理中查询你的编译知识库。

什么是 MCP

MCP（Model Context Protocol，模型上下文协议）是一种开放标准，允许 AI 代理通过结构化的 JSON-RPC 接口调用外部工具。KaaS 实现了一个 MCP 服务器，暴露单一的 ask 工具 — 代理发送自然语言问题，接收基于编译知识库的带引用 Markdown 回答。

ask 工具

ask(query, paths?, model?) → { answer, sources, cost_usd }

参数	类型	说明
query	string	自然语言问题
paths	string[]（可选）	指定回答所基于的文章路径（跳过主索引导航）
model	string（可选）	覆盖聊天 LLM 模型

该工具执行 LLM 迭代检索（主索引 → 页面选择 → 全文上下文），然后生成带有内联 [标题](路径) 引用的回答。

stdio 传输（本地）

在 stdio 模式下，代理将 kb-ai mcp 作为子进程启动。通信通过 stdin/stdout 上的 JSON-RPC 进行 — 无网络、无鉴权。

前提条件

• 已安装 kb-ai（通过 pip install kb-ai 或从源码安装）
• 已编译的知识库目录（默认：./data）
• 环境中配置了 LLM 凭证

环境变量

export KAAS_KB_DIR="/path/to/your/wiki"   # 知识库根目录
export LLM_API_KEY="sk-xxx"               # OpenAI 兼容 API 密钥
export LLM_BASE_URL="https://api.openai.com/v1"  # API 端点
export LLM_MODEL="gpt-4o-mini"            # 模型名称

Claude Code 配置

claude mcp add kaas -- kb-ai mcp

Claude Code 会自动启动 kb-ai mcp 并通过 stdio 通信。

Codex / 其他代理

添加 stdio MCP 服务器：

• 命令: kb-ai mcp
• 环境变量: KAAS_KB_DIR、LLM_API_KEY、LLM_BASE_URL、LLM_MODEL

HTTP 传输（远程）

在 HTTP 模式下，Go 后端在 /mcp 路径暴露 MCP 端点。代理通过 HTTP 连接 — 适用于共享服务器和团队部署。

Docker 配置

docker run -d --name kaas \
  -p 8080:8080 \
  -v ./data:/app/data \
  -e LLM_API_KEY=sk-xxx \
  -e LLM_BASE_URL=https://api.openai.com/v1 \
  -e LLM_MODEL=gpt-4o-mini \
  -e KAAS_MCP_ENABLED=true \
  -e KAAS_MCP_TOKEN=your-secret-token \
  kaas

MCP 端点地址为 http://<host>:8080/mcp。

Claude Code 配置

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

如果启用了鉴权，需要在代理中配置 Bearer Token 请求头。

Codex / 其他代理

添加远程 MCP 服务器：

• URL: http://<host>:8080/mcp
• 传输方式: http（streamable-http）
• 授权: Bearer your-secret-token（如设置了 KAAS_MCP_TOKEN）

鉴权

传输方式	鉴权机制	配置方式
stdio	无（无网络暴露）	—
HTTP	Bearer Token（可选）	设置 KAAS_MCP_TOKEN 环境变量

当设置了 KAAS_MCP_TOKEN 时，每个 HTTP 请求必须包含：

Authorization: Bearer your-secret-token

当 KAAS_MCP_TOKEN 为空或未设置时，HTTP 端点为开放状态（适用于本地/内网环境）。

也可以在 etc/kaas.toml 中配置鉴权：

[ai.mcp]
enabled = true
token = "your-secret-token"   # 为空 = 无鉴权
timeout_sec = 120

如何选择传输方式

维度	stdio	HTTP
部署方式	本地（代理所在机器）	远程服务器 / Docker
延迟	最低（进程内通信）	网络往返
鉴权	不需要	Bearer Token（可选）
共享访问	单一代理	多代理 / 团队共享
配置复杂度	极简	Docker + 环境变量
数据位置	本地 ./data 目录	服务器端挂载卷

使用 stdio：独立工作、知识库在本机、追求零配置。

使用 HTTP：知识库需团队共享、运行在远程服务器、或需要访问控制。

故障排查

kb-ai 命令未找到

确保 kb-ai 已安装并在 PATH 中：

pip install kb-ai
# 或从 KaaS 仓库安装：
cd py && pip install -e .

"No articles found" 或回答为空

• 确认 KAAS_KB_DIR 指向已编译的知识库（应包含 master-index.md）
• 如果知识库为空，需先运行蒸馏流程

HTTP 传输连接被拒绝

• 确认设置了 KAAS_MCP_ENABLED=true
• 检查容器是否运行中：docker ps | grep kaas
• 验证端口映射：默认为 8080

401 未授权

• 在代理配置中设置正确的 Bearer Token
• 检查 KAAS_MCP_TOKEN 与代理发送的 Authorization 头是否一致

超时错误

• 默认工具超时为 120 秒（通过 [ai.mcp] timeout_sec 配置）
• 大型知识库首次检索可能需要更长超时时间
• 确保 LLM 端点（LLM_BASE_URL）从服务器可达