npm package: @iflow-mcp/kyodule-personal-knowledge-mcp
Description: 个人知识库 MCP Server - 支持本地文档、飞书、企业微信
Latest version: 1.0.0

# 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

---

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