内容
# papermoon-mkdocs-mcp
一款适用于 MkDocs 文档站点的轻量级 MCP 服务器。直接从磁盘读取 markdown 文件，提供全文和可选的语义搜索，并通过模型上下文协议暴露项目结构。
## 功能
- **5 种 MCP 工具** -- 搜索、读取文档、列出文档、获取项目信息、获取文档大纲
- **SQLite FTS5 关键词搜索**，带有 BM25 排名（零外部依赖）
- **可选的语义向量搜索**，通过句子转换器
- **混合搜索**，结合关键词 + 向量结果与互惠排名融合
- **增量索引** -- 文件更改时快速更新
- **持久化 SQLite 索引**，在服务器重启后仍然存在
- **导航感知** -- 解析 `mkdocs.yml` 和 `.nav.yml`
- **安全优先** -- 路径遍历预防，只读搜索连接
- **最小依赖** -- 3 个必需，2 个可选
## 安装
```bash
pip install papermoon-mkdocs-mcp
```
要启用向量搜索：
```bash
pip install papermoon-mkdocs-mcp[vector]
```
## 快速开始
在任何 MkDocs 项目的根目录下运行（`mkdocs.yml` 所在的位置）：
```bash
cd /path/to/your/mkdocs-project
papermoon-mkdocs-mcp
```
或者指向特定的配置文件：
```bash
papermoon-mkdocs-mcp --config /path/to/mkdocs.yml
```
服务器在省略 `--config` 时会自动检测当前目录下的 `mkdocs.yml`。
### 传输选项
默认情况下，服务器使用 **stdio** 传输。你可以切换到网络传输以进行远程或多客户端设置：
```bash
# 流式 HTTP（推荐用于网络访问）
mkdocs-mcp --transport streamable-http --host 0.0.0.0 --port 9000
# SSE（旧版客户端兼容性）
mkdocs-mcp --transport sse --port 8080
```
| 参数 | 默认值 | 描述 |
|-----------------|---------------|--------------------------------------------------|
| `--transport` | `stdio` | `stdio`, `sse`, 或 `streamable-http` |
| `--host` | `127.0.0.1` | 绑定地址（仅限网络传输） |
| `--port` | `8000` | 绑定端口（仅限网络传输） |
> **安全注意：** 当绑定到非环回地址时，请将服务器放在一个反向代理（例如 nginx、Caddy）后面，该代理终止 TLS。
## MCP 客户端配置
### Claude Desktop
添加到您的 Claude Desktop 配置文件中：
```json
{
"mcpServers": {
"mkdocs": {
"command": "papermoon-mkdocs-mcp",
"args": ["--config", "/path/to/mkdocs.yml"]
}
}
}
```
**注意：** 如果 Claude Desktop 找不到命令（`Failed to spawn process: No such file or directory`），请使用可执行文件的完整路径而不是仅 `mkdocs-mcp`:
```json
{
"mcpServers": {
"mkdocs": {
"command": "/path/to/.venv/bin/mkdocs-mcp",
"args": ["--config", "/path/to/mkdocs.yml"]
}
}
}
```
这在将软件包安装在虚拟环境中时很常见，而虚拟环境的 `bin/` 目录不在 Claude Desktop 的 PATH 中。
### Claude Code / VS Code
在项目根目录下添加到 `.mcp.json` 中：
```json
{
"mcpServers": {
"mkdocs": {
"command": "papermoon-mkdocs-mcp",
"args": ["--config", "/path/to/mkdocs.yml"]
}
}
}
```
## 可用工具
### 搜索
使用关键词、语义或混合搜索搜索文档。
| 参数 | 类型 | 默认值 | 描述 |
|---------------|--------|------------|----------------------------------------------|
| `query` | 字符串 | （必填） | 搜索查询字符串 |
| `search_type` | 字符串 | `"hybrid"` | `"keyword"`、`"vector"` 或 `"hybrid"` |
| `max_results` | 整数 | `10` | 返回的最大结果数（1--100） |
返回带有路径、标题、相关性评分（归一化 0.0--1.0）和文本片段的排名结果。
### 读取文档
通过相对路径读取文档文件。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|------------|----------------------------------------------------|
| `path` | 字符串 | （必填） | 文档目录下的相对路径（例如 `guide/setup.md`） |
返回 markdown 正文（去掉前置信息）、解析的前置信息作为单独的字段、标题结构和文件元数据。
### 列出文档
列出所有文档文件，可选按章节筛选。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|-------------|---------|------------------------------------------|
| `section` | 字符串或 null | `null` | 要筛选的目录前缀（例如 `guide`） |
返回文档元数据（路径、标题、描述、类别、大小、修改时间）。
### 获取项目信息
获取 MkDocs 项目元数据。不带参数。
返回站点名称、站点 URL、文档目录、主题、导航树、文档数量和索引状态。
### 获取文档大纲
获取文档的标题结构（目录）。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|------------|----------------------------------------------------|
| `path` | 字符串 | （必填） | 文档目录下的相对路径（例如 `guide/setup.md`） |
返回文档标题和带有级别、文本和锚点的标题列表。
## 架构
```
src/mkdocs_mcp/
config.py -- MkDocs 配置检测和导航解析
repository.py -- SQLite 架构和 CRUD 操作
indexer.py -- 带有增量更新的索引编排
searcher.py -- 关键词、向量和混合搜索
server.py -- 带有 5 种工具定义的 FastMCP 服务器
utils.py -- 路径验证、前置信息解析、文本提取
models.py -- Pydantic 响应模型
```
启动时，服务器读取 `mkdocs.yml`，扫描文档目录，并构建（或增量更新）SQLite FTS5 索引。搜索查询直接命中索引；向量搜索使用 `all-MiniLM-L6-v2` 嵌入查询并与存储的文档嵌入进行比较。混合模式使用互惠排名融合两个结果列表。
## 开发
```bash
git clone https://github.com/aspect-build/mkdocs-mcp.git
cd mkdocs-mcp
pip install -e ".[dev]"
pytest
```
代码检查和类型检查：
```bash
ruff check .
mypy src/
```
## 需求
- Python >= 3.10
- **必需：** fastmcp (>=3.0, <4)、pydantic (>=2.0, <3)、pyyaml (>=6.0)、markdown (>=3.4)
- **可选（向量搜索）：** sentence-transformers (>=3.0)、numpy (>=1.24)
## 许可证
详见 [LICENSE](LICENSE)。
