Personal Knowledge MCP Server

个人知识库 MCP 服务器 — 对本地文档建立索引，并提供一组飞书 API 工具，通过 MCP 协议供 AI 客户端访问。

支持 BM25 关键词搜索 + 向量语义搜索的混合检索（Hybrid Search），基于 RRF 融合排名，全部运行在单个 SQLite 文件中，零外部依赖。

当前项目现状、能力边界和使用建议，以 PROJECT_STATUS.md 为准。

当前代码里，search_documents 主要搜索本地已索引文件；飞书内容当前主要通过独立 MCP 工具按需读取/写入，并不会自动统一同步进本地 SQLite 索引。

功能特性

• 本地文档索引（TXT, MD, PDF, DOCX, PPTX）

• 中文分词优化（jieba）

• 文档智能分块（按标题/段落切分）

• 混合搜索：FTS5 BM25 关键词检索 + sqlite-vec 向量 KNN 检索 + RRF 融合

• 本地 embedding 模型（all-MiniLM-L6-v2，384 维，零 API 调用）

• 增量索引（基于文件 mtime，跳过未变更文件）

• 死文档自动清理

• 搜索结果返回查询词定位 snippet（自动居中到匹配位置）

• 同一文档返回多个命中片段（最多 3 个 chunk）

• 标题匹配 10x 加权

• 飞书集成：云文档、多维表格、电子表格、知识库读写工具

• Work Wiki 基础设施：index_file 增量索引 + 本地搜索 + 飞书工具

• MCP 协议标准接口

快速开始

1. 安装依赖

npm install

2. 配置

编辑 config.json：

{
  "local": {
    "enabled": true,
    "watch_paths": [
      "~/Documents",
      "~/Desktop"
    ],
    "file_extensions": [".txt", ".md", ".pdf", ".docx", ".pptx"],
    "exclude_patterns": ["**/node_modules/**", "**/.git/**"]
  },
  "feishu": {
    "enabled": false,
    "app_id": "",
    "app_secret": ""
  },
  "database": {
    "path": "./data/knowledge.db"
  }
}

3. 构建

npm run build

4. 索引文档

npm run index

增量模式：只处理新增/修改的文件，自动清理已删除文件的索引，自动为新增/变更文档生成 embedding 向量。

5. 补跑向量索引（可选）

npm run embed

仅用于为历史存量文档补生成 embedding。日常使用无需手动调用，npm run index 和 sync_local_documents 已自动生成。

首次运行会自动下载 embedding 模型（~80MB），后续运行使用缓存。

6. 启动 MCP Server

npm start

7. 配置 AI 客户端

在 Cherry Studio / Cursor / 其他 MCP 客户端中添加：

{
  "personal-knowledge": {
    "command": "node",
    "args": ["/absolute/path/to/personal-knowledge-mcp/dist/index.js"],
    "cwd": "/absolute/path/to/personal-knowledge-mcp"
  }
}

如果你希望快速了解当前代码现实，而不是只看产品概述，建议先读：

PROJECT_STATUS.md

命令参考

搜索架构

查询 → jieba 分词 → FTS5 BM25 搜索 ─┐
                                       ├→ RRF 融合排名 → 每文档最多3片段 → Top-K
查询 → embedding 模型 → sqlite-vec KNN ┘

• 关键词搜索擅长精确匹配（函数名、错误码、专有名词）

• 向量搜索擅长语义匹配（"怎么处理超时" 匹配 "timeout handling"）

• RRF (Reciprocal Rank Fusion) 融合两者排名，无需训练数据

• 同一文档最多返回 3 个不同片段，避免遗漏长文档中的多处命中

• Snippet 自动定位到查询词出现位置，而非固定截取开头

MCP 工具列表

知识库工具

飞书工具（需在 config.json 中启用）

以下工具是“直连飞书 Open API”的工具层，不等于“飞书内容已进入本地搜索索引”。

项目结构

personal-knowledge-mcp/
├── src/
│   ├── index.ts                # 入口（动态 import，解决 onnxruntime 线程问题）
│   ├── server.ts               # MCP Server 实现
│   ├── types.ts                # TypeScript 类型定义
│   ├── storage/
│   │   └── database.ts         # SQLite + FTS5 + sqlite-vec 数据库
│   ├── crawlers/
│   │   └── local-crawler.ts    # 本地文档爬虫（增量索引）
│   ├── feishu/                 # 飞书 API 集成
│   │   ├── client.ts           # 飞书客户端
│   │   ├── bitable.ts          # 多维表格
│   │   ├── sheets.ts           # 电子表格
│   │   ├── wiki.ts             # 知识库
│   │   ├── docx.ts             # 云文档
│   │   └── drive.ts            # 云盘
│   └── utils/
│       ├── file-parser.ts      # 文件解析（PDF/DOCX/PPTX）
│       ├── tokenizer.ts        # 中文分词（jieba）
│       ├── chunker.ts          # 文档分块
│       └── embedder.ts         # 本地 embedding 模型（批量推理）
├── data/
│   └── knowledge.db            # SQLite 数据库（自动生成）
├── config.json                 # 配置文件
└── package.json

数据库 Schema

documents          主文档表（id, source, title, content, metadata）
chunks             文档分块表（doc_id, chunk_index, content, tokenized_content）
chunks_fts         FTS5 全文索引（基于分块，中文分词后存储）
chunks_vec         sqlite-vec 向量索引（384 维 float embedding）

已知问题

Node.js v24 + onnxruntime-node 存在线程 mutex 兼容性问题，进程退出时可能出现 mutex lock failed 错误。不影响功能，embedding 生成和搜索均正常工作。index.ts 已通过动态 import 和 OMP_NUM_THREADS=1 环境变量缓解此问题。

另外需要注意：

• 当前没有 feishu-crawler，也没有“飞书全文自动同步入本地库”的实现

• npm run sync 目前是预留脚本，不应当作可用的全量同步入口

• LocalCrawler.startWatching() 已实现，但默认启动路径没有启用文件监听；当前仍以手动 npm run index 为主

常见问题

索引速度慢？ 减少 watch_paths 范围，用 exclude_patterns 排除大目录。增量索引只处理变更文件。

Embedding 生成慢？ npm run embed 使用批量推理（每批 50 条），比逐条处理快数倍。首次运行需下载模型（~80MB），后续使用缓存。

搜索不到文档？ 确认已运行 npm run index，检查 file_extensions 是否包含目标文件类型。

如何更新索引？ 重新运行 npm run index，增量处理变更文件并自动清理已删除文件，同时自动为新增/变更文档生成 embedding 向量。

飞书内容会自动进入 search_documents 吗？ 当前不会。飞书内容主要通过独立 MCP 工具按需读取。如果希望进入本地搜索，建议导出为本地文件，或按 Work Wiki 流程写入 raw/ / wiki/ 后再用 index_file 或 npm run index 建索引。

Cherry Studio 连接失败？ 确认已运行 npm run build，配置中使用绝对路径。

许可证

MIT