yuque-ai-mcp

62 fine-grained MCP tools for the full Yuque OpenAPI

中文文档

A full-featured Yuque (语雀) MCP Server built on the Model Context Protocol. Provides 62 fine-grained tools across 15 domains — every Yuque OpenAPI endpoint as a dedicated tool.

Why

• 19 → 62 tools — 3x more coverage than the official yuque-mcp-server
• Dual transport — stdio + HTTP SSE, shared registry, zero downtime on reload
• Modular architecture — 15 domains, barrel exports, single source of truth registry
• Full API coverage — group, recycle, upload, statistics, versions, boards — all the missing pieces
• Skill layer — 62 usage guides for AI agents

Table of Contents

• Quick Start
• Tool Overview
• Architecture
• Configuration
• Error Handling
• Contributing
• License

Quick Start

cd server
npm install
npm run build

# Copy config template
cp config/config.example.json config/config.json
# Edit config.json with your Yuque API token

# Run
npm start              # stdio mode
npm run dev:http       # HTTP SSE mode (http://localhost:3099)

Note: npm run dev:http uses tsx for hot-reload during development.

Tool Overview

All 62 Tools

See SKILL.md or yuque-ai-skills for full tool documentation with parameters and examples.

vs Official

Architecture

server/src/
├── common/              # Shared: config, errors, types, format, validate,
│                        # api-client, web-request, register-tools, copy/export/schedule common,
│                        # repo-capacity (auto-expand), toc-cache (configurable TTL), text-utils
├── user/ search/ group/ doc/ toc/ repo/ statistic/
├── note/ recycle/ upload/ board/ rss/ crawler/ mine/ kv/
├── index.ts             # stdio entry
└── http.ts              # HTTP SSE entry (port 3099)

Configuration

{
  "token": "Your Yuque API Token",
  "api_base": "https://www.yuque.com/api/v2",
  "cookie": "Optional, for recycle/upload features",
  "ctoken": "Optional, extracted from Cookie",
  "kv": { "enabled": true },
  "rss": {
    "enabled": true,
    "sources": {
      "cnblogs": {
        "name": "博客园",
        "slug_pattern": "/p/(\\d+)",
        "feeds": {
          "sitehome": { "label": "首页", "url": "https://feed.cnblogs.com/blog/sitehome/rss" }
        }
      }
    },
    "namespaces": {
      "cnblogs": {
        "book_id": [0],
        "kv_slugs": [],
        "schedule_slugs": []
      }
    }
  },
  "crawler": {
    "enabled": true,
    "namespaces": {
      "my-source": {
        "book_id": [0],
        "kv_slugs": [],
        "schedule_slugs": []
      }
    }
  }
}

• book_id: Target repo ID array — last element is the active repo. Auto-expands when full (5000 docs).
• kv_slugs: KV dedup shard docs ({book_id}/{doc_id} format)
• schedule_slugs: Schedule config docs
• toc_cache_ttl_minutes: TOC cache TTL in minutes (default 60). Set higher to reduce API calls, lower for fresher data.

Error Handling

Unified error handling with structured responses (HTTP status + message + response summary). All tools share the same error pipeline.

Key errors:

• book_full — Auto-expands by creating a new repo and appending to the book_id array
• 401 / 403 — Token/permission issues
• 429 — Rate limit with automatic retry

See references/api/errors.md for the full error code reference.

Contributing

git clone https://github.com/yehuoshun/yuque-ai-mcp.git
cd yuque-ai-mcp/server
npm install
npm run build

# New tool checklist:
# 1. Create server/src/{domain}/{tool}.ts
# 2. Export in {domain}/index.ts + append to tools array
# 3. npx tsc
# 4. Restart HTTP server + curl health
# 5. Sync yuque-ai-skills
# 6. Update README

Both yuque-ai-mcp and yuque-ai-skills are kept in sync.

Tech Stack

• TypeScript + Node.js
• @modelcontextprotocol/sdk v1.x
• Zod (validation)
• Yuque OpenAPI v2 / Web API

License

MIT