AI导哈

语雀文档管理服务器

一个用于构建自定义语雀MCP服务器的工具，支持文档的发现、读取、创建、更新和删除，以及知识库和群组管理。

  • by wwwwujl
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 wwwwujl/yuque-mcp

使用说明

尤克·麦克普

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

此文件夹是为Yuque构建自定义MCP服务器而准备的。

目标

构建Yuque MCP服务器，以便Codex可以：

  • 发现Yuque仓库和文档
  • 在markdown/raw模式下读取文档内容
  • 需要时创建/更新/删除文档
  • 从本地文件创建文档并从本地文件更新文档
  • 创建/更新/删除知识库
  • 创建/更新/删除组
  • 管理组成员(list/add/remove)
  • 联合作战(get_my_repositories, get_repository_overview, search_and_read, create_document_with_toc)
  • 更新存储库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. 脚手架节点+TypeScript MCP服务器。
  3. 实施只读工具。
  4. 添加用于组/仓库/文档CRUD+TOC更新的写入工具。
  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 （可选，逗号分隔的命名空间分配列表，用于repo/doc/toc写入）
  • YUQUE_WRITE_GROUP_ALLOWLIST （可选，逗号分隔的组登录分配列表用于组写入）
  • YUQUE_ALLOW_DELETE （可选，默认 false)
  • YUQUE_DELETE_NAMESPACE_ALLOWLIST （可选，逗号分隔的删除列表目标；repo/doc的命名空间，group的登录名）
  • 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.
  • TOC更新支持额外字段(editNode, url, open_window, visible).
  • 组成员工具： yuque_list_group_users, yuque_add_group_user, yuque_remove_group_user.
  • 基于文件的工具受根目录、扩展名允许列表和最大大小的限制。

在dev中运行：

npm run dev

运行已编译的服务器：

npm run start

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

YUQUE_SMOKE_NAMESPACE=your/test-namespace npm run smoke

运行带有清理功能的write-smoke套件（在测试命名空间上创建/更新/toc/删除）：

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

相关 MCP