架构设计 - cso1z/Feishu-MCP GitHub Wiki

架构设计文档

目录

概述

飞书 MCP 服务器是一个基于 Model Context Protocol (MCP) 的中间件服务，它连接 AI 编码工具（如 Cursor、Windsurf）和飞书文档系统，使 AI 工具能够直接访问和操作飞书文档。

设计目标

  1. 高性能：通过缓存机制减少 API 调用，提高响应速度
  2. 高可用：支持多用户并发，自动处理 Token 刷新
  3. 易扩展：模块化设计，易于添加新功能
  4. 易维护：清晰的代码结构，完善的错误处理

整体架构

架构图

┌─────────────────────────────────────────────────────────────┐
│                        AI 编码工具层                          │
│              (Cursor, Windsurf, Cline等)                     │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Protocol
                         │ (JSON-RPC 2.0)
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    传输层 (Transport Layer)                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │  SSE (HTTP)  │  │   Stdio      │  │ Streamable   │     │
│  │              │  │              │  │    HTTP      │     │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘     │
└─────────┼──────────────────┼──────────────────┼────────────┘
          │                  │                  │
          └──────────────────┼──────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                    MCP 服务器层 (MCP Layer)                   │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              FeishuMcp (McpServer)                   │  │
│  │  ┌────────────────────────────────────────────────┐  │  │
│  │  │  工具注册 (Tools Registration)                  │  │  │
│  │  │  - feishuTools                                  │  │  │
│  │  │  - feishuBlockTools                             │  │  │
│  │  │  - feishuFolderTools                            │  │  │
│  │  └────────────────────────────────────────────────┘  │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────┬────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│                   服务层 (Service Layer)                      │
│  ┌──────────────────────────────────────────────────────┐  │
│  │         FeishuApiService (单例模式)                   │  │
│  │  ┌────────────────────────────────────────────────┐  │  │
│  │  │  BaseApiService (基础API服务)                    │  │  │
│  │  │  - HTTP请求封装                                 │  │  │
│  │  │  - 错误处理                                     │  │  │
│  │  │  - Token管理                                    │  │  │
│  │  └────────────────────────────────────────────────┘  │  │
│  │  ┌────────────────────────────────────────────────┐  │  │
│  │  │  BlockFactory (文档块工厂)                      │  │  │
│  │  │  - 创建各种类型的文档块                          │  │  │
│  │  └────────────────────────────────────────────────┘  │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────┬────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│                   工具层 (Utility Layer)                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  Config  │  │  Logger  │  │  Cache   │  │   Auth   │   │
│  │  配置管理  │  │  日志    │  │  缓存     │  │  认证     │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────┬────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│                     飞书开放平台 API                          │
│              (https://open.feishu.cn/open-apis)               │
└─────────────────────────────────────────────────────────────┘

核心组件

1. 传输层 (Transport Layer)

传输层负责处理与客户端的通信，支持三种传输方式：

SSE (Server-Sent Events)

  • 用途：HTTP 模式下的长连接通信
  • 特点：服务器主动推送消息，客户端通过 POST 请求响应
  • 实现：SSEServerTransport 来自 @modelcontextprotocol/sdk 
// 文件位置: src/server.ts
app.get('/sse', async (req: Request, res: Response) => {
  const sseTransport = new SSEServerTransport('/messages', res);
  const server = new FeishuMcp();
  await server.connect(sseTransport);
});

Stdio (标准输入输出)

  • 用途：CLI 模式下的进程间通信
  • 特点：不占用网络端口，适合嵌入式场景
  • 实现：StdioServerTransport 来自 @modelcontextprotocol/sdk 
// 文件位置: src/index.ts
if (isStdioMode) {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

Streamable HTTP

  • 用途：HTTP 模式下的双向通信
  • 特点：使用标准的 HTTP POST 请求，支持会话管理
  • 实现：StreamableHTTPServerTransport 来自 @modelcontextprotocol/sdk

2. MCP 服务器层 (MCP Layer)

MCP 服务器层是整个系统的核心，负责：

  • 注册工具函数
  • 处理工具调用请求
  • 管理工具执行上下文
// 文件位置: src/mcp/feishuMcp.ts
export class FeishuMcp extends McpServer {
  constructor() {
    super(serverInfo, serverOptions);
    this.initFeishuService();
    this.registerAllTools();
  }
  
  private registerAllTools(): void {
    registerFeishuTools(this, this.feishuService);
    registerFeishuBlockTools(this, this.feishuService);
    registerFeishuFolderTools(this, this.feishuService);
  }
}

3. 服务层 (Service Layer)

FeishuApiService

飞书 API 服务是单例模式，提供所有飞书 API 操作：

// 文件位置: src/services/feishuApiService.ts
export class FeishuApiService extends BaseApiService {
  private static instance: FeishuApiService;
  
  public static getInstance(): FeishuApiService {
    if (!FeishuApiService.instance) {
      FeishuApiService.instance = new FeishuApiService();
    }
    return FeishuApiService.instance;
  }
}

主要功能：

  • 文档操作（创建、读取、更新）
  • 文档块操作（创建、更新、删除）
  • 文件夹管理
  • 图片上传和处理

BaseApiService

基础 API 服务提供通用的 HTTP 请求处理：

// 文件位置: src/services/baseService.ts
export abstract class BaseApiService {
  protected async request<T>(
    endpoint: string,
    method: string = 'GET',
    data?: any,
    needsAuth: boolean = true
  ): Promise<T> {
    // 获取访问令牌
    const accessToken = await this.getAccessToken(userKey);
    
    // 发送 HTTP 请求
    const response = await axios(config);
    
    // 处理响应和错误
    return response.data.data;
  }
}

4. 工具层 (Utility Layer)

Config (配置管理)

// 文件位置: src/utils/config.ts
export class Config {
  // 从环境变量和命令行参数加载配置
  // 支持配置验证和默认值
}

Logger (日志系统)

// 文件位置: src/utils/logger.ts
export class Logger {
  // 统一的日志接口
  // 支持不同日志级别
  // 集成 MCP 日志系统
}

TokenCacheManager (Token 缓存)

// 文件位置: src/utils/auth/tokenCacheManager.ts
export class TokenCacheManager {
  // 管理用户 token 和租户 token
  // 支持文件持久化
  // 自动清理过期 token
}

技术栈

核心依赖

依赖 版本 用途
@modelcontextprotocol/sdk ^1.17.5 MCP 协议实现
axios ^1.7.9 HTTP 请求库
express ^4.21.2 HTTP 服务器
zod ^3.24.2 参数验证
typescript ^5.7.3 类型系统

开发依赖

  • tsx - TypeScript 执行器
  • eslint - 代码检查
  • prettier - 代码格式化
  • jest - 单元测试

数据流转

请求处理流程

1. AI 工具发起请求
   ↓
2. 传输层接收请求 (SSE/Stdio/HTTP)
   ↓
3. MCP 服务器解析请求
   ↓
4. 查找并调用对应工具函数
   ↓
5. 工具函数调用 FeishuApiService
   ↓
6. FeishuApiService 检查 Token
   ↓ (Token 不存在或过期)
7. TokenCacheManager 获取/刷新 Token
   ↓
8. 发送 HTTP 请求到飞书 API
   ↓
9. 处理响应数据
   ↓
10. 返回结果给 AI 工具

Token 管理流程

// 文件位置: src/services/feishuApiService.ts
protected async getAccessToken(userKey?: string): Promise<string> {
  const clientKey = AuthUtils.generateClientKey(userKey);
  
  if (authType === 'tenant') {
    // 租户模式：获取租户访问令牌
    return this.getTenantAccessToken(appId, appSecret, clientKey);
  } else {
    // 用户模式：获取用户访问令牌
    return this.authService.getUserAccessToken(clientKey, appId, appSecret);
  }
}

设计模式

1. 单例模式 (Singleton)

多个核心服务使用单例模式，确保全局唯一实例：

// FeishuApiService
// Config
// TokenCacheManager
// CacheManager
// BlockFactory

2. 工厂模式 (Factory)

BlockFactory 用于创建不同类型的文档块：

// 文件位置: src/services/blockFactory.ts
export class BlockFactory {
  createTextBlock(options: TextBlockOptions): any;
  createCodeBlock(options: CodeBlockOptions): any;
  createHeadingBlock(options: HeadingBlockOptions): any;
  // ...
}

3. 策略模式 (Strategy)

不同的认证策略（租户认证 vs 用户认证）：

if (authType === 'tenant') {
  return this.getTenantAccessToken(...);
} else {
  return this.authService.getUserAccessToken(...);
}

4. 模板方法模式 (Template Method)

BaseApiService 定义了请求处理的模板，子类实现具体细节：

protected async request(...) {
  // 1. 构建请求
  // 2. 添加认证
  // 3. 发送请求
  // 4. 处理错误
  // 5. 返回结果
}

扩展性设计

添加新工具

  1. 在对应的工具文件中添加工具函数：
// 文件位置: src/mcp/tools/feishuTools.ts
server.tool(
  'new_feishu_tool',
  '工具描述',
  {
    param1: z.string().describe('参数1'),
  },
  async ({ param1 }) => {
    // 实现逻辑
  }
);
  1. 在 FeishuApiService 中添加对应的 API 方法（如需要）

添加新的传输方式

  1. 在 server.ts 中添加新的传输层处理
  2. 实现对应的连接和消息处理逻辑

添加新的认证方式

  1. 扩展 AuthService 类
  2. 在 FeishuApiService.getAccessToken() 中添加新的认证逻辑

相关文档:

飞书 MCP 服务器 | GitHub 仓库 | 问题反馈

如有问题或建议，欢迎提交 Issue 或 Pull Request！

⚠️ **GitHub.com Fallback** ⚠️