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

Related MCP server: Yuque MCP Server

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