Feishu MCP Server

🚀 飛書項目文檔

這是一個用於與飛書集成的工具包，支持多種功能模塊開發，能幫助開發者更便捷地實現與飛書的交互。

🚀 快速開始

本工具包可助力開發者輕鬆實現與飛書的集成，以下是詳細的安裝與使用步驟。

📦 安裝指南

安裝依賴

使用以下命令安裝必要的依賴：

npm install @feishu/abc123

💻 使用示例

基礎用法

初始化配置

import { FeiShuClient } from '@feishu/core';

const config: ClientConfig = {
  appId: 'your_app_id',
  appSecret: 'your_app_secret'
};

const client = new FeiShuClient(config);

高級用法

消息發送

發送文本消息

await client.sendMessage('open_chat_id', 'hello world');

發送卡片消息

const card = {
  type: 'message_card',
  content: [{
    type: 'text',
    text: '卡片內容'
  }]
};

await client.sendCardMessage('open_chat_id', card);

🔧 技術細節

錯誤處理

所有 API 請求錯誤將通過 FeiShuApiError 類進行包裝：

try {
  // 執行 API 操作
} catch (error) {
  if (error instanceof FeiShuApiError) {
    // 處理特定的 API 錯誤
    console.error(`飛書 API 錯誤 (${error.code}): ${error.message}`);
  } else {
    // 處理通用錯誤
    console.error('意外錯誤:', error);
  }
  // 轉換為用戶友好的消息
  throw new FeiShuApiError('操作失敗', { cause: error });
}

請參考錯誤處理文檔：錯誤處理指南

擴展指南

添加新功能步驟

1. 創建客戶端類 在 src/client/feature/ 目錄下創建新客戶端類：

// 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 中導出新服務：

// src/services/index.ts
export { FeatureService } from './feature/feature-service';

4. 創建 MCP 工具 在 src/server/tools/feature-tools.ts 中創建工具函數：

// src/server/tools/feature-tools.ts
export function createFeatureTool() {
  return {
    getFeature: async (id: string) => {
      const service = new FeatureService({ /* 配置 */ });
      return await service.getFeature(id);
    }
  };
}

5. 使用新功能

import { createFeatureTool } from './tools/feature-tools';

const tool = createFeatureTool();
await tool.getFeature('123');

🤝 貢獻指南

提交代碼規範

請遵循以下提交規範：

1. 每個提交必須有明確的提交信息
2. 保持代碼格式統一
3. 提交前通過所有測試用例

創建新功能模塊

1. 在 src/components/ 下創建新組件
2. 實現組件邏輯
3. 在示例頁面中集成組件

📁 項目結構

project/
├── src/
│   ├── client/
│   │   └── feature/
│   │       └── feature-client.ts
│   └── services/
│       └── feature/
│           └── feature-service.ts
└── tools/
    └── feature-tools.ts

📄 許可證

本項目遵循 MIT 協議。