# 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` 时，会在当前用户可见工作空间中所有已配置向量模型的知识库里检索。未指定 `workspace_id` 时，通过 `GET /admin/api/user/profile` 的 `workspace_list` 获取可见工作空间（普通用户可用），不再调用工作空间管理接口，也不会静默落到 `default`。

## 环境变量

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

```bash
cp .env.example .env
```

| 变量 | 默认 | 说明 |
|------|------|------|
| `MAXKB_BASE_URL` | 无 | MaxKB 地址，例如 `https://host:2801`（必填） |
| `MAXKB_API_KEY` | 无 | 服务端兜底 Key。HTTP 模式下 **MCP `headers.Authorization` 优先**；两者都配置时用 MCP 端的 Key；`.env` 为空则只用 MCP 端的 Key |
| `MAXKB_WORKSPACE_ID` | 空 / `default` | 可选限制。工具未传 `workspace_id` 且该值不是 `default` 时，只检索该空间；`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](https://docs.astral.sh/uv/)。

```bash
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 天）

客户端接入示例：

```json
{
  "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>`。

API Key 优先级（HTTP / streamable_http）：

1. MCP 客户端 `headers.Authorization`（每次请求携带）
2. 同一 MCP 会话里缓存的 Key（后续请求未再带 Authorization 时）
3. 服务端 `.env` 的 `MAXKB_API_KEY`

`.env` 里 Key 为空时，第 3 步不生效，必须在 MCP 配置里传 Authorization。两边都配了则以 MCP 配置为准。

如需 stdio 模式：

```bash
MCP_TRANSPORT=stdio uv run maxkb-mcp
```

## Docker 镜像打包

需要 Docker 20.10+。

```bash
docker build -t maxkb-mcp:latest .
```

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

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

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

```bash
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` 不构建镜像，只使用已有镜像启动。部署前先完成本地构建或从仓库拉取镜像。

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

使用远程镜像时：

```bash
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:<端口>`。

停止服务：

```bash
docker-compose down
```

## 日志

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

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

## 常见问题

- **普通用户看不到工作空间**：已改为读用户 profile 的 `workspace_list`，不要用工作空间管理接口
- **未提供 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`