# yuque-mcp

语雀 MCP 服务 - 基于语雀 OpenAPI 的 Model Context Protocol 服务，让 AI Agent（如 Qoder、Claude Desktop、Cursor 等）能够安全地访问和操作语雀知识库。

> **本服务是给 AI Agent 使用的 MCP 工具服务**，不是手动运行的程序。安装后，AI Agent 会根据 MCP 配置自动启动本服务，通过 stdin/stdout 与之通信。你不需要手动运行它。

## 工作原理

```
AI Agent (Qoder / Claude Desktop / Cursor ...)
   │
   │  读取 MCP 配置，自动启动: yuque-mcp --permission read
   │  设置环境变量: YUQUE_TOKEN=xxx
   │
   ▼ 通过 stdin/stdout (JSON-RPC) 通信
yuque-mcp 进程
   │
   │  调用语雀 API
   ▼
语雀 API (https://www.yuque.com)
```

## 特性

- 基于语雀 OpenAPI 2.0.1 规范实现
- **三级权限控制**，默认只读，防止 AI 误操作
- 支持 stdio 传输模式，兼容主流 MCP 客户端
- 支持 Docker 部署

## 权限级别

| 级别 | 说明 | 可用操作 | 工具数 |
|------|------|---------|--------|
| `read` (默认) | 只读 | GET 请求 | 14 |
| `write` | 读写 | GET + POST/PUT/PATCH | 22 |
| `admin` | 管理 | 所有操作包括 DELETE | 25 |

## 快速开始

两种方式任选其一，**都只需操作一次**，之后 Agent 每次调用时自动拉起服务，无需手动启动。

### 方式一：本地安装（推荐，简单）

```bash
# 在项目目录下安装
pip install -e .

# 验证安装成功
yuque-mcp --version
```

安装后 `yuque-mcp` 命令注册到 PATH 中，Agent 自动找到并调用。

### 方式二：Docker（适合不想装 Python 的用户）

```bash
# 构建镜像（只需一次，镜像会留在本机）
docker build -t yuque-mcp .
```

构建后镜像 `yuque-mcp:latest` 永久存在本地。只有修改源码才需重新构建。

### 配置 MCP 客户端

在 AI Agent 的 MCP 配置中添加语雀服务，填入你的 Token 和权限级别即可。

> 你不需要手动运行服务，Agent 会根据配置自动启动它。

#### 本地安装方式

所有 MCP 客户端（Claude Desktop、Cursor、Qoder 等）配置相同：

```json
{
  "mcpServers": {
    "yuque": {
      "command": "yuque-mcp",
      "args": ["--permission", "read"],
      "env": {
        "YUQUE_TOKEN": "your_yuque_token_here",
        "YUQUE_BASE_URL": "https://www.yuque.com"
      }
    }
  }
}
```

#### Docker 方式

```json
{
  "mcpServers": {
    "yuque": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "YUQUE_TOKEN", "-e", "YUQUE_BASE_URL", "yuque-mcp"],
      "env": {
        "YUQUE_TOKEN": "your_yuque_token_here",
        "YUQUE_BASE_URL": "https://www.yuque.com"
      }
    }
  }
}
```

> `-i` 保持 stdin 开放用于 MCP 通信，`--rm` 用完后自动清理容器。读写模式在 args 末尾加 `"--permission", "write"` 即可。

> 如果你的语雀团队使用了私有域名（如 `jojoread.yuque.com`），将 `YUQUE_BASE_URL` 改为对应的地址即可。

## 可用工具

### 只读工具（所有权限级别）

| 工具名 | 说明 |
|--------|------|
| `yuque_hello` | 心跳检测 |
| `yuque_get_user_info` | 获取当前用户详情 |
| `yuque_get_user_groups` | 获取用户团队列表 |
| `yuque_get_user_repos` | 获取用户知识库列表 |
| `yuque_get_group_repos` | 获取团队知识库列表 |
| `yuque_get_repo` | 获取知识库详情 |
| `yuque_get_docs` | 获取文档列表 |
| `yuque_get_doc` | 获取文档详情 |
| `yuque_get_doc_by_book_id` | 通过知识库 ID 获取文档 |
| `yuque_get_toc` | 获取知识库目录 |
| `yuque_get_toc_by_book_id` | 通过知识库 ID 获取目录 |
| `yuque_get_doc_versions` | 获取文档历史版本列表 |
| `yuque_get_doc_version` | 获取文档历史版本详情 |
| `yuque_search` | 通用搜索 |

### 写入工具（write/admin 权限）

| 工具名 | 说明 |
|--------|------|
| `yuque_create_repo` | 创建知识库 |
| `yuque_update_repo` | 更新知识库 |
| `yuque_create_doc` | 创建文档 |
| `yuque_update_doc` | 更新文档 |
| `yuque_create_doc_by_book_id` | 通过知识库 ID 创建文档 |
| `yuque_update_doc_by_book_id` | 通过知识库 ID 更新文档 |
| `yuque_update_toc` | 更新知识库目录 |
| `yuque_update_toc_by_book_id` | 通过知识库 ID 更新目录 |

### 删除工具（仅 admin 权限）

| 工具名 | 说明 |
|--------|------|
| `yuque_delete_repo` | 删除知识库 |
| `yuque_delete_doc` | 删除文档 |
| `yuque_delete_doc_by_book_id` | 通过知识库 ID 删除文档 |

## 环境变量

在 MCP 客户端配置的 `env` 字段中设置：

| 变量名 | 必需 | 默认值 | 说明 |
|--------|------|--------|------|
| `YUQUE_TOKEN` | 是 | - | 语雀 API Token |
| `YUQUE_PERMISSION_LEVEL` | 否 | `read` | 权限级别（read/write/admin） |
| `YUQUE_BASE_URL` | 否 | `https://www.yuque.com` | 语雀 API 地址，私有域名时需修改 |
| `YUQUE_MCP_DEBUG` | 否 | - | 设为 `1` 开启 DEBUG 日志 |

## 获取语雀 Token

1. 登录 [语雀](https://www.yuque.com)
2. 进入 **个人设置** → **Token**
3. 创建一个新的 Token

## 调试

服务运行时日志输出到 stderr（MCP 协议使用 stdout），包含配置加载、API 请求/响应等信息。

### 开启 DEBUG 日志

在 MCP 客户端配置中添加 `YUQUE_MCP_DEBUG` 环境变量：

```json
{
  "mcpServers": {
    "yuque": {
      "command": "yuque-mcp",
      "args": ["--permission", "read"],
      "env": {
        "YUQUE_TOKEN": "your_yuque_token_here",
        "YUQUE_BASE_URL": "https://www.yuque.com",
        "YUQUE_MCP_DEBUG": "1"
      }
    }
  }
}
```

### 日志示例

```
2026-06-10 15:28:33 [INFO] yuque_mcp: 配置初始化: base_url=https://www.yuque.com, token=qTGP3rqp..., permission=read, kwargs=[]
2026-06-10 15:28:33 [INFO] yuque_mcp: 创建 HTTP 客户端: base_url=https://www.yuque.com, token=qTGP3rqp...
2026-06-10 15:28:33 [INFO] yuque_mcp: API 请求: GET /api/v2/hello
2026-06-10 15:28:33 [INFO] yuque_mcp: API 响应: GET /api/v2/hello -> 200
```

### 常见问题

**401 Unauthorized**

如果日志显示 `Token: (空)`，说明 `YUQUE_TOKEN` 环境变量未正确传入：
- 确认 Token 写在 MCP 客户端配置的 `env` 字段中
- 确认环境变量名是 `YUQUE_TOKEN`（不是 `YUQUE_YUQUE_TOKEN`）
- 重启 MCP 客户端使配置生效

**私有域名访问**

如果你的语雀使用私有域名（如 `xxx.yuque.com`），需要设置 `YUQUE_BASE_URL`：
```json
"YUQUE_BASE_URL": "https://xxx.yuque.com"
```

## 开发

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 代码检查
ruff check src/

# 格式化
ruff format src/
```

## License

Apache-2.0