MCP 服务器

1# 语雀 MCP 服务器
2 
3[![smithery badge](https://smithery.ai/badge/@HenryHaoson/Yuque-MCP-Server)](https://smithery.ai/server/@HenryHaoson/Yuque-MCP-Server)
4 
5[English Version](./README.en.md)
6 
7一个用于与语雀 API 集成的 Model-Context-Protocol (MCP) 服务器。此实现受 [Figma-Context-MCP](https://github.com/GLips/Figma-Context-MCP) 的启发，并使用 [语雀开放 API](https://app.swaggerhub.com/apis-docs/Jeff-Tian/yuque-open_api/2.0.1)。
8 
9## 概述
10 
11该服务器提供了与语雀知识库平台交互的 MCP 工具，允许 AI 模型：
12 
13- 获取用户和文档信息
14- 创建、读取、更新和删除文档
15- 搜索语雀中的内容
16- 获取知识库信息
17- 获取统计数据和分析信息
18 
19## 安装
20 
21### 安装 via Smithery
22 
23要使用 [Smithery](https://smithery.ai) 将 Yuque MCP Server 自动安装到 Claude 桌面端：
24 
25```bash
26npx -y @smithery/cli install @HenryHaoson/Yuque-MCP-Server --client claude
27```
28 
29### 前提条件
30 
31- Node.js 18+ (推荐)
32- 拥有 API 令牌的语雀账号
33 
34### 设置
35 
361. 克隆此仓库：
37   ```
38   git clone https://github.com/Henryhaoson/Yueque-MCP-Server.git
39   cd Yueque-MCP-Server
40   ```
41 
422. 安装依赖：
43   ```
44   npm install
45   ```
46 
473. 基于 `.env.example` 创建 `.env` 文件：
48   ```
49   cp .env.example .env
50   ```
51 
524. (可选) 在 `.env` 文件中添加你的语雀 API 令牌：
53   ```
54   YUQUE_API_TOKEN=your_yuque_api_token_here
55   ```
56   
57   你也可以选择在连接到服务器时通过查询参数提供令牌，而不是在 .env 文件中设置。
58 
59## 使用方法
60 
61### 运行服务器
62 
63#### 开发模式
64 
65```bash
66# HTTP 服务器模式
67npm run dev
68 
69# CLI stdio 模式
70npm run dev:cli
71```
72 
73#### 生产模式
74 
75首先，构建项目：
76 
77```bash
78npm run build
79```
80 
81然后在 HTTP 或 CLI 模式下运行：
82 
83```bash
84# HTTP 服务器模式
85npm run start
86 
87# CLI stdio 模式
88npm run start:cli
89```
90 
91### 使用 Docker 部署
92 
93本项目提供了 Docker 支持，使您可以轻松地容器化和部署服务器。
94 
95#### 使用 Docker Compose（推荐）
96 
971. 构建并启动容器：
98   ```bash
99   docker-compose up -d
100   ```
101 
1022. 查看日志：
103   ```bash
104   docker-compose logs -f
105   ```
106 
1073. 停止服务：
108   ```bash
109   docker-compose down
110   ```
111 
112您可以通过环境变量或在 `.env` 文件中设置配置项：
113```bash
114# .env 文件示例
115PORT=3000
116YUQUE_API_TOKEN=your_token_here
117YUQUE_API_BASE_URL=https://www.yuque.com/api/v2
118```
119 
120#### 手动使用 Docker
121 
1221. 构建 Docker 镜像：
123   ```bash
124   docker build -t yuque-mcp-server .
125   ```
126 
1272. 运行容器：
128   ```bash
129   docker run -d -p 3000:3000 --name yuque-mcp-server yuque-mcp-server
130   ```
131 
1323. 使用环境变量：
133   ```bash
134   docker run -d -p 3000:3000 \
135     -e YUQUE_API_TOKEN=your_token_here \
136     -e YUQUE_API_BASE_URL=https://www.yuque.com/api/v2 \
137     --name yuque-mcp-server yuque-mcp-server
138   ```
139 
140### MCP 工具
141 
142语雀 MCP 服务器提供以下工具：
143 
144#### 用户和文档管理
145- `get_current_user` - 获取当前认证用户的信息，包括用户ID、用户名、头像等语雀账号基本信息
146- `get_user_docs` - 获取当前用户的所有知识库文档列表，包括私人和协作文档
147- `get_user_repos` - 获取指定用户的知识库列表，知识库是语雀中组织文档的集合
148- `get_repo_docs` - 获取特定知识库中的所有文档列表，包括文档标题、更新时间等信息
149- `get_doc` - 获取语雀中特定文档的详细内容，包括正文、修改历史和权限信息
150- `create_doc` - 在指定知识库中创建新的语雀文档，支持多种格式内容（Markdown、HTML、Lake）
151- `update_doc` - 更新语雀中已存在的文档，可以修改标题、内容或权限设置
152- `delete_doc` - 从语雀知识库中删除指定文档，此操作不可撤销
153- `search` - 在语雀平台中搜索文档或知识库内容，支持范围和作者筛选
154 
155#### 团队统计分析
156- `get_group_statistics` - 获取团队的汇总统计数据，包括成员人数、文档数量、阅读量和互动数据等
157- `get_group_member_statistics` - 获取团队成员的统计数据，包括各成员的编辑次数、阅读量、点赞量等
158- `get_group_book_statistics` - 获取团队知识库的统计数据，包括各知识库的文档数、字数、阅读量等
159- `get_group_doc_statistics` - 获取团队文档的统计数据，包括各文档的字数、阅读量、评论量等
160 
161## 与 AI 模型的集成
162 
163此 MCP 服务器可以与支持 Model-Context-Protocol 的 AI 模型一起使用，允许它们通过定义的工具与语雀交互。例如：
164 
1651. 启动 MCP 服务器
1662. 从兼容的客户端连接到服务器
1673. AI 模型现在可以使用注册的工具与语雀数据交互
168 
169### SSE 端点的查询参数
170 
171当连接到 SSE 端点时，你可以通过查询参数（query parameters）覆盖环境配置，这些参数的优先级高于环境变量：
172 
173- `accessToken`: 覆盖在 .env 文件中设置的语雀 API 令牌
174- `baseUrl`: 覆盖在 .env 文件中设置的语雀 API 基础 URL
175 
176示例：
177```
178http://localhost:3000/sse?accessToken=your_token_here&baseUrl=https://custom.yuque.api/v2
179```
180 
181这允许你在不修改 .env 文件的情况下动态配置服务，并且查询参数的优先级高于环境变量。这对于多用户环境或测试不同 API 端点特别有用。
182 
183每个 SSE 连接都可以使用不同的配置，这使得同一个服务器实例可以同时为不同的用户或环境提供服务。
184 
185## 开发
186 
187### 项目结构
188 
189```
190src/
191  ├── config.ts          # 服务器配置
192  ├── index.ts           # 主入口点
193  ├── cli.ts             # CLI 入口点 
194  ├── server.ts          # MCP 服务器实现
195  └── services/
196      └── yuque.ts       # 语雀 API 服务
197```
198 
199### 添加新工具
200 
201要添加新工具，请修改 `src/server.ts` 中的 `registerTools` 方法。
202 
203## API 改进
204 
205最近的更新增加了以下功能：
206 
2071. **团队统计数据**：添加了获取团队、成员、知识库和文档统计数据的功能，便于分析和监控团队知识库的使用情况。
208 
2092. **文档管理增强**：
210   - 支持多种文档格式（Markdown、HTML、Lake）
211   - 完善的文档公开性设置（私密、公开、企业内公开）
212   - 搜索功能支持更多参数和过滤条件
213 
2143. **数据类型完善**：更新了接口定义，使其与语雀 OpenAPI 规范保持一致。
215 
216## 许可证
217 
218MIT License
219 
220Copyright (c) 2025 Henryhaoson
221 
222Permission is hereby granted, free of charge, to any person obtaining a copy
223of this software and associated documentation files (the "Software"), to deal
224in the Software without restriction, including without limitation the rights
225to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
226copies of the Software, and to permit persons to whom the Software is
227furnished to do so, subject to the following conditions:
228 
229The above copyright notice and this permission notice shall be included in all
230copies or substantial portions of the Software.
231 
232THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
233IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
234FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
235AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
236LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
237OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
238SOFTWARE.
239 
240## 致谢
241 
242- [Figma-Context-MCP](https://github.com/GLips/Figma-Context-MCP) 提供 MCP 服务器实现参考
243- [语雀开放 API](https://app.swaggerhub.com/apis-docs/Jeff-Tian/yuque-open_api/2.0.1) 提供 API 文档
244- [Model Context Protocol](https://github.com/anthropics/model-context-protocol) 提供 MCP 规范
245