内容
# kb-mcp
一个MCP服务器，使您的Obsidian/markdown保险库可搜索——文本、PDF、办公文档、图像和音频——从任何MCP客户端（Claude、Cursor等）内部。自主托管；您的文件仍然属于您。
## 为什么选择kb-mcp
- **在您的工作环境中为您提供服务**。kb-mcp是一个MCP *服务器*：您的知识库（KB）作为原生工具出现在Claude、Cursor或任何MCP客户端中——桌面和移动设备。您不需要切换到新的应用程序；KB直接在您已经使用的代理中可用。
- **在原处，不建立孤岛**。它读取和写入您的实际markdown文件。它们保持原样、可移植，并且属于您——在Obsidian中可编辑，版本控制/备份方式随您喜欢。大多数笔记-AI工具导入 *副本* 到它们自己的存储库中；kb-mcp直接操作原始文件。
- **多模态，不仅限于文本**。除了markdown，它还提取和搜索PDF、办公文档（docx/xlsx/pptx）、图像（OCR + CLIP视觉搜索）和音频/视频（语音转文本）——这样，照片、扫描的发票或录音也可以被找到。（办公/音频提取很常见；独特的组合是多模态 + MCP原生 + 在您的实时保险库上，加上CLIP *视觉* 检索。）
- **真正的检索，不依赖简单的RAG**。混合BM25 + 向量通过 reciprocal-rank-fusion融合，加上wikilink图信号和类型感知排序，在 *类型* 的语料库（原始来源 vs 编译笔记）上，具有出处和写入治理。
- **基础架构，而不是大脑**。服务器只执行确定性工作（搜索、提取、嵌入）；推理发生在您的客户端模型中。没有服务器端LLM，没有专有云后端。
## 比较
- **vs. doc-chat / RAG应用**：它们将副本导入它们自己的存储库中，您需要在它们的UI中工作；kb-mcp在您的实时保险库上工作，在您现有的代理中。
- **vs. 其他MCP笔记服务器**：大多数只支持文本搜索/CRUD；kb-mcp添加多模态提取 + CLIP视觉搜索 + 类型化的知识模型。
## 快速入门（本地）
最快的路径是 **本地，在Claude Code中，在您自己的保险库上——无需云，无需OAuth，大约20分钟**：
```bash
git clone <repo-url> kb-mcp && cd kb-mcp
python3 -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
pip install -e . # 精简版：关键词/BM25搜索，无重依赖
python -m kb_mcp init --vault "/path/to/your/Obsidian"
claude mcp add kb-mcp --env KB_MCP_VAULT_PATH="/path/to/your/Obsidian" \
--env KB_MCP_DISABLE_EMBEDDINGS=1 -- python -m kb_mcp --transport stdio
python -m kb_mcp install-skill # “大脑” - 不要跳过此步骤
```
**[SETUP-LOCAL.md](SETUP-LOCAL.md)** 指导本地路径的完成（保险库引导、混合与精简版选择、技能和可选的自动捕获钩子）。有关远程/移动访问，请参见 **[docs/deployment.md](docs/deployment.md)**。
## 工具
两个层级。第一层是类型路由的，编码了KB学科；第二层是文件系统的逃生口，供第一层无法表达的内容使用。
**第一层 — 类型路由（主要）**。在适合第一层操作时使用这些。
- `find` — 在 `Knowledge Base/` 上进行只读搜索，按类型/项目/标签过滤。
- `get` — 读取保险库根目录下任意位置的完整文件（包括只读精选输入文件夹）。`frontmatter_only=true` 只返回frontmatter。
- `add` — 捕获原始 `source` 页面，具有完整的写入权限。
- `note` — 创建六种编译页面类型（研究笔记、见解、失败、模式、实验、生产日志）中的任意一种，并带有 `ingested_into:` 反向引用到引用的来源。
- `link` — 在 `Entities/<Type>/<Name>.md` 下创建一个类型化的实体（人、概念、库、决策）。
- `edit` — 在位编辑编译页面。模式：正文 / 标签 / 外科手术 `old_string`→`new_string`；`edits=[…]` （批量外科手术）；`row_key`+`take` （填充 `[take: ]` 观点行）；`field`+`value` （修补一个frontmatter字段）。增加 `updated:`。
- `replace` — 替换：写入新页面并将旧页面翻转为 `status: superseded`，带有 `superseded_by:` 反向链接。用于实质性重写的修改路径。
- `preserve` — 捕获二进制或文本工件到 `Evidence/<scope>/<category>/` （仅追加）。
- `audit` — 只读图健康检查（损坏的wikilink、孤立实体、未处理的来源、索引/日志漂移、标签不一致）。
**第二层 — 文件系统对等（逃生口）**。在第一层无法表达您需要的内容时使用：新的文件夹结构、保险库外部的文件或外科手术编辑。
> **精简界面（`KB_MCP_DISABLE_TIER2`）**。设置 `KB_MCP_DISABLE_TIER2=1` （在 `.env` 或服务环境中）以从注册中删除所有8个第二层工具；第一层操作仍然加载。当客户端 *延迟* MCP工具在关键字搜索后面时使用它 - 更小的界面意味着代理到达 `find`/`get`/`note` 而无需浏览十几个逃生口。默认情况下未设置：所有工具都已注册。
- `create_file` — 在任意保险库路径上写入文件，可选的frontmatter字典。`kind="dir"` 创建文件夹（mkdir -p）。拒绝Sources/Evidence；精选树需要 `allow_curated=true`。
- `list_directory` — 列出文件 + 子文件夹（可选递归）。为 `.md` 条目显示 `type:` frontmatter字段。只读。
- `move_file` — 重命名/重新定位。默认情况下重写传入的wikilink。
- `delete` — **删除** 文件或文件夹（自动检测）。移动到 `Knowledge Base/_trash/YYYY-MM-DD/`，带有 `.meta.json` 边车；永久删除。恢复是 `recover_from_trash`。需要 `confirm=true`；文件夹如果非空，需要 `recursive=true`；如果没有传入链接，除非 `force_orphan=true`，否则拒绝。
- `list_trash` — 枚举可恢复的删除条目（原始路径、时间戳、强制标志）。还显示漂移。只读。
- `recover_from_trash` — 撤销删除；读取边车以找到原始位置。可选 `restore_path` 覆盖。
- `append_to_file` — 追加文本。拒绝Sources/。
- `list_inbound_links` — 查找所有wikilink解析为目标的文件。只读。对移动/删除前很有用。
**在两个层级中保持一致的规范：** Sources/ 和 Evidence/ 是仅追加的（没有第二层操作写入）；精选输入文件夹（可配置）默认拒绝第二层写入 - 通过 `allow_curated=true` 作为故意逐调用确认；删除永远不会是永久的（`delete` 放入回收站，通过 `recover_from_trash` 可恢复）；每次写入都记录到 `Knowledge Base/log.md`。
**两层追溯性：**
- `Knowledge Base/log.md` — 持久的内容历史记录。只有写入，KB范围。“保险库发生了什么”记录；永远不会自动清除。
- `logs/kb-mcp.log` — 服务日志。每个调用（读取 + 写入）都通过每个调用中间件显示为 `tool=<name> duration_ms=<n> event=tool_success|tool_error`。操作层（调用是否到达服务器，检测慢操作）。在进程中轮换（5 MB × 5）- 每个平台都是如此。
## 多模态提取（可选）
两个可选的依赖项附加项将二进制文件转换为可搜索的文本/向量。两者 **软降级**：如果库未安装，搜索降级为关键词/BM25，上传仍然有效，只是没有服务器端提取。
- **`embeddings`** (`pip install -e ".[embeddings]"`) — `torch` + `sentence-transformers` + `pillow`。为混合 `find` 添加本地向量部分（bge文本模型）和 **CLIP** 图像嵌入用于视觉搜索。~1–2 GB 下载。
- **`media`** (`pip install -e ".[media]"`) — 上传时在服务器端提取：**faster-whisper** ASR用于音频/视频，**Tesseract** OCR用于图像，**PyMuPDF** 用于PDF，**MarkItDown** 用于办公/HTML文档（docx/xlsx/pptx/html）。两个系统工具不可通过pip安装：**Tesseract OCR** (`winget install UB-Mannheim.TesseractOCR`，或设置 `KB_MCP_TESSERACT_CMD`)，以及ffmpeg（由PyAV通过faster-whisper捆绑，因此音频/视频解码开箱即用）。
**GPU注意。** CUDA GPU加速ASR/OCR/嵌入，但 **不是必需的** - CPU工作，只是速度较慢（选择较小的Whisper模型，`KB_MCP_WHISPER_MODEL=base`）。在Windows + NVIDIA上，`media`附加项固定了一个CUDA-12运行时（cublas/cudnn/cudart），ctranslate2需要它与torch的cu132构建一起；支持RTX 50系列（Blackwell，sm_120）。请参阅 **[docs/deployment.md](docs/deployment.md)** 获取GPU启动和Blackwell/CUDA详细信息。完全禁用提取，设置 `KB_MCP_DISABLE_MEDIA_EXTRACTION=1` （上传仍然有效；没有可搜索文本提取）。
## 远程访问（可选）
要从claude.ai在网页或移动设备上访问保险库，服务器作为一个始终在线的HTTP服务运行在公共HTTPS端点后面，通过 **GitHub OAuth** 认证锁定到单个登录。claude.ai的MCP客户端从Anthropic的云（不是从您的手机）获取连接器URL，因此端点必须是公开可访问的 - **Cloudflare Tunnel**（您拥有的域名）或 **Tailscale Funnel**（免费 `*.ts.net` 主机）提供它。
完整的设置 - OAuth应用、隧道、服务安装程序（launchd / systemd / NSSM）、多主机部署和故障排除 - 在 **[docs/deployment.md](docs/deployment.md)** 中。替换 `<your-host>` / `example.com` 为您的主机名。
## 配置
服务器从环境变量（或存储库根目录中的 `.env` 文件）读取配置。唯一必需的是保险库路径。
| 变量 | 用途 |
|---|---|
| `KB_MCP_VAULT_PATH` | **必需。** 保险库根目录 - 包含 `Knowledge Base/` 的文件夹。 |
| `KB_MCP_DISABLE_EMBEDDINGS` | `1` 强制仅关键词/BM25搜索（无torch/向量）。 |
| `KB_MCP_DISABLE_TIER2` | `1` 删除8个第二层逃生口工具（更简洁的工具界面）。 |
| `KB_MCP_DISABLE_MEDIA_EXTRACTION` | `1` 跳过服务器端OCR/ASR/PDF/办公文档提取。 |
| `KB_MCP_DISABLE_CLIP` | `1` 禁用CLIP视觉图像搜索。 |
| `KB_MCP_CLIP_DEVICE` | `cpu`/`cuda` CLIP的重写（ASR激活时默认为CPU）。 |
| `KB_MCP_WHISPER_MODEL` | ASR的Whisper模型大小（例如 `base`，`small`，`large-v3`）。 |
| `KB_MCP_TESSERACT_CMD` | 如果未自动发现，则`tesseract`二进制文件的路径。 |
| `KB_MCP_DUP_THRESHOLD` | 近似重复的余弦警告阈值（默认 `0.90`）。 |
| `KB_MCP_DISABLE_QUERY_LOG` | `1` 禁用检索评估查询/写入日志。 |
| `KB_MCP_HOST` | HTTP传输的绑定主机（默认 `127.0.0.1`）。 |
仅限远程（参见 [docs/deployment.md](docs/deployment.md)）：`KB_MCP_BASE_URL`，`GITHUB_CLIENT_ID`，`GITHUB_CLIENT_SECRET`，`KB_MCP_GITHUB_USERNAME`，`KB_MCP_JWT_SIGNING_KEY`。
## 许可证
AGPL-3.0-or-later - 请参阅 [LICENSE](LICENSE)。
