{
  "markdown": "# yuque-mcp\n\n中文说明: [README.zh-CN.md](./README.zh-CN.md)\n\nThis folder is prepared for building a custom MCP server for Yuque.\n\n## Goal\n\nBuild a Yuque MCP server so Codex can:\n- discover Yuque repos and docs\n- read doc content in markdown/raw mode\n- create/update/delete docs when needed\n- create docs from local files and update docs from local files\n- create/update/delete repos (knowledge bases)\n- create/update/delete groups\n- manage group members (`list/add/remove`)\n- run combined operations (`get_my_repositories`, `get_repository_overview`, `search_and_read`, `create_document_with_toc`)\n- update repository TOC nodes\n- use Yuque content as a research knowledge base\n\n## Included Docs\n\n- `docs/00-project-brief.md`\n- `docs/01-scope-v1.md`\n- `docs/02-architecture.md`\n- `docs/03-tool-contract.md`\n- `docs/04-api-mapping.md`\n- `docs/05-security.md`\n- `docs/06-implementation-plan.md`\n- `docs/07-test-plan.md`\n- `docs/08-codex-integration.md`\n- `docs/09-release-notes-zh.md`\n- `docs/10-registry-publish.md`\n- `docs/11-weekly-maintenance.md`\n- `docs/12-complaint-and-takedown.md`\n- `CHANGELOG.md`\n- `CONTRIBUTING.md`\n- `SECURITY.md`\n- `DISCLAIMER.md`\n- `tasks/TODO.md`\n\n## Session Kickoff\n\nIn your new Codex session, start with:\n1. Read `docs/01-scope-v1.md` and `docs/03-tool-contract.md`.\n2. Scaffold Node + TypeScript MCP server.\n3. Implement read-only tools.\n4. Add write tools for group/repo/doc CRUD + TOC update.\n5. Run tests and add Codex MCP config.\n\n## Quick Start (Local)\n\n```bash\nnpm install\nnpm run build\n```\n\nRequired env:\n\n- `YUQUE_TOKEN`\n- `YUQUE_ENDPOINT` (optional, default `https://www.yuque.com/api/v2/`)\n- `YUQUE_TIMEOUT_MS` (optional, default `10000`)\n- `YUQUE_MAX_RETRIES` (optional, default `2`, read-only retries only)\n- `YUQUE_ALLOW_WRITE` (optional, default `false`)\n- `YUQUE_WRITE_NAMESPACE_ALLOWLIST` (optional, comma-separated namespace allowlist for repo/doc/toc writes)\n- `YUQUE_WRITE_GROUP_ALLOWLIST` (optional, comma-separated group login allowlist for group writes)\n- `YUQUE_ALLOW_DELETE` (optional, default `false`)\n- `YUQUE_DELETE_NAMESPACE_ALLOWLIST` (optional, comma-separated delete allowlist targets; namespace for repo/doc, login for group)\n- `YUQUE_FILE_ROOT` (optional, default current working directory, used by file-based doc tools)\n- `YUQUE_FILE_MAX_BYTES` (optional, default `1048576`)\n- `YUQUE_FILE_ALLOWED_EXTENSIONS` (optional, default `.md,.markdown,.txt`)\n\nWrite safety:\n\n- All write tools are blocked by default.\n- Set `YUQUE_ALLOW_WRITE=true` to enable writes.\n- Optional write allowlists:\n  - `YUQUE_WRITE_NAMESPACE_ALLOWLIST=team/sandbox,team/test`\n  - `YUQUE_WRITE_GROUP_ALLOWLIST=sandbox-team`\n\nDelete safety:\n\n- `yuque_delete_doc`, `yuque_delete_repo`, and `yuque_delete_group` are blocked by default.\n- To enable delete for test repos only, set:\n  - `YUQUE_ALLOW_WRITE=true`\n  - `YUQUE_ALLOW_DELETE=true`\n  - `YUQUE_DELETE_NAMESPACE_ALLOWLIST=your/test-namespace,your-test-group-login`\n- Delete tools also require `confirm: true` and exact `confirm_text`:\n  - doc: `DELETE DOC <namespace>/<docRef>`\n  - repo: `DELETE REPO <namespace>`\n  - group: `DELETE GROUP <login>`\n\nLatest highlights:\n\n- `yuque_get_doc` / `yuque_update_doc` / `yuque_delete_doc` support either `slug` or `doc_id`.\n- `yuque_list_docs` supports pagination (`offset`, `limit`).\n- `yuque_search_docs` now scans paginated docs across the full repository.\n- Doc format supports `markdown`, `html`, `lake`; visibility supports `0 | 1 | 2`.\n- TOC update supports extra fields (`editNode`, `url`, `open_window`, `visible`).\n- Group member tools: `yuque_list_group_users`, `yuque_add_group_user`, `yuque_remove_group_user`.\n- File-based tools are constrained by root directory, extension allowlist, and max size.\n\nRun in dev:\n\n```bash\nnpm run dev\n```\n\nRun compiled server:\n\n```bash\nnpm run start\n```\n\nRun local MCP smoke test (test namespace only):\n\n```bash\nYUQUE_SMOKE_NAMESPACE=your/test-namespace npm run smoke\n```\n\nRun write smoke suite with cleanup (create/update/toc/delete on test namespace):\n\n```bash\nYUQUE_SMOKE_NAMESPACE=your/test-namespace \\\nYUQUE_SMOKE_ENABLE_WRITE=true \\\nYUQUE_ALLOW_WRITE=true \\\nYUQUE_ALLOW_DELETE=true \\\nYUQUE_DELETE_NAMESPACE_ALLOWLIST=your/test-namespace \\\nnpm run smoke\n```\n\n## Suggested Stack\n\n- Node.js 20+\n- TypeScript\n- `@modelcontextprotocol/sdk`\n- Native `fetch` or lightweight HTTP client\n- `zod` for input validation\n\n## Open Source Governance\n\n- Contribution guide: `CONTRIBUTING.md`\n- Security policy: `SECURITY.md`\n- Weekly maintenance checklist: `docs/11-weekly-maintenance.md`\n- Complaint and takedown policy: `docs/12-complaint-and-takedown.md`\n- Disclaimer: `DISCLAIMER.md`\n",
  "bytes": 4648,
  "sha": "9b2d0cc2f5a513dd06dd5c8bf59f9d4a37c16aac298f1ff05ab99784cb0af9bc",
  "repo_slug": "wwwwujl/yuque-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_wwwwujl_yuque_mcp_a994e462/readme"
}