飞书MCP服务器

飞书MCP服务器是一个基于Model Context Protocol的服务，提供飞书API集成，使AI模型能够轻松与飞书服务交互。

目录

• 功能特点
• 项目架构
  • 代码结构
  • 设计原则
  • 工作流程
• 快速开始
  • 前提条件
  • 安装步骤
  • 运行服务
• 配置说明
• API文档
  • 文档操作
  • 机器人操作
  • 聊天操作
  • 多维表格操作
• 开发指南
  • 代码规范
  • 错误处理
  • 提交规范
  • 扩展指南
• 常见问题
• 许可证
• 贡献指南

功能特点

• 文档服务：读取飞书文档内容和元数据
• 机器人服务：发送文本消息和交互卡片到飞书聊天
• 聊天服务：管理群组和聊天会话
• 多模式支持：
  • STDIO模式：通过标准输入/输出通信，适用于CLI环境和集成到其他应用
  • HTTP模式：提供REST API和SSE连接，适用于Web服务和分布式部署
• 完善的错误处理：统一的错误处理机制，提供详细的错误信息
• 类型安全：基于TypeScript，提供完整的类型定义
• 模块化架构：易于扩展新功能和集成其他飞书API

项目架构

代码结构

设计原则

项目采用分层架构设计，确保关注点分离和职责明确：

1. 分层职责

• 客户端层（Client）
  • 封装HTTP请求的细节
  • 处理底层API参数和响应格式
  • 管理认证和令牌刷新
  • 不包含业务逻辑
• 服务层（Service）
  • 使用客户端执行API操作
  • 实现业务逻辑
  • 处理和转换错误
  • 提供友好的接口给上层使用
• 工具层（Tools）
  • 实现MCP协议定义的工具
  • 处理参数验证和格式转换
  • 调用服务层完成实际操作
  • 格式化返回结果

2. 依赖方向

• 服务层依赖客户端层
• 工具层依赖服务层
• 严格避免循环依赖

3. 错误处理策略

• 使用 FeiShuApiError 统一处理API错误
• 客户端层返回原始错误
• 服务层捕获并转换为业务相关错误
• 工具层处理所有异常并返回用户友好消息

工作流程

1. MCP服务器接收请求（STDIO或HTTP）
2. 工具层验证参数并调用相应服务
3. 服务层实现业务逻辑并调用客户端
4. 客户端执行实际API请求并返回结果
5. 结果经由服务层处理后返回给工具层
6. 工具层格式化结果并返回给MCP服务器

快速开始

前提条件

• Node.js 23.0或更高版本
• pnpm包管理器
• 有效的飞书开发者账号和已创建的自建应用

安装步骤

1. 克隆仓库

2. 安装依赖

3. 创建.env文件

运行服务

开发模式

生产模式

STDIO模式

配置说明

API文档

文档操作

get_feishu_doc_raw

获取飞书文档的原始内容。

参数：

• docId - 文档ID，通常在URL中找到 (例如：feishu.cn/docx/)

返回：

• 文档的文本内容

get_feishu_doc_info

获取飞书文档的元数据信息。

参数：

• docId - 文档ID

返回：

• 文档的元数据（JSON格式）

机器人操作

send_feishu_text_message

发送文本消息到飞书聊天。

参数：

• chatId - 聊天ID
• text - 要发送的文本内容

返回：

• 发送状态和消息ID

send_feishu_card

发送交互卡片到飞书聊天。

参数：

• chatId - 聊天ID
• cardContent - 卡片内容（JSON字符串）

返回：

• 发送状态和消息ID

聊天操作

get_feishu_chat_info

获取飞书聊天的基本信息。

参数：

• chatId - 聊天ID

返回：

• 聊天的基本信息（JSON格式）

多维表格操作

get_feishu_sheet_meta

获取飞书多维表格的元数据信息。

参数：

• appToken - 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/ 或 feishu.cn/app/)

返回：

• 多维表格的元数据（JSON格式），包含表格ID、名称、修订版本、创建者、创建时间、权限等信息

get_feishu_sheet_tables

获取飞书多维表格中的数据表列表。

参数：

• appToken - 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/ 或 feishu.cn/app/)
• pageSize - 每页返回的数据表数量，可选，默认为20，最大为100
• pageToken - 分页标记，可选，用于获取下一页数据

返回：

• 数据表列表（JSON格式），包含表ID、名称、字段信息等

get_feishu_sheet_views

获取飞书多维表格中数据表的视图列表。

参数：

• appToken - 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/ 或 feishu.cn/app/)
• tableId - 数据表ID
• pageSize - 每页返回的视图数量，可选，默认为20，最大为100
• pageToken - 分页标记，可选，用于获取下一页数据

返回：

• 视图列表（JSON格式），包含视图ID、名称、类型和属性等信息

get_feishu_sheet_view

获取飞书多维表格中数据表特定视图的详细信息。

参数：

• appToken - 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/ 或 feishu.cn/app/)
• tableId - 数据表ID
• viewId - 视图ID，要获取详细信息的视图

返回：

• 视图详情（JSON格式），包含视图ID、名称、类型和属性等信息

get_feishu_sheet_records

获取飞书多维表格中的数据表记录。

参数：

• appToken - 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/ 或 feishu.cn/app/)
• tableId - 数据表ID
• viewId - 视图ID，可选，不指定时使用默认视图
• fieldIds - 字段ID列表，可选，指定返回哪些字段
• filter - 过滤条件，可选，使用FQL格式
• sort - 排序条件，可选，使用JSON格式
• pageSize - 每页返回的记录数量，可选，默认为20，最大为100
• pageToken - 分页标记，可选，用于获取下一页数据

返回：

• 记录列表（JSON格式），包含记录ID和字段值

get_feishu_sheet_record

获取飞书多维表格中的单条记录。

参数：

• appToken - 多维表格ID，通常在URL中找到 (例如：feishu.cn/base/ 或 feishu.cn/app/)
• tableId - 数据表ID
• recordId - 记录ID
• fieldIds - 字段ID列表，可选，指定返回哪些字段

返回：

• 单条记录（JSON格式），包含记录ID和字段值

开发指南

代码规范

项目使用严格的TypeScript规范和ESLint配置：

• 使用TypeScript接口和类型定义
• 避免使用 any 类型
• 使用 Record<string, unknown> 替代 object 类型
• 所有代码文件、注释和错误消息使用英文

运行代码检查：

错误处理

所有与飞书API相关的错误应使用 FeiShuApiError 类处理：

提交规范

提交消息必须遵循以下格式：

例如：

• feat(bot): 添加发送卡片功能
• fix(documents): 修复文档内容获取错误

支持的类型：

• feat: 新功能
• fix: 修复Bug
• docs: 文档变更
• style: 代码格式调整
• refactor: 代码重构
• perf: 性能优化
• test: 测试相关
• chore: 构建过程或辅助工具的变动

扩展指南

添加新功能的步骤：

1. 创建客户端类
   • 在 src/client/<feature>/ 目录下创建
   • 继承 ApiClient 基类
   • 实现API请求方法
   // src/client/feature/feature-client.ts export class FeatureClient extends ApiClient { async getFeatureData(id: string): Promise<FeatureData> { return this.request<FeatureResponse>('/feature/get', { id }); } }
2. 创建服务类
   • 在 src/services/<feature>/ 目录下创建
   • 使用相应的客户端类
   • 实现业务逻辑和错误处理
   // src/services/feature/feature-service.ts export class FeatureService { private client: FeatureClient; constructor(config: ApiClientConfig) { this.client = new FeatureClient(config); } async getFeature(id: string): Promise<Feature> { try { const data = await this.client.getFeatureData(id); return this.transformData(data); } catch (error) { handleError(error); } } }
3. 注册服务
   • 在 src/services/index.ts 中导出新服务
   • 将服务添加到 FeiShuServices 类
4. 创建MCP工具
   • 在 src/server/tools/feature-tools.ts 中创建
   • 使用Zod进行参数验证
   • 调用服务层方法
   // src/server/tools/feature-tools.ts export function registerFeatureTools(params: ToolRegistryParams): void { const { server, services, logger } = params; server.tool( 'get_feishu_feature', 'Get feature from FeiShu', { id: z.string().describe('Feature ID'), }, async ({ id }) => { try { const feature = await services.feature.getFeature(id); return { content: [{ type: 'text', text: JSON.stringify(feature) }] }; } catch (error) { return handleToolError(error, logger); } } ); }
5. 注册工具
   • 在 src/server/tools/index.ts 中引入并注册新工具

常见问题

认证失败

问题：API请求返回认证错误

解决方案：

• 检查应用ID和密钥是否正确
• 确认应用具有所需的权限范围
• 检查服务器时间是否正确同步

令牌刷新问题

问题：令牌刷新失败

解决方案：

• 设置更短的令牌缓存时间
• 检查网络连接稳定性
• 查看飞书开发者平台的应用状态

许可证

MIT

贡献指南

欢迎贡献！请遵循以下步骤：

1. Fork仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'feat: add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 开启Pull Request

提交PR前请确保：

• 代码通过所有测试
• 更新了相关文档
• 遵循项目的代码风格和命名约定
• 添加必要的单元测试