# Yuque MCP Server

语雀（Yuque）文档 Model Context Protocol (MCP) 服务器，提供文档搜索、目录浏览、内容获取和文档创建功能。

## 功能

- **search**: 搜索语雀文档
- **get_doc**: 获取文档详细内容
- **get_toc**: 获取知识库目录结构
- **create_doc**: 创建新文档
- **update_doc**: 更新现有文档

## 安装

```bash
npm install
```

## 构建

```bash
git clone https://github.com/wangx-wx/yuque-mcp.git
cd yuque-mcp
npm install
npm run build
```

## MCP 配置

在 Claude Desktop 配置文件中添加：

### macOS
`~/Library/Application Support/Claude/claude_desktop_config.json`

### Windows
`%APPDATA%\Claude\claude_desktop_config.json`

配置内容：

```json
{
  "mcpServers": {
    "yuque": {
      "command": "node",
      "args": ["E:\\node\\yuque-mcp\\dist\\index.js"],
      "env": {
        "YUQUE_AUTH_TOKEN": "your-auth-token-here",
        "YUQUE_BASE_URL": "https://www.yuque.com",
        "YUQUE_GROUP_LOGIN": "your-group-login",
        "YUQUE_BOOK_SLUG": "your-book-slug"
      }
    }
  }
}
```


### CLI 配置
```sh
claude mcp add yuque-mcp-asd \
		--scope project \
		--transport stdio \
		-- node "/path/yuque-mcp/dist/index.js" \
		--env YUQUE_AUTH_TOKEN=your-auth-token-here \
		--env YUQUE_BASE_URL=https://www.leyaoyao.yuque.com \
		--env YUQUE_GROUP_LOGIN=your-group-login \
		--env YUQUE_BOOK_SLUG=your-book-slug
```

```powershell
claude mcp add yuque-mcp-asd `
		--scope project `
		--transport stdio `
		-- node "D:/yuque-mcp/dist/index.js" `
		--env YUQUE_AUTH_TOKEN=your-auth-token-here `
		--env YUQUE_BASE_URL=https://www.leyaoyao.yuque.com `
		--env YUQUE_GROUP_LOGIN=your-group-login `
		--env YUQUE_BOOK_SLUG=your-book-slug
```
## 工具说明

### search

搜索语雀文档。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| q | string | 是 | 搜索关键词 |

**使用场景：** 用户想查找特定内容的文档

**示例：**
```
搜索关键词 "TypeScript" 的文档
```

### get_toc

获取知识库目录结构。

**参数：** 无（从环境变量读取知识库配置）

**使用场景：** 用户想浏览目录或导航文件夹结构

**返回：** 扁平化的目录项列表，包含 uuid 和 title

**示例：**
```
查看知识库的目录结构
```

### get_doc

获取指定文档的详细内容。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| doc_id | number | 是 | 文档 ID |

**使用场景：** 已有文档 ID，需要读取完整文档内容

**示例：**
```
获取文档 123456 的详细内容
```

### create_doc

创建新文档并添加到目录结构中。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | string | 是 | 文档标题 |
| content | string | 是 | 文档内容（Markdown 格式） |
| target_uuid | string | 否 | 目标节点 UUID（通过 get_toc 获取）。不填则添加到根节点 |
| action_mode | string | 否 | 插入模式：`child`（子级，默认）或 `sibling`（同级） |

**使用场景：** 用户想创建新文档

**返回：** 文档 ID、标题和访问 URL

**示例：**
```
创建标题为 "部署指南" 的文档，内容为 "# 部署\n\n..."
```

### update_doc

更新现有文档的标题、内容或路径。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| doc_id | string | 是 | 文档 ID 或路径 |
| title | string | 否 | 新文档标题 |
| content | string | 否 | 文档内容（Markdown 格式）|
| slug | string | 否 | 新文档路径 |

**使用场景：** 修改已有文档的内容或标题

**返回：** 文档 ID、标题、路径、访问 URL 和更新时间

**示例：**
```
更新文档 abc123，将标题改为 "新标题"，内容改为 "# 新内容"
```

## 项目结构

```
yuque-mcp/
├── src/
│   ├── config/
│   │   └── env.ts          # 环境变量配置
│   ├── models/
│   │   ├── types.ts        # TypeScript 类型定义
│   │   └── responses.ts    # 响应转换器
│   ├── api/
│   │   ├── client.ts       # HTTP 客户端
│   │   └── yuque-api.ts    # 语雀 API 封装
│   ├── tools/
│   │   ├── search.ts       # search 工具实现
│   │   ├── get-doc.ts      # get_doc 工具实现
│   │   ├── get-toc.ts      # get_toc 工具实现
│   │   ├── create-doc.ts   # create_doc 工具实现
│   │   └── update-doc.ts   # update_doc 工具实现
│   ├── server.ts           # MCP 服务器配置
│   └── index.ts            # 入口文件
├── package.json
├── tsconfig.json
└── README.md
```

## 使用示例

### 搜索文档

```
帮我搜索关于 "TypeScript" 的语雀文档
```

### 浏览目录

```
查看知识库的目录结构
```


### 创建文档

```
创建一个新文档，标题是 "部署指南"，内容如下：
# 部署指南

## 环境准备
- Node.js 18+
- MySQL 8.0

## 部署步骤
...
```

### 更新文档

```
更新文档 123456，标题改为 "部署指南 v2"，内容添加 "## 更新日志\n\n- 2024-01-01: 初始版本"
```

### 组合使用

```
先查看目录，找到 "技术文档" 分类的 uuid，然后在该分类下创建一个新文档
```

## 许可证

MIT

## 参考文档

- [语雀 API 文档](https://www.yuque.com/yuque/developer/api)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)