Yuque MCP

yuque-mcp

中文说明：README.zh-CN.md

此文件夹用于构建自定义 Yuque MCP 服务。

目标

构建 Yuque MCP 服务，以便 Codex 能够：

• 发现 Yuque 知识库和文档
• 以 Markdown／原始模式读取文档内容
• 按需创建／更新／删除文档
• 从本地文件创建文档，并根据本地文件更新文档
• 创建／更新／删除知识库
• 创建／更新／删除分组
• 管理分组成员（list/add/remove）
• 执行组合操作（get_my_repositories、get_repository_overview、search_and_read、create_document_with_toc）
• 更新知识库目录节点
• 将 Yuque 内容用作研究知识库

包含的文档

• docs/00-project-brief.md
• docs/01-scope-v1.md
• docs/02-architecture.md
• docs/03-tool-contract.md
• docs/04-api-mapping.md
• docs/05-security.md
• docs/06-implementation-plan.md
• docs/07-test-plan.md
• docs/08-codex-integration.md
• docs/09-release-notes-zh.md
• docs/10-registry-publish.md
• docs/11-weekly-maintenance.md
• docs/12-complaint-and-takedown.md
• CHANGELOG.md
• CONTRIBUTING.md
• SECURITY.md
• DISCLAIMER.md
• tasks/TODO.md

会话启动

在新的 Codex 会话中，从以下步骤开始：

1. 阅读 docs/01-scope-v1.md 和 docs/03-tool-contract.md。
2. 搭建 Node + TypeScript MCP 服务框架。
3. 实现只读工具。
4. 添加用于分组／知识库／文档 CRUD 和目录更新的写入工具。
5. 运行测试并添加 Codex MCP 配置。

快速开始（本地）

npm install
npm run build

必需的环境变量：

• YUQUE_TOKEN
• YUQUE_ENDPOINT（可选，默认值为 https://www.yuque.com/api/v2/）
• YUQUE_TIMEOUT_MS（可选，默认值为 10000）
• YUQUE_MAX_RETRIES（可选，默认值为 2，仅对只读操作重试）
• YUQUE_ALLOW_WRITE（可选，默认值为 false）
• YUQUE_WRITE_NAMESPACE_ALLOWLIST（可选，以逗号分隔的知识库／文档／目录写入命名空间允许列表）
• YUQUE_WRITE_GROUP_ALLOWLIST（可选，以逗号分隔的分组写入登录名允许列表）
• YUQUE_ALLOW_DELETE（可选，默认值为 false）
• YUQUE_DELETE_NAMESPACE_ALLOWLIST（可选，以逗号分隔的删除目标允许列表；知识库／文档使用命名空间，分组使用登录名）
• YUQUE_FILE_ROOT（可选，默认值为当前工作目录，供基于文件的文档工具使用）
• YUQUE_FILE_MAX_BYTES（可选，默认值为 1048576）
• YUQUE_FILE_ALLOWED_EXTENSIONS（可选，默认值为 .md,.markdown,.txt）

写入安全：

• 默认情况下，所有写入工具均被禁用。
• 设置 YUQUE_ALLOW_WRITE=true 以启用写入。
• 可选的写入允许列表：
  • YUQUE_WRITE_NAMESPACE_ALLOWLIST=team/sandbox,team/test
  • YUQUE_WRITE_GROUP_ALLOWLIST=sandbox-team

删除安全：

• 默认情况下，yuque_delete_doc、yuque_delete_repo 和 yuque_delete_group 均被禁用。
• 若要仅对测试知识库启用删除，请设置：
  • YUQUE_ALLOW_WRITE=true
  • YUQUE_ALLOW_DELETE=true
  • YUQUE_DELETE_NAMESPACE_ALLOWLIST=your/test-namespace,your-test-group-login
• 删除工具还要求设置 confirm: true，并提供完全匹配的 confirm_text：
  • 文档：DELETE DOC <namespace>/<docRef>
  • 知识库：DELETE REPO <namespace>
  • 分组：DELETE GROUP <login>

最新亮点：

• yuque_get_doc／yuque_update_doc／yuque_delete_doc 支持使用 slug 或 doc_id。
• yuque_list_docs 支持分页（offset、limit）。
• yuque_search_docs 现在会扫描整个知识库中的分页文档。
• 文档格式支持 markdown、html、lake；可见性支持 0 | 1 | 2。
• 目录更新支持额外字段（editNode、url、open_window、visible）。
• 分组成员工具：yuque_list_group_users、yuque_add_group_user、yuque_remove_group_user。
• 基于文件的工具受根目录、扩展名允许列表和最大文件大小的限制。

在开发模式下运行：

npm run dev

运行已编译的服务：

npm run start

运行本地 MCP 冒烟测试（仅限测试命名空间）：

YUQUE_SMOKE_NAMESPACE=your/test-namespace npm run smoke

运行带清理的写入冒烟测试套件（在测试命名空间中执行创建／更新／目录更新／删除）：

YUQUE_SMOKE_NAMESPACE=your/test-namespace \
YUQUE_SMOKE_ENABLE_WRITE=true \
YUQUE_ALLOW_WRITE=true \
YUQUE_ALLOW_DELETE=true \
YUQUE_DELETE_NAMESPACE_ALLOWLIST=your/test-namespace \
npm run smoke

建议的技术栈

• Node.js 20+
• TypeScript
• @modelcontextprotocol/sdk
• 原生 fetch 或轻量级 HTTP 客户端
• 使用 zod 进行输入验证

开源治理

• 贡献指南：CONTRIBUTING.md
• 安全政策：SECURITY.md
• 每周维护清单：docs/11-weekly-maintenance.md
• 投诉和下架政策：docs/12-complaint-and-takedown.md
• 免责声明：DISCLAIMER.md