# 语雀 MCP Server（本地版 · 双认证模式）

一个用 Python 编写的本地 MCP server，让 AI 客户端（ZCode）可以直接读写你的语雀文档。

## 认证方式（按优先级自动选择）

| 模式 | 环境变量 | 要求 | 接口 |
|------|---------|------|------|
| 官方 OpenAPI | `YUQUE_TOKEN` | **需超级会员** | `/api/v2/...` |
| 网页端 Cookie | `YUQUE_COOKIE` | **免费，任何用户可用** | `/api/...`（内部接口） |

## 它能做什么（6 个工具）

| 工具 | 功能 |
|------|------|
| `get_user` | 获取当前账号信息（验证凭证是否有效） |
| `list_repos` | 列出当前账号的知识库 |
| `list_docs` | 列出知识库里的文档 |
| `create_doc` | 创建文档（Markdown 正文） |
| `get_doc` | 获取文档内容 |
| `update_doc` | 更新文档标题/正文 |

## 一、免费方式：获取 Cookie（不需要超级会员）

1. 用 Chrome/Edge **登录**语雀网页版（https://www.yuque.com）
2. 按 **F12** 打开开发者工具 → 切到 **Network（网络）** 标签
3. **刷新页面**，点击任意一个请求
4. 在右侧 **Request Headers** 里找到 `Cookie:` 开头的整段内容（很长的一串）
5. **整段复制**（含 `_yuque_session=...` 和 `yuque_ctoken=...`）

> ⚠️ 一定包含 `yuque_ctoken`，它是写操作（创建/更新文档）要用的 CSRF 令牌。
> Cookie 有效期约 2 周，过期后在 Settings → MCP 里重新粘贴即可。

## 二、把凭证填进 ZCode

ZCode → **Settings → MCP** → 找到 `yuque` → 在环境变量里粘贴：
- `YUQUE_COOKIE`：粘贴上一步复制的整段 Cookie 值（免费路线，推荐）

> ⚠️ Cookie 等于你的登录态，别贴到聊天框、别提交进 git、别发给任何人。

## 三、重启 ZCode

配置修改后**重启 ZCode**（新会话自动连接），在 **Settings → MCP** 确认 `yuque` 已连接。
之后说一句「把 XXX 写成语雀文档」即可。

## 手动验证（可选）

```bash
pip install "mcp>=1.2.0,<2"   # mcp 2.x 移除了 FastMCP，必须锁 1.x
python test_client.py          # 协议自测：握手 → 列工具 → 两种认证模式链路
```

## 文件说明

- `server.py` — MCP server 本体（双认证模式，`@mcp.tool()` 注册工具，stdio 传输）
- `test_client.py` — 模拟 MCP 客户端的自测脚本（3 组用例）
- `requirements.txt` — 依赖（mcp 1.x）

## 踩坑记录（学习笔记）

1. **mcp 2.0.0 移除了 FastMCP**：`pip install mcp` 默认装 2.x 会报
   `ModuleNotFoundError: No module named 'mcp.server.fastmcp'`，必须锁 `mcp>=1.2,<2`。
2. **Windows 下 spawn 进程要用绝对路径**：`command` 填 `python.exe` 完整路径，别写 `python`。
3. **语雀 OpenAPI 令牌是超级会员专享**（2022 年后的策略）：免费用户改用网页端内部接口
   + cookie 认证。**实测可用的端点**（cookie 模式）：
   - `GET /api/mine`（用户）、`GET /api/mine/books`（知识库）、
     `GET /api/docs/{slug}?book_id=...&mode=markdown`（文档，正文在 `sourcecode` 字段）
   - **创建文档：`POST /api/docs`**（JSON 体：`book_id/title/format/body/body_draft/public`）
   - **更新文档：`PUT /api/docs/{id}/content` 再 `PUT /api/docs/{id}/publish`**（先写草稿后发布）
4. **cookie 模式写操作三要素**：`yuque_ctoken` 同时作为 cookie 和 `X-CSRF-Token` 请求头；
   请求头必须带 `X-Requested-With: XMLHttpRequest`；请求体是 **JSON**（不是表单），
   且要带 `Referer: https://www.yuque.com/{login}/{book_slug}`。
5. **网页端接口是非公开的**：语雀改版可能需要适配；这是社区方案（elog、
   yuque-cookie-plugin 等）都在用的路线。第一次写 404 很正常——先抓真实源码，
   别猜端点。