飞书-MCP服务器

Name: 飞书-MCP服务器
Author: sdd330

作者：sdd33046 星标更新：2025-03-27

安装使用来源：spider==github.com

项目介绍

技术文档摘要

Feishu MCP Server

Feishu MCP服务器基于Model Context Protocol。该服务提供Feishu API集成，使AI模型能够轻松与Feishu服务交互。

功能特点

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

项目架构

代码结构

/src
  /client        # API客户端实现（底层API请求封装）
    /documents   # 文档相关API客户端
    /bots        # 机器人API客户端
    /chats       # 聊天相关API客户端
  /services      # 服务层实现（业务逻辑和错误处理）
    /documents   # 文档相关服务
    /bots        # 机器人相关服务
    /chats       # 聊天相关服务
  /server        # MCP服务器实现
    /tools       # MCP工具注册和实现
  /typings       # 类型定义
  /utils         # 通用工具函数
  /http          # HTTP服务器实现
  /logger        # 日志服务
  /consts        # 常量定义
  config.ts      # 配置管理
  index.ts       # 入口点

设计原则

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

1. 分层职责

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

2. 依赖方向

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

3. 错误处理策略

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

工作流程

MCP服务器接收请求(STDIO或HTTP)
工具层验证参数并调用相应的服务
服务层实现业务逻辑并调用客户端
客户端执行实际API请求并返回结果
结果由服务层处理并返回给工具层
工具层格式化结果并返回给MCP服务器

快速开始

前置条件

Node.js 23.0或更高版本
Pnpm包管理器
有效的Feishu开发者账户和已创建的自建应用

安装步骤

克隆仓库

git clone https://github.com/yourusername/feishu-mcp-server.git
cd feishu-mcp-server

安装依赖

pnpm install

创建.env文件

# 飞书应用凭证（必填）
FEISHU_APP_ID=your_app_id
FEISHU_APP_SECRET=your_app_secret

# 服务器配置（可选）
PORT=3344
LOG_LEVEL=info

运行服务

开发模式

# 开发模式（自动重启）
pnpm dev

# 或使用普通启动
pnpm start

生产模式

# 构建项目
pnpm build

# 运行编译后的代码
node dist/index.js

STDIO模式

# 方法1：使用环境变量
NODE_ENV=cli node dist/index.js

# 方法2：使用命令行参数
node dist/index.js --stdio

配置说明

选项	环境变量	命令行参数	默认值	描述
Feishu应用ID	`FEISHU_APP_ID`	`--feishu-app-id`	-	Feishu自建应用的App ID
Feishu应用密钥	`FEISHU_APP_SECRET`	`--feishu-app-secret`	- Feishu自建应用的App Secret
服务器端口	`PORT`	`--port`	3344	HTTP服务器端口号
日志级别	`LOG_LEVEL`	`--log-level`	info	日志级别 (debug/info/warn/error)
令牌缓存时间	`TOKEN_CACHE_DURATION`	-	7100	访问令牌缓存时间（秒）

API文档

文档操作

`get_feishu_doc_raw`

获取Feishu文档的原始内容。

参数

docId -文档ID，通常在URL中找到（例如feishu.cn/docx)/<documentId>)

文档的文本内容

`get_feishu_doc_info`

获取Feishu文档的元数据信息。

参数

docId -文档ID

文档元数据（JSON格式）

机器人操作

`send_feishu_text_message`

向Feishu聊天发送文本消息。

参数

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

发送状态和消息ID

`send_feishu_card`

向Feishu聊天发送互动卡片。

参数

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

发送状态和消息ID

聊天操作

`get_feishu_chat_info`

获取Feishu聊天的基本信息。

参数

chatId -聊天ID

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

多维表格操作

`get_feishu_sheet_meta`

从Feishu多维表格中获取元数据信息。

参数

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

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

`get_feishu_sheet_tables`

从Feishu多维表格中获取数据表列表。

参数

appToken -多维表格ID，通常在URL中找到（例如feishu.cn/base)/<appToken> 或 feishu.cn/app/<appToken>)
pageSize -每页返回的数据表数量，可选，默认为20，最大为100
pageToken -分页标签，可选，用于从下一页检索数据

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

`get_feishu_sheet_views`

从Feishu多维表格中获取数据表视图列表。

参数

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

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

`get_feishu_sheet_view`

获取Feishu多维表格中数据表的具体视图详细信息。

参数

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

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

`get_feishu_sheet_records`

从Feishu多维表格中获取数据表记录。

参数

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

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

`get_feishu_sheet_record`

从Feishu多维表格中获取单个记录。

参数

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

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

开发指南

代码规范

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

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

运行代码检查：

# 运行代码检查
pnpm lint

# 运行代码检查并修复
pnpm lint:fix

# 运行代码格式化
pnpm format

错误处理

所有与Feishu API相关的错误应使用FeiShuApiError类进行处理：

try {
  // API操作
} catch (error) {
  if (error instanceof FeiShuApiError) {
    // 处理特定的API错误
    logger.error(`FeiShu API Error (${error.code}): ${error.message}`);
  } else {
    // 处理通用错误
    logger.error('Unexpected error:', error);
  }
  // 转换为用户友好的消息
  throw new FeiShuApiError('操作失败', { cause: error });
}

提交规范

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

<type>(<scope>): <subject>

例如：

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

支持的类型：

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

扩展指南

添加新功能的步骤：

创建客户端类

在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 });
  }
}

创建服务类

在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);
    }
  }
}

注册服务
- 在src/services/index.ts导出新的服务
- 将服务添加到FeiShuServices类中

创建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',
    '从FeiShu获取特性',
    {
      id: z.string().describe('特性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);
      }
    }
  );
}

注册工具
- 在src/server/tools/index.ts引入并注册新的工具

常见问题

认证失败

问题API请求返回认证错误

解决方案：

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

令牌刷新问题

问题令牌刷新失败