Odel
Yuque MCP

Yuque MCP

Local
@wwwwujlTypeScriptMITUpdated 6mo ago

Yuque MCP server with safe read/write tools for groups, group members, repositories, docs, and TOC.

View on GitHub

yuque-mcp

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

This folder is prepared for building a custom MCP server for Yuque.

Goal

Build a Yuque MCP server so Codex can:

  • discover Yuque repos and docs
  • read doc content in markdown/raw mode
  • create/update/delete docs when needed
  • create docs from local files and update docs from local files
  • create/update/delete repos (knowledge bases)
  • create/update/delete groups
  • manage group members (list/add/remove)
  • run combined operations (get_my_repositories, get_repository_overview, search_and_read, create_document_with_toc)
  • update repository TOC nodes
  • use Yuque content as a research knowledge base

Included Docs

  • 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

Session Kickoff

In your new Codex session, start with:

  1. Read docs/01-scope-v1.md and docs/03-tool-contract.md.
  2. Scaffold Node + TypeScript MCP server.
  3. Implement read-only tools.
  4. Add write tools for group/repo/doc CRUD + TOC update.
  5. Run tests and add Codex MCP config.

Quick Start (Local)

npm install
npm run build

Required env:

  • YUQUE_TOKEN
  • YUQUE_ENDPOINT (optional, default https://www.yuque.com/api/v2/)
  • YUQUE_TIMEOUT_MS (optional, default 10000)
  • YUQUE_MAX_RETRIES (optional, default 2, read-only retries only)
  • YUQUE_ALLOW_WRITE (optional, default false)
  • YUQUE_WRITE_NAMESPACE_ALLOWLIST (optional, comma-separated namespace allowlist for repo/doc/toc writes)
  • YUQUE_WRITE_GROUP_ALLOWLIST (optional, comma-separated group login allowlist for group writes)
  • YUQUE_ALLOW_DELETE (optional, default false)
  • YUQUE_DELETE_NAMESPACE_ALLOWLIST (optional, comma-separated delete allowlist targets; namespace for repo/doc, login for group)
  • YUQUE_FILE_ROOT (optional, default current working directory, used by file-based doc tools)
  • YUQUE_FILE_MAX_BYTES (optional, default 1048576)
  • YUQUE_FILE_ALLOWED_EXTENSIONS (optional, default .md,.markdown,.txt)

Write safety:

  • All write tools are blocked by default.
  • Set YUQUE_ALLOW_WRITE=true to enable writes.
  • Optional write allowlists:
    • YUQUE_WRITE_NAMESPACE_ALLOWLIST=team/sandbox,team/test
    • YUQUE_WRITE_GROUP_ALLOWLIST=sandbox-team

Delete safety:

  • yuque_delete_doc, yuque_delete_repo, and yuque_delete_group are blocked by default.
  • To enable delete for test repos only, set:
    • YUQUE_ALLOW_WRITE=true
    • YUQUE_ALLOW_DELETE=true
    • YUQUE_DELETE_NAMESPACE_ALLOWLIST=your/test-namespace,your-test-group-login
  • Delete tools also require confirm: true and exact confirm_text:
    • doc: DELETE DOC <namespace>/<docRef>
    • repo: DELETE REPO <namespace>
    • group: DELETE GROUP <login>

Latest highlights:

  • yuque_get_doc / yuque_update_doc / yuque_delete_doc support either slug or doc_id.
  • yuque_list_docs supports pagination (offset, limit).
  • yuque_search_docs now scans paginated docs across the full repository.
  • Doc format supports markdown, html, lake; visibility supports 0 | 1 | 2.
  • TOC update supports extra fields (editNode, url, open_window, visible).
  • Group member tools: yuque_list_group_users, yuque_add_group_user, yuque_remove_group_user.
  • File-based tools are constrained by root directory, extension allowlist, and max size.

Run in dev:

npm run dev

Run compiled server:

npm run start

Run local MCP smoke test (test namespace only):

YUQUE_SMOKE_NAMESPACE=your/test-namespace npm run smoke

Run write smoke suite with cleanup (create/update/toc/delete on test namespace):

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

Suggested Stack

  • Node.js 20+
  • TypeScript
  • @modelcontextprotocol/sdk
  • Native fetch or lightweight HTTP client
  • zod for input validation

Open Source Governance

  • Contribution guide: CONTRIBUTING.md
  • Security policy: SECURITY.md
  • Weekly maintenance checklist: docs/11-weekly-maintenance.md
  • Complaint and takedown policy: docs/12-complaint-and-takedown.md
  • Disclaimer: DISCLAIMER.md