使用说明

项目简介

本项目是一个 MCP (Model Context Protocol) 服务器，旨在为 AI 模型提供与语雀知识库平台进行交互的能力。通过此服务器，AI 模型可以安全、可控地访问和操作语雀中的知识库、文档和用户信息，从而实现更智能的知识管理和应用集成。

主要功能点

用户与文档管理:
- 获取当前用户信息
- 获取用户知识库和文档列表
- 获取、创建、更新、删除语雀文档
- 在语雀中进行内容搜索
团队统计分析:
- 获取团队、成员、知识库和文档的统计数据，用于分析和监控团队知识库使用情况
文档内容分块:
- 支持将长文档分割成多个块，方便 AI 模型处理和理解大型文档内容
灵活的部署方式:
- 支持 HTTP 和 CLI (stdio) 两种服务器模式
- 提供 Docker 部署方案，方便容器化部署
SSE 协议支持:
- 通过 SSE (Server-Sent Events) 协议与 MCP 客户端通信，实现实时数据推送

安装步骤

前提条件:
- 确保已安装 Node.js 18 或更高版本。
- 拥有语雀账号并获取 API 令牌 (Token)。

克隆仓库:

git clone https://github.com/HenryHaoson/Yuque-MCP-Server.git
cd Yuque-MCP-Server

安装依赖:
```
npm install
```
配置环境变量:
- 复制 '.env.example' 文件并重命名为 '.env'。
- 打开 '.env' 文件，根据需要配置以下环境变量：
  - 'YUQUE_API_TOKEN': 语雀 API 令牌 (可选，也可在客户端连接时通过参数传递)。
  - 'YUQUE_API_BASE_URL': 语雀 API 基础 URL，默认为 'https://www.yuque.com/api/v2'。
  - 'PORT': 服务器 HTTP 模式运行时监听的端口，默认为 '3000'。

服务器配置

MCP 客户端需要配置服务器的启动命令和参数才能连接到语雀 MCP 服务器。以下是基于本项目提供的 'package.json' 和 'README.md' 生成的服务器配置信息（JSON 格式）：

HTTP 服务器模式配置:

{
  "serverName": "Yuque-MCP-Server-HTTP",
  "command": "node",
  "args": [
    "dist/index.js"
  ],
  "transports": [
    {
      "type": "sse",
      "url": "http://localhost:3000/sse"
    }
  ],
  "description": "使用 HTTP 模式启动语雀 MCP 服务器，通过 SSE 协议与客户端通信。"
}

参数说明:

'serverName': 服务器名称，客户端用于标识连接的服务器。
'command': 启动服务器的命令，这里使用 'node' 运行 Node.js 程序。
'args': 传递给 'node' 命令的参数，'dist/index.js' 是编译后的 HTTP 服务器入口文件。
'transports': 配置服务器支持的传输协议。
- 'type': 传输协议类型，这里为 'sse' (Server-Sent Events)。
- 'url': SSE 端点 URL，客户端通过此 URL 建立 SSE 连接。注意 'localhost:3000' 需要替换为实际服务器地址和端口。
'description': 服务器配置的描述信息。

CLI Stdio 模式配置:

{
  "serverName": "Yuque-MCP-Server-CLI",
  "command": "node",
  "args": [
    "dist/cli.js"
  ],
  "transports": [
    {
      "type": "stdio"
    }
  ],
  "description": "使用 CLI (stdio) 模式启动语雀 MCP 服务器，通过标准输入输出与客户端通信。"
}

参数说明:

'serverName': 服务器名称，客户端用于标识连接的服务器。
'command': 启动服务器的命令，这里使用 'node' 运行 Node.js 程序。
'args': 传递给 'node' 命令的参数，'dist/cli.js' 是编译后的 CLI 服务器入口文件。
'transports': 配置服务器支持的传输协议。
- 'type': 传输协议类型，这里为 'stdio' (标准输入输出)。
'description': 服务器配置的描述信息。

注意:

以上 'command' 和 'args' 配置假定您已在项目根目录下执行 'npm run build' 命令，生成了 'dist' 目录及编译后的 JavaScript 文件。
如果您在开发模式下运行，可以直接使用 'npm run dev' 和 'npm run dev:cli' 中定义的命令，但 MCP 客户端配置应指向编译后的 'dist' 目录下的文件，以确保生产环境的稳定性。
'url' 中的 'localhost:3000' 需要根据实际服务器部署情况进行修改，例如部署到远程服务器时，需要替换为服务器的 IP 地址或域名。

基本使用方法

启动服务器:
- 开发模式:
  - HTTP 模式: 'npm run dev'
  - CLI 模式: 'npm run dev:cli'
- 生产模式:
  - 构建项目: 'npm run build'
  - HTTP 模式: 'npm run start'
  - CLI 模式: 'npm run start:cli'
连接 MCP 客户端:
- 根据您选择的服务器模式 (HTTP 或 CLI)，配置 MCP 客户端连接到相应的服务器地址或命令。
- 对于 HTTP 模式，客户端通常需要连接到 'http://<服务器地址>:<端口>/sse' 端点。
- 对于 CLI 模式，客户端通常通过标准输入输出与服务器进程通信。
使用工具:
- 服务器启动成功后，MCP 客户端可以调用服务器提供的工具，与语雀知识库进行交互。
- 可用工具包括：
  - 'get_current_user'
  - 'get_user_docs'
  - 'get_user_repos'
  - 'get_repo_docs'
  - 'get_doc'
  - 'create_doc'
  - 'update_doc'
  - 'delete_doc'
  - 'search'
  - 'get_group_statistics'
  - 'get_group_member_statistics'
  - 'get_group_book_statistics'
  - 'get_group_doc_statistics'
  - 'get_doc_chunks_info'
- 工具的具体参数和使用方法请参考 'src/server.ts' 文件中 'registerTools' 方法的定义和工具描述。
通过 SSE 端点传递 API Token:
- 在 HTTP 模式下，您可以通过 SSE 端点的查询参数 'accessToken' 传递语雀 API Token，例如： 'http://localhost:3000/sse?accessToken=your_yuque_api_token_here'
- 通过查询参数传递的 Token 优先级高于 '.env' 文件中配置的 'YUQUE_API_TOKEN'。

Docker 部署

本项目提供了 Dockerfile 和 docker-compose.yml 文件，方便使用 Docker 进行部署。具体步骤请参考仓库 README.md 文档中 "使用 Docker 部署" 章节。

关键词