JinDaGe - webex-messaging-mcp-server MCP Details

article

README

🚀 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 小时后过期。要更新令牌，请按以下步骤操作：

访问：https://developer.webex.com/messaging/docs/api/v1/rooms/list-rooms
使用您的电子邮件登录
从您的个人资料中复制新的承载令牌
使用新令牌更新环境变量 "WEBEX_PUBLIC_WORKSPACE_API_KEY"（去除 "Bearer " 前缀）

安装

克隆并安装依赖项：

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

配置环境：

cp .env.example .env
# 使用您的 Webex API 令牌编辑 .env

测试服务器：

# 列出可用工具
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_PUBLIC_WORKSPACE_API_KEY | 必需。Webex API 令牌（去除 "Bearer " 前缀） | | WEBEX_API_BASE_URL | 可选。Webex API 基础 URL，默认为 https://webexapis.com/v1 | | WEBEX_USER_EMAIL | 可选。您的 Webex 电子邮件（仅供参考） | | PORT | 可选。HTTP 模式的端口，默认为 3001 | | MCP_MODE | 可选。传输模式（stdio 或 http），默认为 stdio |

获取 Webex API 令牌

访问 developer.webex.com
使用您的思科/Webex 账户登录
从 API 文档中复制承载令牌
重要提示：添加到 .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    # 多容器设置

添加新工具

在 tools/webex-public-workspace/webex-messaging/ 中创建一个新的工具文件
遵循现有工具的模式并进行正确的导入
将工具路径添加到 tools/paths.js
使用 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 社区频道参与讨论