MaxKB 知识库检索 MCP

基于 MaxKB Admin API 的 MCP 服务，按用户问题检索知识库分段。支持向量检索、混合检索、全量检索。默认 Top K 为 10、检索模式为向量检索。

默认以 Streamable HTTP 提供服务：

• MCP 地址：http://<主机>:8000/mcp
• 健康检查：http://<主机>:8000/health

能力

工具	作用
search_knowledge	按问题检索相关分段
list_knowledge_bases	列出知识库
get_knowledge_base	查看单个知识库
list_documents	列出知识库文档
list_workspaces	列出工作空间

search_mode（工具未指定时使用环境变量，默认向量检索）：

• 向量 / 向量检索 / embedding
• 混合 / 混合检索 / blend
• 全量 / 全量检索 / keywords
• auto：混合检索 → 向量检索 → 全文检索，直到命中

未指定 knowledge_ids 时，会在当前工作空间所有已配置向量模型的知识库中检索。

环境变量

复制示例文件后按实际环境修改：

cp .env.example .env

变量	默认	说明
MAXKB_BASE_URL	无	MaxKB 地址，例如 https://host:2801（必填）
MAXKB_API_KEY	无	用户 API Key；HTTP 模式下可省略，优先使用客户端 headers.Authorization
MAXKB_WORKSPACE_ID	default	默认工作空间
MAXKB_TOP_K	10	检索返回条数，范围 1-100
MAXKB_SEARCH_MODE	向量	向量 / 混合 / 全量
MAXKB_VERIFY_SSL	true	证书无法校验时可设为 false
MAXKB_TIMEOUT	30	请求超时秒数
MCP_TRANSPORT	http	http（streamable-http）/ stdio / sse
MCP_HOST	0.0.0.0	HTTP 监听地址
MCP_PORT	8000	HTTP 端口
MAXKB_LOG_DIR	logs	本地日志目录
MAXKB_LOG_RETENTION_DAYS	7	日志留存天数，到期自动删除

单次调用 search_knowledge 时若传入 top_n 或 search_mode，会覆盖服务端默认值。

本地启动

需要 Python 3.10+ 与 uv。

cp .env.example .env
uv sync
uv run maxkb-mcp

启动后：

• MCP：http://127.0.0.1:8000/mcp
• 健康检查：http://127.0.0.1:8000/health
• 日志文件：logs/mcp.log（按天滚动，默认保留 7 天）

客户端接入示例：

{
  "mcpServers": {
    "maxkb-knowledge": {
      "transport": "streamable_http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "你的 MaxKB API Key"
      },
      "disabled": false
    }
  }
}

Authorization 可以是原始 Key，也可以是 Bearer <key>。

如需 stdio 模式：

MCP_TRANSPORT=stdio uv run maxkb-mcp

Docker 镜像打包

需要 Docker 20.10+。

docker build -t maxkb-mcp:latest .

国内网络建议指定 PyPI 镜像：

docker build \
  --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
  -t maxkb-mcp:latest .

推送到镜像仓库（可选）：

docker tag maxkb-mcp:latest <registry>/<namespace>/maxkb-mcp:0.1.0
docker push <registry>/<namespace>/maxkb-mcp:0.1.0

Docker 部署

docker-compose.yml 不构建镜像，只使用已有镜像启动。部署前先完成本地构建或从仓库拉取镜像。

cp .env.example .env
docker-compose up -d
docker-compose logs -f maxkb-mcp

使用远程镜像时：

MAXKB_MCP_IMAGE=<registry>/<namespace>/maxkb-mcp:0.1.0 docker-compose up -d

启动后：

• MCP：http://<主机>:8000/mcp
• 健康检查：http://<主机>:8000/health
• 日志目录：宿主机 ./logs（容器内 /app/logs）

经 HTTPS 反代后，客户端 url 改为 https://your-domain/mcp。

若 MaxKB 部署在宿主机，将 MAXKB_BASE_URL 写成 http://host.docker.internal:<端口>。

停止服务：

docker-compose down

日志

所有 HTTP 请求与 MCP 工具调用都会写入本地日志，Authorization 会脱敏。

• 文件：{MAXKB_LOG_DIR}/mcp.log，每天滚动为 mcp.log.YYYY-MM-DD
• 启动时清理一次过期文件，之后每 6 小时再清理
• 超过 MAXKB_LOG_RETENTION_DAYS（默认 7 天）的日志会被删除

常见问题

• 未提供 API Key：在客户端 headers.Authorization 中传入 MaxKB 用户 Key，或在 .env 中配置 MAXKB_API_KEY
• 构建慢或超时：打包时加 --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
• 容器访问不到 MaxKB：检查 MAXKB_BASE_URL、网络，以及是否需要 host.docker.internal
• 证书校验失败：设置 MAXKB_VERIFY_SSL=false