Webex Messaging MCP Server

🚀 Webex MCP Server

Webex MCP Server 是一個模型上下文協議（MCP）服務器，它為 AI 助手提供了全面訪問思科 Webex 消息傳遞功能的途徑，極大地增強了 AI 與 Webex 平臺的交互能力。

🚀 快速開始

前提條件

• Node.js 18+（推薦 20+）。注意：如果使用較低版本的 Node 運行，fetch 將不可用。工具使用 fetch 進行 HTTP 調用。要解決此問題，可以將工具修改為使用 node-fetch。確保 node-fetch 作為依賴項安裝，然後將其作為 fetch 導入到每個工具文件中。
• Docker（可選，用於容器化部署）
• 從 developer.webex.com 獲取的 Webex API 令牌

令牌更新

Webex 承載令牌的有效期較短，當前令牌將在 12 小時後過期。要更新令牌，請按以下步驟操作：

1. 訪問：https://developer.webex.com/messaging/docs/api/v1/rooms/list-rooms
2. 使用您的電子郵件登錄
3. 從您的個人資料中複製新的承載令牌
4. 使用新令牌更新環境變量 "WEBEX_PUBLIC_WORKSPACE_API_KEY"（去除 "Bearer " 前綴）

安裝

1. 克隆並安裝依賴項：

git clone <repository-url>
cd webex-messaging-mcp-server
npm install

2. 配置環境：

cp .env.example .env
# 使用您的 Webex API 令牌編輯 .env

3. 測試服務器：

# 列出可用工具
node index.js tools

# 詳細分析發現工具
npm run discover-tools

# 啟動 MCP 服務器（STDIO 模式 - 默認）
node mcpServer.js

# 啟動 MCP 服務器（HTTP 模式）
npm run start:http

✨ 主要特性

• ✅ 完整的 Webex API 覆蓋：提供 52 種工具，涵蓋所有主要的消息傳遞操作
• ✅ Docker 支持：支持生產就緒的容器化部署
• ✅ 雙傳輸模式：支持 STDIO 和 HTTP（StreamableHTTP）兩種模式
• ✅ 企業就緒：支持思科企業認證
• ✅ 類型安全：完全使用 TypeScript/JavaScript 實現，並進行了適當的錯誤處理
• ✅ 集中配置：方便進行令牌和端點管理

📦 安裝指南

環境變量

獲取 Webex API 令牌

1. 訪問 developer.webex.com
2. 使用您的思科/Webex 賬戶登錄
3. 從 API 文檔中複製承載令牌
4. 重要提示：添加到 .env 文件時，去除 "Bearer " 前綴

💻 使用示例

基礎用法

工具發現命令

# 人類可讀的工具分析
npm run discover-tools

# 用於編程使用的 JSON 輸出
npm run discover-tools -- --json

# 按類別過濾工具
ENABLED_TOOLS=create_message,list_rooms npm run discover-tools

# 獲取幫助
npm run discover-tools -- --help

高級用法

MCP 客戶端集成

Claude Desktop（STDIO 模式）

在您的 Claude Desktop 配置中添加以下內容：

{
  "mcpServers": {
    "webex-messaging": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "WEBEX_PUBLIC_WORKSPACE_API_KEY",
        "-e",
        "WEBEX_USER_EMAIL",
        "-e",
        "WEBEX_API_BASE_URL",
        "webex-mcp-server"
      ],
      "env": {
        "WEBEX_USER_EMAIL": "your.email@company.com",
        "WEBEX_API_BASE_URL": "https://webexapis.com/v1",
        "WEBEX_PUBLIC_WORKSPACE_API_KEY": "your_token_here"
      }
    }
  }
}

HTTP 模式集成

對於基於 HTTP 的 MCP 客戶端，以 HTTP 模式啟動服務器：

# 啟動 HTTP 服務器
npm run start:http

# 服務器端點：
# 健康檢查：http://localhost:3001/health
# MCP 端點：http://localhost:3001/mcp

該服務器支持 MCP 2025 - 06 - 18 協議和 StreamableHTTP 傳輸，包括：

• 正確的 CORS 配置，暴露 mcp - session - id 頭
• 有狀態連接的會話管理
• 服務器發送事件（SSE）響應格式

其他 MCP 客戶端

對於 STDIO 模式：

docker run -i --rm --env-file .env webex-mcp-server

對於 HTTP 模式：

docker run -p 3001:3001 --rm --env-file .env webex-mcp-server --http

📚 詳細文檔

可用工具

核心消息傳遞

• create_message - 向房間發送消息
• list_messages - 檢索消息歷史記錄
• edit_message - 修改現有消息
• delete_message - 刪除消息
• get_message_details - 獲取特定消息信息

房間管理

• create_room - 創建新的 Webex 空間
• list_rooms - 瀏覽可用房間
• get_room_details - 獲取房間信息
• update_room - 修改房間設置
• delete_room - 刪除房間

團隊操作

• create_team - 創建團隊
• list_teams - 瀏覽團隊
• get_team_details - 獲取團隊信息
• update_team - 修改團隊設置
• delete_team - 刪除團隊

成員管理

• create_membership - 將人員添加到房間
• list_memberships - 查看房間成員
• update_membership - 更改成員角色
• delete_membership - 刪除成員
• create_team_membership - 添加團隊成員
• list_team_memberships - 查看團隊成員

人員與目錄

• get_my_own_details - 獲取您的個人資料
• list_people - 搜索用戶
• get_person_details - 獲取用戶信息
• create_person - 添加新用戶（僅限管理員）
• update_person - 修改用戶詳細信息
• delete_person - 刪除用戶（僅限管理員）

Webhook 與事件

• create_webhook - 設置事件通知
• list_webhooks - 管理 Webhook
• get_webhook_details - 獲取 Webhook 信息
• update_webhook - 修改 Webhook
• delete_webhook - 刪除 Webhook
• list_events - 獲取活動日誌
• get_event_details - 獲取特定事件信息

企業功能

• create_room_tab - 向房間添加標籤
• list_room_tabs - 查看房間標籤
• get_room_tab_details - 獲取標籤信息
• update_room_tab - 修改標籤
• delete_room_tab - 刪除標籤
• create_attachment_action - 處理表單提交
• get_attachment_action_details - 獲取附件詳細信息
• list_ecm_folder - 企業內容管理
• get_ecm_folder_details - 獲取 ECM 文件夾詳細信息
• create_ecm_folder - 創建 ECM 配置
• update_ecm_linked_folder - 修改 ECM 文件夾
• unlink_ecm_linked_folder - 刪除 ECM 鏈接

傳輸模式

STDIO 模式（默認）

MCP 客戶端（如 Claude Desktop）的默認傳輸模式：

# 以 STDIO 模式啟動
node mcpServer.js
# 或者
npm start

HTTP 模式（StreamableHTTP）

基於 HTTP 的傳輸，支持 MCP 2025 - 06 - 18 協議：

# 以 HTTP 模式啟動
npm run start:http
# 或者
node mcpServer.js --http

HTTP 模式特性：

• 健康檢查：GET http://localhost:3001/health
• MCP 端點：POST http://localhost:3001/mcp
• 會話管理：自動處理會話 ID
• CORS 支持：正確的跨域配置
• 協議：MCP 2025 - 06 - 18 與 StreamableHTTP 傳輸

環境變量：

• MCP_MODE=http - 強制使用 HTTP 模式
• PORT=3001 - 自定義端口（默認：3001）

Smithery 集成

該服務器配置為通過 Smithery 進行自動部署，使用 HTTP 運行時：

# smithery.yaml
runtime: "nodejs"
main: "mcpServer.js"
envMapping:
  webexApiKey: "WEBEX_PUBLIC_WORKSPACE_API_KEY"
  webexApiBaseUrl: "WEBEX_API_BASE_URL"

使用 smithery deploy 進行部署。

開發

項目結構

├── lib/
│   ├── tools.js           # 工具發現和加載
│   └── webex-config.js    # 集中式 API 配置
├── tools/
│   └── webex-public-workspace/webex-messaging/
│       ├── create-a-message.js
│       ├── list-messages.js
│       └── ... (50 多個工具)
├── scripts/
│   └── update-webex-tools.js  # 自動工具更新
├── mcpServer.js           # 主 MCP 服務器
├── index.js              # CLI 接口
├── Dockerfile             # 容器配置
└── docker-compose.yml    # 多容器設置

添加新工具

1. 在 tools/webex-public-workspace/webex-messaging/ 中創建一個新的工具文件
2. 遵循現有工具的模式並進行正確的導入
3. 將工具路徑添加到 tools/paths.js
4. 使用 node index.js tools 進行測試

🔧 技術細節

安全

• 非根容器：以用戶 mcp（UID 1001）身份運行
• 多階段構建：優化生產鏡像
• 環境隔離：通過環境變量傳遞機密信息
• 健康檢查：支持容器監控

測試

🧪 全面測試套件

• 118 個單元測試，分佈在 53 個測試套件中
• 100% 通過率，覆蓋全面
• 50 多個 API 端點 進行端到端測試
• 20 多個關鍵 bug 修復 經過驗證

# 運行所有測試
npm test

# 運行並生成覆蓋率報告
npm run test:coverage

# 在本地運行測試（與 npm test 相同）
npm run test:local

# 驗證代碼質量和測試
npm run validate

🔒 預提交質量檢查

使用 Husky 預提交鉤子進行自動質量保證：

# 在 git commit 時自動運行：
🚀 Running pre-commit validation...
🔍 Checking code quality and running 118 unit tests...
✅ All validations passed! Commit proceeding...

驗證內容：

• JavaScript 語法檢查
• 118 個單元測試必須全部通過
• 代碼質量標準
• API 實現正確性

詳細測試文檔請參閱 tests/README.md。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

支持

• 問題反饋：通過 GitHub issues 報告 bug 和提出功能請求
• 文檔：請參閱 SETUP - COMPLETE.md 獲取詳細的設置說明
• 社區：加入 MCP 社區頻道參與討論