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
   
   # 启动 MCP 服务器
   node mcpServer.js
   

Docker 使用方法

1. 构建并运行：

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

2. 使用 docker-compose：

   docker-compose up webex-mcp-server
   

✨ 主要特性

• ✅ 完整的 Webex API 覆盖：提供 52 种工具，涵盖所有主要的消息传递操作
• ✅ 支持 Docker：支持生产就绪的容器化部署
• ✅ 双传输模式：支持 STDIO 和 SSE（服务器发送事件）两种模式
• ✅ 企业级适配：支持思科企业认证
• ✅ 类型安全：完全使用 TypeScript/JavaScript 实现，并具备完善的错误处理机制
• ✅ 集中配置：便于进行令牌和端点管理

📦 安装指南

环境变量

获取 Webex API 令牌

1. 访问 developer.webex.com
2. 使用您的思科/Webex 账户登录
3. 从 API 文档中复制承载令牌
4. 重要提示：添加到 .env 文件时，去除 "Bearer " 前缀

💻 使用示例

MCP 客户端集成

Claude Desktop

将以下内容添加到您的 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"
                }
            },
  }
}

其他 MCP 客户端

STDIO 模式：

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

SSE 模式：

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

📚 详细文档

可用工具

核心消息传递

• 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 链接

开发

项目结构

├── 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 多个关键错误修复 经过验证

# 运行所有测试
npm test

# 运行带覆盖率的测试
npm run test:coverage

# 验证代码质量和测试
npm run validate

🔒 提交前质量检查

使用 Husky 提交前钩子进行自动质量保证：

# 在 git 提交时自动运行：
🚀 Running pre-commit validation...
🔍 Checking code quality and running 118 unit tests...
✅ All validations passed! Commit proceeding...

验证内容包括：

• JavaScript 语法检查
• 所有 118 个单元测试必须通过
• 代码质量标准
• API 实现正确性

详细测试文档请参阅 tests/README.md。

🤝 贡献指南

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 提交时自动运行测试，通过提交前钩子实现
5. 确保所有 118 个测试都通过
6. 提交拉取请求

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🛠️ 支持

• 问题反馈：通过 GitHub 问题报告错误和提出功能请求
• 文档参考：详细的设置说明请参阅 SETUP-COMPLETE.md
• 社区交流：加入 MCP 社区频道参与讨论