yuque-ai-mcp 2.7.4 → 2.7.5

package/README.md

@@ -0,0 +1,183 @@
+<p align="center">
+  <img src="https://cdn.nlark.com/yuque/0/2025/png/25689388/1749661212345-avatar/8a3b5c7d-1e2f-4a5b-9c7d-8e1f2a3b4c5d.png" width="120" alt="yuque-ai-mcp" />
+</p>
+
+<h1 align="center">yuque-ai-mcp</h1>
+<p align="center">
+  <b>61 fine-grained MCP tools for the full Yuque OpenAPI</b>
+</p>
+
+<p align="center">
+  <a href="https://github.com/yehuoshun/yuque-ai-mcp"><img src="https://img.shields.io/badge/version-2.7.4-blue" alt="version" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license" /></a>
+  <a href="https://github.com/yehuoshun/yuque-ai-skills"><img src="https://img.shields.io/badge/skills-61%20guides-orange" alt="skills" /></a>
+</p>
+
+<p align="center">
+  <a href="README_CN.md">中文文档</a>
+</p>
+
+---
+
+A full-featured Yuque (语雀) MCP Server built on the [Model Context Protocol](https://modelcontextprotocol.io/). Provides 61 fine-grained tools across 15 domains — every Yuque OpenAPI endpoint as a dedicated tool.
+
+## Why
+
+- **19 → 61 tools** — 3x more coverage than the official [yuque-mcp-server](https://github.com/yuque/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](https://github.com/yehuoshun/yuque-ai-skills)** — 61 usage guides for AI agents
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Tool Overview](#tool-overview)
+- [Architecture](#architecture)
+- [Configuration](#configuration)
+- [Error Handling](#error-handling)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Quick Start
+
+```bash
+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
+
+| Domain | Tools | Highlights |
+|--------|-------|------------|
+| **doc** | 14 | CRUD, versions, diff, batch get, import URL/file, cross-book copy, export |
+| **repo** | 8 | CRUD, batch get, cross-book copy, full export (TOC-structure + INDEX/GRAPH) |
+| **toc** | 3 | Get, update, batch update (createTitle/appendNode/removeNode/moveNode) |
+| **search** | 2 | General search + RAG-enhanced search |
+| **user** | 3 | User info, heartbeat, group list |
+| **group** | 3 | Member list, role change, delete member |
+| **statistic** | 4 | Group/member/repo/doc statistics |
+| **note** | 4 | CRUD + soft-delete/restore |
+| **recycle** | 3 | List, restore, destroy (Cookie auth) |
+| **upload** | 1 | File upload to Yuque CDN (Cookie auth) |
+| **board** | 3 | Mindmap, flowchart, architecture diagram |
+| **mine** | 2 | Book stacks, editor center (Cookie auth) |
+| **rss** | 3 | Source list, fetch + dedup + save, schedule analysis |
+| **crawler** | 4 | Fetch, CSS extract, dedup save, schedule analysis |
+| **kv** | 4 | Get, set, delete, list — incremental sharding, 250KB/doc limit |
+| **Total** | **61** | |
+
+See [SKILL.md](SKILL.md) or [yuque-ai-skills](https://github.com/yehuoshun/yuque-ai-skills) for full tool documentation.
+
+## vs Official
+
+| Feature | Official yuque-mcp-server | yuque-ai-mcp |
+|---------|--------------------------|--------------|
+| Tools | 19 | **61** |
+| Granularity | Coarse | **Fine-grained** (1 tool / endpoint) |
+| Group, Recycle, Upload, Statistics | ❌ | ✅ |
+| Versions, Diff, Cross-book Copy | ❌ | ✅ |
+| Transport | stdio only | **stdio + HTTP SSE** |
+| Config | Env var | **config.json** (token + cookie) |
+| Skill Layer | ❌ | ✅ 61 guides |
+
+## 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 (24h 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
+
+```json
+{
+  "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,
+    "namespaces": {
+      "cnblogs": {
+        "book_id": [80197497],
+        "kv_slugs": ["80197550/274164064"],
+        "schedule_slugs": []
+      }
+    }
+  },
+  "crawler": {
+    "enabled": true,
+    "namespaces": {
+      "cnblogs": {
+        "book_id": [80197497],
+        "kv_slugs": ["80197550/274164064"],
+        "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
+
+## 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](references/api/errors.md) for the full error code reference.
+
+## Contributing
+
+```bash
+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](https://github.com/yehuoshun/yuque-ai-mcp) and [yuque-ai-skills](https://github.com/yehuoshun/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

package/README_CN.md

@@ -0,0 +1,182 @@
+<p align="center">
+  <h1 align="center">yuque-ai-mcp</h1>
+  <p align="center">
+    <b>61 个细粒度 MCP 工具，覆盖语雀 OpenAPI 全部能力</b>
+  </p>
+</p>
+
+<p align="center">
+  <a href="https://github.com/yehuoshun/yuque-ai-mcp"><img src="https://img.shields.io/badge/版本-2.7.4-blue" alt="version" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/许可-MIT-green" alt="license" /></a>
+  <a href="https://github.com/yehuoshun/yuque-ai-skills"><img src="https://img.shields.io/badge/skills-61%20指导-orange" alt="skills" /></a>
+</p>
+
+<p align="center">
+  <a href="README.md">English</a>
+</p>
+
+---
+
+基于 [Model Context Protocol](https://modelcontextprotocol.io/) 的语雀全功能 MCP Server。61 个工具，15 个域——每个语雀 OpenAPI 端点一个专用工具。
+
+## 为什么选这个
+
+- **19 → 61 工具** — 比官方 [yuque-mcp-server](https://github.com/yuque/yuque-mcp-server) 多 3 倍覆盖
+- **双传输模式** — stdio + HTTP SSE，共享注册中心，修改无需重启
+- **模块化架构** — 15 个域，barrel export，唯一注册中心
+- **完整 API 覆盖** — 团队、回收站、上传、统计、版本、画板——补全官方缺失
+- **[Skill 层](https://github.com/yehuoshun/yuque-ai-skills)** — 61 个 AI Agent 使用指导
+
+## 目录
+
+- [快速开始](#快速开始)
+- [工具概览](#工具概览)
+- [与官方对比](#与官方对比)
+- [架构](#架构)
+- [配置](#配置)
+- [错误处理](#错误处理)
+- [贡献](#贡献)
+- [许可](#许可)
+
+## 快速开始
+
+```bash
+cd server
+npm install
+npm run build
+
+# 复制配置模板
+cp config/config.example.json config/config.json
+# 编辑 config.json 填入你的语雀 API Token
+
+# 运行
+npm start              # stdio 模式
+npm run dev:http       # HTTP SSE 模式 (http://localhost:3099)
+```
+
+> 开发时用 `npm run dev:http` 启动 `tsx` 热重载。
+
+## 工具概览
+
+| 域 | 工具数 | 亮点 |
+|--------|-------|------------|
+| **doc** | 14 | CRUD、版本管理、Diff、批量获取、URL/文件导入、跨库复制、导出 |
+| **repo** | 8 | CRUD、批量获取、跨库复制、全量导出（TOC 结构 + INDEX/GRAPH） |
+| **toc** | 3 | 获取、更新、批量更新（createTitle/appendNode/removeNode/moveNode） |
+| **search** | 2 | 通用搜索 + RAG 增强搜索 |
+| **user** | 3 | 用户信息、心跳、团队列表 |
+| **group** | 3 | 成员列表、角色变更、删除成员 |
+| **statistic** | 4 | 团队/成员/知识库/文档统计 |
+| **note** | 4 | CRUD + 软删除/恢复 |
+| **recycle** | 3 | 列表、恢复、彻底删除（Cookie 认证） |
+| **upload** | 1 | 文件上传到语雀 CDN（Cookie 认证） |
+| **board** | 3 | 思维导图、流程图、架构图 |
+| **mine** | 2 | 书架列表、编辑中心（Cookie 认证） |
+| **rss** | 3 | 数据源列表、抓取+去重+写入、定时策略分析 |
+| **crawler** | 4 | 抓取、CSS 提取、去重写入、定时策略分析 |
+| **kv** | 4 | 增删查列——增量分片，单文档 250KB 上限 |
+| **合计** | **61** | |
+
+完整工具文档见 [SKILL.md](SKILL.md) 或 [yuque-ai-skills](https://github.com/yehuoshun/yuque-ai-skills)。
+
+## 与官方对比
+
+| 功能 | 官方 yuque-mcp-server | yuque-ai-mcp |
+|---------|--------------------------|--------------|
+| 工具数 | 19 | **61** |
+| 粒度 | 粗粒度 | **细粒度**（1 端点 = 1 工具） |
+| 团队、回收站、上传、统计 | ❌ | ✅ |
+| 版本、Diff、跨库复制 | ❌ | ✅ |
+| 传输模式 | 仅 stdio | **stdio + HTTP SSE** |
+| 配置 | 环境变量 | **config.json**（token + cookie） |
+| Skill 层 | ❌ | ✅ 61 指导 |
+
+## 架构
+
+```
+server/src/
+├── common/              # 公共：config, errors, types, format, validate,
+│                        # api-client, web-request, register-tools, copy/export/schedule,
+│                        # repo-capacity（自动扩容）, toc-cache（24h TTL）, text-utils
+├── user/ search/ group/ doc/ toc/ repo/ statistic/
+├── note/ recycle/ upload/ board/ rss/ crawler/ mine/ kv/
+├── index.ts             # stdio 入口
+└── http.ts              # HTTP SSE 入口（端口 3099）
+```
+
+## 配置
+
+```json
+{
+  "token": "你的语雀 API Token",
+  "api_base": "https://www.yuque.com/api/v2",
+  "cookie": "可选，回收站/上传功能需要",
+  "ctoken": "可选，从 Cookie 中提取",
+  "kv": { "enabled": true },
+  "rss": {
+    "enabled": true,
+    "namespaces": {
+      "cnblogs": {
+        "book_id": [80197497],
+        "kv_slugs": ["80197550/274164064"],
+        "schedule_slugs": []
+      }
+    }
+  },
+  "crawler": {
+    "enabled": true,
+    "namespaces": {
+      "cnblogs": {
+        "book_id": [80197497],
+        "kv_slugs": ["80197550/274164064"],
+        "schedule_slugs": []
+      }
+    }
+  }
+}
+```
+
+- `book_id`：目标知识库 ID 数组，最后一个为当前活跃仓库。满 5000 篇自动扩容追加。
+- `kv_slugs`：KV 去重分片文档（`{book_id}/{doc_id}` 格式）
+- `schedule_slugs`：定时策略配置文档
+
+## 错误处理
+
+统一错误处理，返回结构化错误（HTTP 状态码 + 消息 + 响应摘要）。所有工具共用同一错误管道。
+
+关键错误：
+- `book_full` — 知识库超 5000 篇，自动创建新仓库并追加到 `book_id` 数组
+- `401` / `403` — Token/权限问题
+- `429` — 限流，自动重试
+
+完整错误码见 [references/api/errors.md](references/api/errors.md)。
+
+## 贡献
+
+```bash
+git clone https://github.com/yehuoshun/yuque-ai-mcp.git
+cd yuque-ai-mcp/server
+npm install
+npm run build
+
+# 新增工具清单：
+# 1. 创建 server/src/{域}/{工具}.ts
+# 2. 在 {域}/index.ts 中 export + 追加到工具数组
+# 3. npx tsc
+# 4. 重启 HTTP Server + curl health
+# 5. 同步 yuque-ai-skills
+# 6. 更新 README
+```
+
+[yuque-ai-mcp](https://github.com/yehuoshun/yuque-ai-mcp) 和 [yuque-ai-skills](https://github.com/yehuoshun/yuque-ai-skills) 保持同步更新。
+
+## 技术栈
+
+- TypeScript + Node.js
+- @modelcontextprotocol/sdk v1.x
+- Zod（参数校验）
+- 语雀 OpenAPI v2 / Web API
+
+## 许可
+
+MIT

package/SKILL.md

@@ -0,0 +1,180 @@
+# yuque-ai-mcp
+
+语雀全功能 MCP Server，61 个工具 / 15 个域。当用户提到「语雀」「yuque」「知识库」「文档」「团队」等关键词时触发。
+
+## 触发场景
+
+- 语雀知识库管理（创建、删除、列表、复制、导出）
+- 文档操作（读写、搜索、导入导出、版本对比）
+- 用户/团队信息查询
+- 回收站管理
+- 目录 TOC 导航
+- 画板（思维导图/流程图）
+- 统计数据
+- 小记
+- RSS 抓取
+- 网页爬虫
+- KV 存储
+
+## API 端点索引
+
+### user（3 工具）
+| 工具 | 说明 |
+|------|------|
+| `yuque_hello` | 心跳检测，验证 Token 有效性 |
+| `yuque_get_user` | 获取当前 Token 的用户详情 |
+| `yuque_get_user_groups` | 获取用户所属的团队列表 |
+
+### search（2 工具）
+| 工具 | 说明 |
+|------|------|
+| `yuque_search` | 通用搜索文档/知识库 |
+| `yuque_rag_search` | RAG 检索增强搜索 + 自动获取文档内容 |
+
+### group（3 工具）
+| 工具 | 说明 |
+|------|------|
+| `yuque_get_group_users` | 获取团队成员列表 |
+| `yuque_update_group_user` | 变更团队成员角色 |
+| `yuque_delete_group_user` | 删除团队成员 |
+
+### doc（14 工具）
+| 工具 | 说明 |
+|------|------|
+| `yuque_list_docs` | 获取知识库文档列表 |
+| `yuque_create_doc` | 创建文档 |
+| `yuque_get_doc` | 获取文档详情（支持 ID 或 slug） |
+| `yuque_update_doc` | 更新文档 |
+| `yuque_delete_doc` | 删除文档 |
+| `yuque_batch_get_docs` | 批量获取文档详情（max 20） |
+| `yuque_get_doc_versions` | 获取文档历史版本列表 |
+| `yuque_get_doc_version_detail` | 获取文档历史版本详情 |
+| `yuque_diff_doc_versions` | 对比两个版本的行级差异 |
+| `yuque_copy_doc` | 单文档跨库复制 |
+| `yuque_export_doc` | 导出单篇文档为 Markdown（含图片下载） |
+| `yuque_import_url` | 从网页 URL 导入文档 |
+| `yuque_import_file` | 从本地文件导入文档（direct/upload_assets/embed_assets） |
+| `yuque_embed_url` | 生成文档嵌入阅读器 URL |
+
+### toc（3 工具）
+| 工具 | 说明 |
+|------|------|
+| `yuque_get_toc` | 获取知识库目录 |
+| `yuque_update_toc` | 更新知识库目录 |
+| `yuque_batch_update_toc` | 批量更新目录（Agent 出计划，Tool 执行） |
+
+### repo（8 工具）
+| 工具 | 说明 |
+|------|------|
+| `yuque_list_repos` | 获取知识库列表（用户/团队） |
+| `yuque_create_repo` | 创建知识库 |
+| `yuque_get_repo` | 获取知识库详情 |
+| `yuque_update_repo` | 更新知识库 |
+| `yuque_delete_repo` | 删除知识库 |
+| `yuque_batch_get_repos` | 批量获取知识库详情（max 20） |
+| `yuque_copy_repo` | 批量跨库复制（LLM 分类 + 目录重建） |
+| `yuque_export_repo` | 批量导出知识库为 Markdown（按 TOC 目录结构） |
+
+### statistic（4 工具）
+| 工具 | 说明 |
+|------|------|
+| `yuque_get_group_statistics` | 获取团队汇总统计数据 |
+| `yuque_get_member_statistics` | 获取团队成员统计数据 |
+| `yuque_get_book_statistics` | 获取团队知识库统计数据 |
+| `yuque_get_doc_statistics` | 获取团队文档统计数据 |
+
+### note（4 工具）
+| 工具 | 说明 |
+|------|------|
+| `yuque_list_notes` | 获取小记列表 |
+| `yuque_get_note` | 获取小记详情 |
+| `yuque_create_note` | 创建小记 |
+| `yuque_update_note` | 更新小记 |
+
+### recycle（3 工具）
+| 工具 | 说明 |
+|------|------|
+| `yuque_list_recycles` | 列出回收站项目 |
+| `yuque_restore_recycle` | 恢复回收站项目 |
+| `yuque_destroy_recycle` | 彻底删除回收站项目 |
+
+### upload（1 工具）
+| 工具 | 说明 |
+|------|------|
+| `yuque_upload_attachment` | 上传文件到语雀 CDN |
+
+### board（3 工具）
+| 工具 | 说明 |
+|------|------|
+| `yuque_get_board` | 获取文档中的画板资源 |
+| `yuque_create_board` | 在文档中创建画板资源 |
+| `yuque_update_board` | 更新文档中的画板资源 |
+
+### rss（3 工具）
+| 工具 | 说明 |
+|------|------|
+| `yuque_rss_list_sources` | 列出所有可用 RSS 数据源及 feed 类型 |
+| `yuque_rss_fetch` | 抓取 RSS/Atom Feed，解析后去重写入语雀 |
+| `yuque_rss_schedule` | 分析更新频率，生成推荐抓取时间并写入配置 |
+
+### crawler（4 工具）
+| 工具 | 说明 |
+|------|------|
+| `yuque_crawl_fetch` | 抓取网页原始 HTML |
+| `yuque_crawl_extract` | CSS 选择器从 HTML 提取内容 |
+| `yuque_crawl_save` | 去重 + 写入语雀（接收 Agent 清洗后的内容） |
+| `yuque_crawl_schedule` | 分析爬虫抓取频率，生成推荐抓取时间 |
+
+> **清洗规范**：Agent 负责 fetch → 提取正文 → HTML→Markdown → 传干净 body 给 `crawl_save`。详见 `references/api/crawler_api.md`。
+
+### mine（2 工具）
+| 工具 | 说明 |
+|------|------|
+| `yuque_get_book_stacks` | 获取知识库分组（书架）列表 |
+| `yuque_get_editor_center` | 获取个人编辑中心全景数据 |
+
+### kv（4 工具）
+| 工具 | 说明 |
+|------|------|
+| `yuque_kv_get` | 读取 KV 命名空间的完整 JSON map（分片合并） |
+| `yuque_kv_set` | 增量设置 key-value，超 250KB 自动分片 |
+| `yuque_kv_delete` | 遍历分片查找并删除 key |
+| `yuque_kv_list` | 列出已配置的 KV 命名空间 |
+
+## 错误码
+
+所有工具共用统一错误处理。API 失败时返回结构化错误信息（含状态码、中文描述、响应摘要）。
+
+完整错误码及处理策略见 `references/api/errors.md`。
+
+## 配置
+
+```json
+{
+  "token": "语雀 API Token",
+  "api_base": "https://www.yuque.com/api/v2",
+  "cookie": "可选，回收站/上传/mine 功能需要",
+  "ctoken": "可选，从 Cookie 中提取",
+  "kv": { "enabled": true },
+  "rss": {
+    "enabled": true,
+    "namespaces": {
+      "cnblogs": {
+        "book_id": 80197497,
+        "kv_slugs": ["80197550/274164064"],
+        "schedule_slugs": ["80278170/274357940"]
+      }
+    }
+  },
+  "crawler": {
+    "enabled": true,
+    "namespaces": {
+      "cnblogs": {
+        "book_id": 80197497,
+        "kv_slugs": ["80197550/274164064"],
+        "schedule_slugs": ["80278170/274358465"]
+      }
+    }
+  }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuque-ai-mcp",
-  "version": "2.7.4",
+  "version": "2.7.5",
   "description": "Full-featured Yuque MCP Server — 61 fine-grained tools covering the entire Yuque OpenAPI",
   "type": "module",
   "main": "dist/index.js",
@@ -31,7 +31,7 @@
     "dev:http": "tsx watch src/http.ts",
     "start": "node dist/index.js",
     "start:http": "node dist/http.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && cp ../README.md ../README_CN.md ../SKILL.md . 2>/dev/null; true"
   },
   "repository": {
     "type": "git",