飞书文档MCP工具

一个基于Model Context Protocol (MCP)的飞书文档操作工具，允许AI助手通过标准化接口读取、创建和编辑飞书wiki文档。

功能特性

• 🔗 链接解析: 解析飞书wiki文档链接，提取文档标识符
• 📖 文档读取: 获取飞书wiki文档的完整内容
• ✏️ 文档创建: 创建新的飞书wiki文档
• 📝 文档编辑: 编辑现有飞书wiki文档内容
• ➕ 增量更新: 在文档末尾追加内容，保留原有内容
• 🔐 安全认证: 基于飞书开放平台的OAuth 2.0认证
• 🚀 MCP协议: 完全兼容Model Context Protocol标准
• 📊 监控日志: 完整的操作审计和错误处理

快速开始

环境要求

• Node.js >= 18.0.0
• npm 或 pnpm
• 飞书开放平台应用凭证

安装

# 全局安装
npm install -g @be-link/feishu-doc-mcp
# 或者
pnpm add -g @be-link/feishu-doc-mcp

MCP使用配置

{
  "mcpServers": {
    "feishu-doc-mcp": {
      "command": "feishu-doc-mcp",
      "args": [
        "--app-id", "your_feishu_app_id",
        "--app-secret", "your_feishu_app_secret"
      ],
      "env": {
        "MCP_DISABLE_LOGS": "true"
      }
    }
  }
}

环境变量配置

| 环境变量 | 描述 | 默认值 | 可选值 | |---------|------|--------|--------| | MCP_DISABLE_LOGS | 禁用所有日志输出（推荐用于生产环境） | false | true, false | | MCP_LOG_LEVEL | 设置日志级别 | INFO | DEBUG, INFO, WARN, ERROR | | NODE_ENV | 运行环境 | - | development, production |

重要: 在Cursor等MCP客户端中使用时，建议设置 MCP_DISABLE_LOGS=true 以避免JSON解析错误。

安装后可直接在 MCP 客户端中配置使用。

使用示例

对话内容中只有包含飞书文档链接时，才会调用飞书文档MCP工具。

注意: 暂不支持同时执行创建 + 写入, 只能先创建文档, 再写入内容。

读取飞书文档内容

prompt:

帮我这篇飞书文档内容: https://example.feishu.cn/wiki/doccnxxxxxxxxxxxxxx

创建飞书wiki文档

prompt:

在飞书文档(https://example.feishu.cn/wiki/doccnxxxxxxxxxxxxxx)下创建一个子节点, 标题为"XXX接口文档"

编辑飞书wiki文档 (全量覆盖)

prompt:

将`api.md`的内容写入这个飞书文档中: https://example.feishu.cn/wiki/doccnxxxxxxxxxxxxxx

追加内容到飞书wiki文档

prompt:

在这个飞书文档末尾追加新的章节内容: https://example.feishu.cn/wiki/doccnxxxxxxxxxxxxxx

## 新增功能说明

这里是要追加的内容...

MCP工具说明

1. parse-feishu-wiki-url

解析飞书wiki文档链接，提取文档标识符。

参数:

• url (string): 飞书wiki文档链接

返回:

{
  "objToken": "doccnxxxxxxxxxxxxxx",
  "isValid": true,
  "originalUrl": "https://example.feishu.cn/wiki/doccnxxxxxxxxxxxxxx"
}

示例:

# MCP调用示例
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "parse-feishu-wiki-url",
    "arguments": {
      "url": "https://example.feishu.cn/wiki/doccnxxxxxxxxxxxxxx"
    }
  }
}

2. read-feishu-doc

读取飞书wiki文档内容。

参数:

• objToken (string): 文档标识符
• format (string, 可选): 返回格式，支持 'text', 'markdown', 'json'，默认 'markdown'

返回:

{
  "title": "文档标题",
  "content": "文档内容",
  "format": "text",
  "lastModified": "2024-01-01T00:00:00Z",
  "objToken": "doccnxxxxxxxxxxxxxx"
}

3. create-feishu-doc

创建新的飞书wiki文档。

参数:

• title (string): 文档标题
• content (string): 文档内容
• format (string, 可选): 内容格式，支持 'text', 'markdown'，默认 'markdown'

返回:

{
  "objToken": "doccnxxxxxxxxxxxxxx",
  "url": "https://example.feishu.cn/wiki/doccnxxxxxxxxxxxxxx",
  "title": "文档标题",
  "success": true
}

3.1. create-feishu-wiki-node

在飞书Wiki中创建新的节点。

参数:

• title (string): 节点标题
• parentNodeUrl (string): 父级节点的链接URL

返回:

{
  "objToken": "doccnxxxxxxxxxxxxxx",
  "url": "https://example.feishu.cn/wiki/doccnxxxxxxxxxxxxxx",
  "title": "节点标题",
  "success": true,
  "message": "Wiki节点创建成功"
}

示例:

# MCP调用示例
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create-feishu-wiki-node",
    "arguments": {
      "title": "新的Wiki节点",
      "parentNodeUrl": "https://example.feishu.cn/wiki/doccnxxxxxxxxxxxxxx"
    }
  }
}

4. edit-feishu-doc

编辑现有飞书wiki文档。

参数:

• objToken (string): 文档标识符
• title (string, 可选): 新的文档标题
• content (string, 可选): 新的文档内容
• format (string, 可选): 内容格式，支持 'text', 'markdown'，默认 'markdown'

返回:

{
  "objToken": "doccnxxxxxxxxxxxxxx",
  "success": true,
  "message": "文档更新成功"
}

5. append-to-feishu-doc

增量更新飞书文档内容（在文档末尾追加内容，不删除原有内容）。

参数:

• objToken (string): 文档的objToken标识符（来自parse-feishu-wiki-url工具的返回值）
• content (string): 增量写入的markdown文本内容

返回:

{
  "objToken": "doccnxxxxxxxxxxxxxx",
  "success": true,
  "message": "内容追加成功"
}

示例:

# MCP调用示例
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "append-to-feishu-doc",
    "arguments": {
      "objToken": "doccnxxxxxxxxxxxxxx",
      "content": "\n\n## 新增章节\n\n这是追加的内容..."
    }
  }
}

API文档

核心服务类

FeishuAuthService

处理飞书API认证和token管理。

class FeishuAuthService {
  async getTenantAccessToken(): Promise<string>
  async refreshToken(): Promise<void>
  isTokenValid(): boolean
}

WikiUrlParser

解析飞书wiki链接。

class WikiUrlParser {
  static parseUrl(url: string): ParseResult
  static isValidFeishuUrl(url: string): boolean
  static extractObjToken(url: string): string | null
}

DocContentService

处理文档内容读取。

class DocContentService {
  async getDocContent(objToken: string, format?: string): Promise<DocumentContent>
  async validateAccess(objToken: string): Promise<boolean>
}

DocEditService

处理文档创建和编辑。

class DocEditService {
  async createDocument(title: string, content: string, format?: string): Promise<CreateResult>
  async updateDocument(objToken: string, updates: DocumentUpdate): Promise<UpdateResult>
}

配置选项

interface AppConfig {
  feishu: {
    appId: string;
    appSecret: string;
    baseUrl: string;
    timeout?: number;
  };
  mcp: {
    port?: number;
    logLevel?: 'debug' | 'info' | 'warn' | 'error';
    maxConcurrentRequests?: number;
  };
  security: {
    enableAuditLog?: boolean;
    rateLimitEnabled?: boolean;
    maxRequestsPerMinute?: number;
  };
}

错误处理

错误类型

• AuthenticationError: 认证失败
• PermissionError: 权限不足
• DocumentNotFoundError: 文档不存在
• InvalidUrlError: 无效的URL格式
• RateLimitError: 请求频率超限
• NetworkError: 网络连接错误

错误响应格式

{
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "认证失败，请检查应用凭证",
    "details": {
      "timestamp": "2024-01-01T00:00:00Z",
      "requestId": "req_xxxxxxxxxxxxxx"
    }
  }
}

故障排除

常见问题

Q: 认证失败怎么办？ A: 检查配置中的 app-id 和 app-secret 是否正确，确保应用已启用相关权限。

Q: 无法读取文档内容？ A: 确认应用具有文档读取权限，检查objToken是否有效。

Q: MCP连接失败？ A: 检查 MCP 客户端配置是否正确，确认命令行参数格式正确。

Q: 请求频率超限？ A: 联系飞书开放平台申请更高的API配额。

贡献指南

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

许可证

MIT License - 详见 LICENSE 文件

注意: 使用本工具前请确保遵守飞书开放平台的使用条款和API限制。