# Personal Knowledge MCP Server
个人知识库 MCP 服务器 - 将本地文档、飞书、企业微信文档统一索引，通过 MCP 协议提供给 AI 客户端（如 Cherry Studio）访问。
## ✨ 功能特性
**Phase 1 (已实现)**
- ✅ 本地文档索引（支持 TXT, MD, PDF, DOCX, PPTX）
- ✅ 全文搜索（SQLite FTS5）
- ✅ MCP 协议接口
- ✅ 文档元数据管理
**Phase 2-3 (规划中)**
- 🚧 飞书文档同步
- 🚧 企业微信文档同步
- 🚧 语义搜索（向量化）
## 🚀 快速开始
### 1. 安装依赖
```bash
cd personal-knowledge-mcp
npm install
```
### 2. 配置
编辑 `config.json`，设置你想要索引的文档路径：
```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. 构建项目
```bash
npm run build
```
### 4. 索引本地文档
```bash
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. 配置如下：
```json
{
"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` 或应用设置目录），添加：
```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
**示例:**
```json
{
"query": "React Hooks",
"source": "local",
"limit": 10
}
```
### 2. `get_document`
获取完整文档内容
**参数:**
- `document_id` (必填): 文档 ID
### 3. `list_documents`
列出所有文档
**参数:**
- `source` (可选): 限定来源
- `limit` (可选): 返回数量，默认 50
### 4. `get_stats`
获取知识库统计信息
**返回示例:**
```json
{
"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. 语义搜索 + 关键词搜索混合
## 📝 开发说明
```bash
# 开发模式（自动编译）
npm run dev
# 手动编译
npm run build
# 索引文档
npm run index
# 启动 MCP Server
npm start
```
## ⚠️ 重要提示
1. **合规性**: 确保索引企业文档符合公司信息安全政策
2. **权限**: 某些文档可能需要管理员授权才能访问
3. **隐私**: 本地数据库包含文档内容，注意保护
4. **备份**: 定期备份 `data/knowledge.db`
## 📄 许可证
MIT
---
**问题反馈**: 如遇到问题，请检查日志输出并提供详细错误信息。
