# NoteBridge MCP

统一多平台笔记 MCP 服务器 - 一个项目管理飞书、Notion、语雀三大平台。

## 架构说明

NoteBridge MCP 采用**单一服务器架构**，将三个平台的工具整合到一个 MCP 服务器中：

```
┌─────────────────────────────────────────────────────────────┐
│                    Claude Code                               │
└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                 NoteBridge MCP Server                        │
│                    (73 个工具)                                │
├─────────────────────────────────────────────────────────────┤
│  飞书 (55个工具)  │  Notion (10个工具)  │  语雀 (8个工具)     │
└─────────────────────────────────────────────────────────────┘
```

**优势**：
- ✅ **单一项目**：一个 package.json，一个入口文件
- ✅ **单一配置**：一个 .mcp.json 搞定
- ✅ **统一管理**：所有工具在同一个服务器中
- ✅ **完整功能**：73 个工具覆盖三大平台

---

## 快速开始

### 1. 安装依赖

```bash
cd D:\notebridge-mcp
bun install
```

### 2. 配置 Token

编辑 `D:\notebridge-mcp\.mcp.json`，替换以下 Token：

```json
{
  "mcpServers": {
    "notebridge": {
      "command": "C:/Users/Siat/.bun/bin/bun.exe",
      "args": ["run", "D:/notebridge-mcp/src/index.ts"],
      "env": {
        "LARK_APP_ID": "your_lark_app_id",
        "LARK_APP_SECRET": "your_lark_app_secret",
        "NOTION_API_KEY": "your_notion_token",
        "YUQUE_TOKEN": "your_yuque_token"
      }
    }
  }
}
```

### 3. 复制配置到 Claude

```bash
cp D:\notebridge-mcp\.mcp.json ~/.claude/mcp.json
```

### 4. 重启 Claude Code

关闭并重新打开 Claude Code，即可使用全部 73 个工具。

---

## API 权限清单

### 飞书 (Lark) 所需权限

在 [飞书开放平台](https://open.feishu.cn/app) 中配置：

| 权限 | 说明 | 用途 |
|------|------|------|
| `wiki:wiki` | Wiki 读写 | 知识库操作 |
| `wiki:node:move` | 移动 Wiki 节点 | 节点移动 |
| `docx:document:readonly` | 文档只读 | 读取文档 |
| `docx:document` | 文档读写 | 创建/更新文档 |
| `docx:document:create` | 创建文档 | 新建文档 |
| `drive:drive` | 云盘操作 | 文件管理 |
| `bitable:app` | 多维表格 | 表格操作 |
| `task:task:read` | 读取任务 | 待办事项 |
| `task:task:write` | 写入任务 | 创建待办 |
| `task:tasklist:read` | 读取任务清单 | 清单管理 |
| `task:tasklist:write` | 写入任务清单 | 创建清单 |
| `task:section:write` | 任务分组 | 分组管理 |
| `contact:contact.base:readonly` | 联系人 | 部门成员 |
| `contact:user.base:readonly` | 用户信息 | 获取用户 |
| `contact:user.email:readonly` | 用户邮箱 | 获取邮箱 |
| `offline_access` | 离线访问 | Token 刷新 |

**配置步骤**：
1. 登录 [飞书开放平台](https://open.feishu.cn/app)
2. 进入你的应用 → 权限管理
3. 添加上述所有权限
4. 版本管理 → 发布新版本
5. 重新授权

### Notion 所需权限

在 [Notion Integrations](https://www.notion.so/profile/integrations) 中配置：

| 权限 | 说明 | 用途 |
|------|------|------|
| Read content | 读取内容 | 搜索、读取页面/数据库 |
| Update content | 更新内容 | 更新页面/数据库 |
| Insert content | 插入内容 | 创建页面/数据库 |
| Read user information | 读取用户信息 | 获取用户信息 |

**配置步骤**：
1. 访问 https://www.notion.so/profile/integrations
2. 点击 "New integration"
3. 填写名称，选择工作区
4. 在 Capabilities 中勾选上述权限
5. 点击 "Submit"
6. 复制 "Internal Integration Token"（以 `ntn_` 开头）
7. **重要**：在 Notion 中连接需要访问的页面
   - 打开目标页面
   - 点击右上角 `···` → Connections
   - 选择你的 Integration

### 语雀 (Yuque) 所需权限

在 [语雀 Token 设置](https://www.yuque.com/settings/tokens) 中配置：

| 权限 | 说明 | 用途 |
|------|------|------|
| 读取 | 读取知识库和文档 | 搜索、读取 |
| 写入 | 创建和更新文档 | 创建、更新、删除 |

**配置步骤**：
1. 登录 https://www.yuque.com
2. 点击右上角头像 → 账户设置
3. 左侧菜单 → Token
4. 点击 "新建 Token"
5. 填写名称，选择 "读写" 权限
6. 点击 "确定"
7. **立即复制 Token**（只显示一次）

---

## 完整工具列表

### 飞书工具 (55个)

#### 认证工具 (5个)
| 工具 | 说明 |
|------|------|
| `lark_auth_url` | 自动 OAuth 授权 |
| `lark_auth` | 手动提交授权码 |
| `user_me` | 获取当前用户信息 |
| `user_get` | 查询指定用户 |
| `user_list` | 列出部门成员 |

#### Wiki 工具 (10个)
| 工具 | 说明 |
|------|------|
| `wiki_spaces` | 列出所有 Wiki 空间 |
| `wiki_list_nodes` | 列出 Wiki 节点 |
| `wiki_read` | 读取 Wiki 内容 |
| `wiki_update` | 更新 Wiki 内容 |
| `wiki_prepend` | 在 Wiki 顶部插入 |
| `wiki_append` | 在 Wiki 底部追加 |
| `wiki_insert_blocks` | 在指定位置插入 |
| `wiki_delete_blocks` | 删除指定范围 |
| `wiki_create_node` | 创建新节点 |
| `wiki_move_node` | 移动节点 |

#### 文档工具 (16个)
| 工具 | 说明 |
|------|------|
| `doc_create` | 创建文档 |
| `doc_read` | 读取文档 |
| `doc_prepend` | 在文档顶部插入 |
| `doc_append` | 在文档底部追加 |
| `doc_update` | 更新文档 |
| `doc_delete` | 删除文档 |
| `doc_move` | 移动文档 |
| `doc_insert_blocks` | 在指定位置插入 |
| `doc_delete_blocks` | 删除指定范围 |
| `doc_move_blocks` | 移动块 |
| `doc_search_blocks` | 搜索块 |
| `doc_indent_block` | 缩进/取消缩进 |
| `doc_batch_update_blocks` | 批量更新 |
| `drive_list` | 列出云盘文件 |
| `drive_recent` | 列出最近文件 |
| `lark_search` | 全局搜索 |

#### 格式转换工具 (1个)
| 工具 | 说明 |
|------|------|
| `blocks_to_markdown` | Blocks 转 Markdown |

#### 待办工具 (8个)
| 工具 | 说明 |
|------|------|
| `todo_list` | 列出待办 |
| `todo_create` | 创建待办 |
| `todo_search` | 搜索待办 |
| `todo_update` | 更新待办 |
| `todo_add_members` | 添加负责人 |
| `todo_remove_members` | 移除负责人 |
| `task_complete` | 完成任务 |
| `task_delete` | 删除任务 |

#### 任务清单工具 (7个)
| 工具 | 说明 |
|------|------|
| `tasklist_list` | 列出清单 |
| `tasklist_create` | 创建清单 |
| `tasklist_get` | 获取清单详情 |
| `tasklist_update` | 更新清单 |
| `tasklist_delete` | 删除清单 |
| `tasklist_add_task` | 添加任务到清单 |
| `tasklist_remove_task` | 从清单移除任务 |
| `tasklist_tasks` | 列出清单任务 |

#### 子任务工具 (3个)
| 工具 | 说明 |
|------|------|
| `subtask_create` | 创建子任务 |
| `subtask_list` | 列出子任务 |
| `subtask_update` | 更新子任务 |

#### 任务分组工具 (4个)
| 工具 | 说明 |
|------|------|
| `section_list` | 列出分组 |
| `section_tasks` | 列出分组任务 |
| `section_create` | 创建分组 |
| `section_delete` | 删除分组 |

### Notion 工具 (22个)

| 工具 | 说明 |
|------|------|
| `API-post-search` | 搜索页面和数据库 |
| `API-retrieve-a-page` | 获取页面详情 |
| `API-create-a-page` | 创建页面 |
| `API-update-page-properties` | 更新页面属性 |
| `API-retrieve-a-database` | 获取数据库详情 |
| `API-query-a-database` | 查询数据库 |
| `API-create-a-database` | 创建数据库 |
| `API-update-a-database` | 更新数据库 |
| `API-retrieve-a-block` | 获取块详情 |
| `API-retrieve-block-children` | 获取子块 |
| `API-append-block-children` | 追加子块 |
| `API-update-a-block` | 更新块 |
| `API-delete-a-block` | 删除块 |
| `API-retrieve-a-user` | 获取用户详情 |
| `API-list-all-users` | 列出用户 |
| `API-list-comments` | 列出评论 |
| `API-create-a-comment` | 创建评论 |
| `API-retrieve-a-page-property` | 获取页面属性 |
| `API-retrieve-content-lake` | 获取内容湖 |
| `API-create-a-data-source` | 创建数据源 |
| `API-query-data-source` | 查询数据源 |
| `API-move-page` | 移动页面 |

### 语雀工具 (8个)

| 工具 | 说明 |
|------|------|
| `yuque_repo_list` | 列出知识库 |
| `yuque_repo_get` | 获取知识库详情 |
| `yuque_doc_list` | 列出文档 |
| `yuque_doc_get` | 获取文档详情 |
| `yuque_doc_create` | 创建文档 |
| `yuque_doc_update` | 更新文档 |
| `yuque_doc_delete` | 删除文档 |
| `yuque_search` | 搜索内容 |

---

## 使用示例

### 跨平台搜索

```
帮我搜索所有平台上关于"项目进展"的内容
```

Claude 会并行调用：
- `lark_search` 搜索飞书
- `API-post-search` 搜索 Notion
- `yuque_search` 搜索语雀

### 内容迁移

```
把我 Notion 上的"产品需求文档"复制到飞书知识库
```

Claude 会：
1. `API-retrieve-a-page` 读取 Notion 文档
2. `API-retrieve-block-children` 获取内容
3. `wiki_create_node` 在飞书创建页面
4. `wiki_append` 写入内容

### 统一待办

```
查看我在所有平台上的待办事项
```

Claude 会：
- `todo_list` 获取飞书待办
- `API-query-a-database` 查询 Notion 数据库（如果有待办数据库）

---

## 项目结构

```
D:\notebridge-mcp\
├── package.json             # 统一依赖管理
├── tsconfig.json
├── README.md                # 本文档
├── .mcp.json                # MCP 配置文件
└── src/
    ├── index.ts             # 入口文件
    ├── constants.ts         # 常量配置（三个平台）
    ├── lifecycle.ts         # 生命周期管理
    ├── services/
    │   ├── lark-client.ts   # 飞书 API 客户端
    │   ├── notion-client.ts # Notion API 客户端
    │   └── yuque-client.ts  # 语雀 API 客户端
    ├── tools/
    │   ├── auth.ts          # 飞书认证工具 (5个)
    │   ├── wiki.ts          # 飞书 Wiki 工具 (10个)
    │   ├── doc.ts           # 飞书文档工具 (16个)
    │   ├── todo.ts          # 飞书待办工具 (24个)
    │   ├── notion.ts        # Notion 工具 (10个)
    │   └── yuque.ts         # 语雀工具 (8个)
    ├── schemas/
    │   ├── common.ts
    │   ├── auth.ts
    │   ├── wiki.ts
    │   ├── doc.ts
    │   └── todo.ts
    └── utils/
        ├── errors.ts
        ├── rate-limiter.ts
        ├── retry.ts
        ├── markdown.ts
        ├── oauth-callback.ts
        └── response.ts
```

---

## 常见问题

### Q: 重启后工具没有出现？

A: 检查 `~/.claude/mcp.json` 文件是否存在且格式正确。

### Q: API 调用失败？

A: 检查 Token 是否有效，权限是否完整。参考上方的「API 权限清单」。

### Q: 如何更新某个平台？

A: 进入对应目录执行 git pull 即可，各平台独立更新：
```bash
cd D:\lark-office-mcp && git pull
cd D:\notion-mcp-server && git pull
cd D:\yuque-mcp-server && git pull
```

### Q: 如何添加更多平台？

A: 参考现有项目结构，创建新的 MCP 服务器，然后在 `.mcp.json` 中添加配置。

---

## 更新日志

### v1.0.0 (2026-06-10)

- 初始版本
- **单一项目**整合飞书、Notion、语雀三大平台
- 73 个工具（飞书 55 + Notion 10 + 语雀 8）
- 统一的 API 客户端和错误处理
- 完整的权限清单和配置指南

---

## 相关项目

本项目在设计上参考了以下两个仓库：

- [lark-office-mcp](https://github.com/YSzEthan/lark-office-mcp)
- [notion-mcp-server](https://github.com/makenotion/notion-mcp-server)

---

## License

MIT