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

命令参考

命令	说明
npm run build	编译 TypeScript
npm run dev	开发模式（watch 编译）
npm run index	索引本地文档（增量）
npm run embed	生成文档 embedding 向量
npm start	启动 MCP Server
npm run sync	预留脚本，当前未实现完整“同步所有文档源”流程

搜索架构

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

• 关键词搜索擅长精确匹配（函数名、错误码、专有名词）
• 向量搜索擅长语义匹配（"怎么处理超时" 匹配 "timeout handling"）
• RRF (Reciprocal Rank Fusion) 融合两者排名，无需训练数据
• 同一文档最多返回 3 个不同片段，避免遗漏长文档中的多处命中
• Snippet 自动定位到查询词出现位置，而非固定截取开头

MCP 工具列表

知识库工具

工具	说明
search_documents	搜索文档（支持混合检索）
get_document	获取完整文档内容
list_documents	列出文档（按更新时间排序）
get_stats	获取统计信息
sync_local_documents	手动触发本地文档同步
index_file	索引单个本地文件（适合新写入文件的秒级可搜）

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

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

工具	说明
get_bitable_records	获取多维表格记录（支持筛选、排序）
list_bitable_tables	列出多维表格中的数据表
create_bitable_records	创建多维表格记录（批量）
update_bitable_record	更新单条多维表格记录
batch_update_bitable_records	批量更新多维表格记录
delete_bitable_records	删除多维表格记录（批量）
list_wiki_spaces	列出可访问的知识空间列表
get_wiki_nodes	获取知识空间节点列表（支持递归）
get_wiki_node_content	获取知识库文档内容（只需 node_token）
get_docx_content	获取云文档纯文本内容
list_drive_files	列出云盘文件夹中的文件
get_drive_file_content	获取云盘文件内容
get_sheet_data	获取电子表格数据
list_sheets	列出电子表格工作表
write_sheet_data	写入电子表格数据
append_sheet_data	追加电子表格数据
list_bitable_fields	列出多维表格字段定义
create_bitable_field	创建多维表格字段
update_bitable_field	更新多维表格字段
delete_bitable_field	删除多维表格字段

项目结构

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