Personal Knowledge MCP Server

Personal Knowledge MCP Server

个人知识库 MCP 服务器 - 将本地文档、飞书、企业微信文档统一索引，通过 MCP 协议提供给 AI 客户端（如 Cherry Studio）访问。

✨ 功能特性

Phase 1 (已实现)

• ✅ 本地文档索引（支持 TXT, MD, PDF, DOCX, PPTX）
• ✅ 全文搜索（SQLite FTS5）
• ✅ MCP 协议接口
• ✅ 文档元数据管理

Phase 2-3 (规划中)

• 🚧 飞书文档同步
• 🚧 企业微信文档同步
• 🚧 语义搜索（向量化）

🚀 快速开始

1. 安装依赖

cd personal-knowledge-mcp
npm install

2. 配置

编辑 config.json，设置你想要索引的文档路径：

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

3. 构建项目

npm run build

4. 索引本地文档

npm run index

输出示例：

开始扫描本地文档...
扫描目录: ~/Documents
找到 45 个 .md 文件
找到 12 个 .pdf 文件
正在保存 57 个文档到数据库...
索引完成！

数据库统计:
  local: 57 个文档

5. 配置 Cherry Studio

在 Cherry Studio 中添加 MCP Server：

方法 1: 通过 UI 配置

1. 打开 Cherry Studio 设置
2. 找到 "MCP Servers" 或 "Model Context Protocol"
3. 添加新的 Server
4. 配置如下：

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

方法 2: 直接编辑配置文件

找到 Cherry Studio 的配置文件（通常在 ~/.cherry-studio/config.json 或应用设置目录），添加：

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

6. 在 Cherry Studio 中使用

重启 Cherry Studio 后，你可以在对话中使用以下方式访问知识库：

请帮我搜索知识库中关于"TypeScript 泛型"的文档

AI 会自动调用 search_documents 工具进行搜索。

🛠️ MCP 工具列表

服务器提供以下 MCP 工具：

1. `search_documents`

搜索知识库中的文档

参数:

• query (必填): 搜索关键词
• source (可选): 限定来源 ('local', 'feishu', 'wecom')
• limit (可选): 返回数量，默认 20

示例:

{
  "query": "React Hooks",
  "source": "local",
  "limit": 10
}

2. `get_document`

获取完整文档内容

参数:

• document_id (必填): 文档 ID

3. `list_documents`

列出所有文档

参数:

• source (可选): 限定来源
• limit (可选): 返回数量，默认 50

4. `get_stats`

获取知识库统计信息

返回示例:

{
  "stats": {
    "local": 57,
    "feishu": 0,
    "wecom": 0
  }
}

5. `sync_local_documents`

手动触发本地文档同步

📁 项目结构

personal-knowledge-mcp/
├── src/
│   ├── index.ts              # 入口文件
│   ├── server.ts             # MCP Server 实现
│   ├── types.ts              # TypeScript 类型定义
│   ├── storage/
│   │   └── database.ts       # SQLite 数据库管理
│   ├── crawlers/
│   │   └── local-crawler.ts  # 本地文档爬虫
│   └── utils/
│       └── file-parser.ts    # 文件解析器
├── data/
│   └── knowledge.db          # SQLite 数据库（自动生成）
├── config.json               # 配置文件
├── package.json
├── tsconfig.json
└── README.md

🔧 常见问题

Q: 索引速度慢？

A:

• 减少 watch_paths 的范围
• 使用 exclude_patterns 排除大型目录
• 大型 PDF 文件解析较慢，可以先排除

Q: 搜索不到文档？

A:

1. 确认文档已被索引（运行 npm run index）
2. 检查 file_extensions 是否包含你的文件类型
3. 尝试使用不同的关键词（支持 SQLite FTS5 语法）

Q: Cherry Studio 连接失败？

A:

1. 确认已运行 npm run build
2. 检查配置中的路径是否为绝对路径
3. 查看 Cherry Studio 的日志输出

Q: 如何更新索引？

A: 重新运行 npm run index 即可。已存在的文档会被更新，删除的文件会被移除。

📈 性能优化建议

1. 定期清理数据库: 删除不再需要的文档
2. 合理设置监控路径: 避免监控整个硬盘
3. 限制文件大小: 在 local-crawler.ts 中可以添加文件大小限制
4. 使用 SSD: 数据库访问速度直接影响搜索性能

🛣️ 下一步计划

Phase 2: 飞书集成

1. OAuth 认证
2. 文档列表获取
3. 内容下载和解析
4. 增量同步

Phase 3: 企业微信集成

1. 评估 API 可用性
2. 实现文件下载
3. 或采用手动导出方案

Phase 4: 高级搜索

1. 接入本地 Embedding 模型（ollama）
2. 向量化文档
3. 语义搜索 + 关键词搜索混合

📝 开发说明

# 开发模式（自动编译）
npm run dev

# 手动编译
npm run build

# 索引文档
npm run index

# 启动 MCP Server
npm start

⚠️ 重要提示

1. 合规性: 确保索引企业文档符合公司信息安全政策
2. 权限: 某些文档可能需要管理员授权才能访问
3. 隐私: 本地数据库包含文档内容，注意保护
4. 备份: 定期备份 data/knowledge.db

📄 许可证

MIT

问题反馈: 如遇到问题，请检查日志输出并提供详细错误信息。