使用说明

项目简介

语雀 MCP 服务器是一个基于 Model Context Protocol (MCP) 构建的应用后端，旨在将语雀知识库平台的功能以标准化的 工具 (Tools) 形式提供给大型语言模型 (LLM) 客户端。通过此服务器，LLM 可以安全、可扩展地访问和操作语雀中的知识库、文档和用户信息，实现更智能的应用场景，例如：

知识库问答: LLM 可以通过工具检索语雀文档内容，回答用户关于知识库的问题。
文档创作辅助: LLM 可以利用工具创建和更新语雀文档，辅助用户进行内容创作。
团队知识管理: LLM 可以结合团队统计工具，分析团队知识库的使用情况，辅助团队进行知识管理和优化。

主要功能点

资源访问: 提供多种工具，允许 LLM 查询用户信息、知识库信息、文档内容，包括文档的详细内容和分块信息，支持处理大型文档。
知识库管理: 支持 LLM 创建、更新和删除语雀文档，实现对知识库内容的管理和维护。
内容搜索: 提供工具支持在语雀平台中进行文档和知识库内容的搜索，并支持多种搜索参数。
统计分析: 提供团队统计数据查询工具，包括团队成员、知识库和文档的统计信息，帮助分析和监控团队知识库使用情况。
多协议支持: 同时支持 HTTP SSE 和 CLI Stdio 两种传输协议，满足不同应用场景的需求。
灵活配置: 支持通过环境变量或 SSE 连接时的查询参数配置语雀 API 令牌和 Base URL，方便部署和使用。

安装步骤

前提条件:
- 确保已安装 Node.js 18 或更高版本和 npm 包管理器。
- 拥有一个语雀账号，并获取语雀 API 令牌。

克隆仓库: 打开终端，执行以下命令克隆仓库到本地：

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

进入项目目录:
```
cd Yuque-MCP-Server
```
安装依赖:
```
npm install
```

配置环境变量: 复制 '.env.example' 文件并重命名为 '.env'：

cp .env.example .env

编辑 '.env' 文件，根据需要配置以下环境变量：

YUQUE_API_TOKEN=your_yuque_api_token_here  # 您的语雀 API 令牌 (必填)
YUQUE_API_BASE_URL=https://www.yuque.com/api/v2 # 语雀 API 基础 URL (可选，默认为官方 API)
PORT=3000                                    # 服务器端口 (可选，默认为 3000)

注意: 强烈建议配置 'YUQUE_API_TOKEN'，否则部分需要身份验证的工具将无法使用。

服务器配置

MCP 客户端需要配置服务器的启动命令和参数才能连接到语雀 MCP 服务器。以下是不同运行模式的配置示例 (JSON 格式)：

HTTP 服务器模式 (开发环境)

{
  "serverName": "YuqueMCP-HTTP-Dev",
  "command": "npm",
  "args": ["run", "dev"]  // 运行开发模式的 HTTP 服务器，监听端口在 .env 文件或默认 3000 端口中配置
}

HTTP 服务器模式 (生产环境)

{
  "serverName": "YuqueMCP-HTTP-Prod",
  "command": "npm",
  "args": ["run", "start"] // 运行生产模式的 HTTP 服务器，监听端口配置同上
}

CLI Stdio 模式 (开发环境)

{
  "serverName": "YuqueMCP-CLI-Dev",
  "command": "npm",
  "args": ["run", "dev:cli"] // 运行开发模式的 CLI Stdio 服务器，通过标准输入输出进行通信
}

CLI Stdio 模式 (生产环境)

{
  "serverName": "YuqueMCP-CLI-Prod",
  "command": "npm",
  "args": ["run", "start:cli"] // 运行生产模式的 CLI Stdio 服务器，通过标准输入输出进行通信
}

提示:

'serverName' 字段可以自定义，用于在 MCP 客户端中标识不同的服务器连接。
'command' 字段指定启动服务器的命令，通常为 'npm' 或 'node'。
'args' 字段是传递给命令的参数，用于指定运行模式。
选择 HTTP 模式时，请确保 MCP 客户端配置正确的 SSE 或 Message 端点 URL (默认为 '/sse' 和 '/messages')。
选择 CLI Stdio 模式时，MCP 客户端需要配置为通过标准输入输出与服务器进程通信。

基本使用方法

启动服务器: 根据选择的运行模式，在项目根目录下执行相应的命令：
- HTTP 开发模式: 'npm run dev'
- HTTP 生产模式: 'npm run start' (需先执行 'npm run build')
- CLI Stdio 开发模式: 'npm run dev:cli'
- CLI Stdio 生产模式: 'npm run start:cli' (需先执行 'npm run build')
连接 MCP 客户端: 配置您的 MCP 客户端，使用上述 服务器配置 中生成的 JSON 配置信息连接到已启动的语雀 MCP 服务器。
使用工具: 连接成功后，MCP 客户端将可以调用服务器提供的 工具 (Tools)，例如 'get_doc' (获取文档内容)、'search' (搜索文档) 等。
查看可用工具: 服务器启动成功后，会在控制台输出所有注册的工具列表及其描述信息，您可以参考这些信息在 MCP 客户端中使用相应的工具。

示例: 使用 'get_doc' 工具获取指定文档内容

假设您想使用 'get_doc' 工具获取知识库 'my-org/my-repo' 中 'my-doc' 文档的内容，您需要在 MCP 客户端中构建如下的 JSON-RPC 请求：

{
  "jsonrpc": "2.0",
  "method": "call_tool",
  "params": {
    "tool_name": "get_doc",
    "tool_parameters": {
      "namespace": "my-org/my-repo",
      "slug": "my-doc"
    }
  },
  "id": "get-doc-1" // 请求 ID，可自定义
}

服务器将返回包含文档内容的 JSON-RPC 响应。

详细工具使用方法和参数说明请参考仓库 README 文档和服务器启动后的工具列表输出。

关键词