Webex Messaging MCP Server

🚀 Webex MCP Server

このModel Context Protocol (MCP)サーバーは、AIアシスタントにCisco Webexメッセージング機能への包括的なアクセスを提供します。

🚀 クイックスタート

前提条件

• Node.js 18以上（20以上が推奨）。注意：Nodeのバージョンが低いとfetchが使えません。ツールはHTTP呼び出しにfetchを使用しています。この問題を回避するには、ツールをnode-fetchを使うように変更できます。node-fetchを依存関係としてインストールし、各ツールファイルでfetchとしてインポートしてください。
• Docker（コンテナ化デプロイ用、オプション）
• developer.webex.comから取得したWebex APIトークン

トークンの更新

Webexのベアラートークンは短期間で有効期限が切れます。現在のトークンは12時間で期限切れになります。更新するには以下の手順を実行します：

1. 次のURLにアクセス：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
   # .envファイルを編集してWebex APIトークンを設定
   

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)の両方のモード
• ✅ エンタープライズ対応：Ciscoエンタープライズ認証をサポート
• ✅ 型安全：適切なエラーハンドリングを備えた完全なTypeScript/JavaScript実装
• ✅ 集中管理構成：トークンとエンドポイントの管理が容易

📚 ドキュメント

概要

このMCPサーバーは、AIアシスタントが52の異なるツールを通じてWebexメッセージングとやり取りできるようにします。これらのツールは以下の領域をカバーしています：

• メッセージ：メッセージの送信、編集、削除、取得
• ルーム：Webexスペースの作成と管理
• チーム：チームの作成とメンバーシップ管理
• ユーザー：ユーザー管理とディレクトリ操作
• Webhook：イベント通知と統合
• エンタープライズ機能：ECMフォルダ、ルームタブ、添付ファイル

🔍 ツールの探索

サーバーには包括的なツール探索機能が備わっています：

ツール探索コマンド

# 人間が読みやすい形式でツールを分析
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

ツールマニフェスト

tools-manifest.jsonファイルには以下の情報が含まれています：

• ツールカテゴリ：メッセージ、ルーム、チーム、メンバーシップ、ユーザー、Webhook、エンタープライズ
• 合計52のツール：完全なWebexメッセージングAPIをカバー
• 環境構成：必須およびオプションの変数
• テスト情報：カバレッジと検証の詳細
• 移行履歴：MCPプロトコルのアップグレードドキュメント

ツールの組織化

ツールは機能別に組織化されています：

• メッセージ（6つのツール）：メッセージの作成、リスト表示、編集、削除
• ルーム（6つのツール）：ルームの管理と設定
• チーム（5つのツール）：チームの作成と管理
• メンバーシップ（10つのツール）：ルームとチームのメンバーシップ操作
• ユーザー（6つのツール）：ユーザープロファイルとディレクトリ管理
• Webhook（7つのツール）：イベント通知とWebhook管理
• エンタープライズ（12つのツール）：ECMフォルダ、ルームタブ、添付ファイル

利用可能なツール

コアメッセージング

• 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モード（デフォルト）

Claude DesktopのようなMCPクライアントのデフォルトのトランスポートモードです：

# STDIOモードで起動
node mcpServer.js
# または
npm start

HTTPモード（StreamableHTTP）

MCP 2025-06-18プロトコルをサポートするHTTPベースのトランスポートです：

# 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でデプロイします。

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トランスポートをサポートしており、以下を含みます：

• mcp-session-idヘッダーの公開を伴う適切なCORS構成
• ステートフル接続のためのセッション管理
• サーバー送信イベント（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

開発

プロジェクト構造

├── 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）として実行
• マルチステージビルド：最適化された本番用イメージ
• 環境分離：シークレットは環境変数を介して渡される
• ヘルスチェック：コンテナ監視をサポート

テスト

🧪 包括的なテストスイート

• 53のテストスイートにわたる118の単体テスト
• 包括的なカバレッジで100%の合格率
• エンドツーエンドでテストされた50以上のAPIエンドポイント
• 検証された20以上の重大なバグ修正

# すべてのテストを実行
npm test

# カバレッジを伴って実行
npm run test:coverage

# ローカルでテストを実行（npm testと同じ）
npm run test:local

# コード品質とテストを検証
npm run validate

🔒 コミット前の品質ゲート

Huskyのコミット前フックを使用した自動品質保証：

# git commit時に自動的に実行されます：
🚀 コミット前の検証を実行中...
🔍 コード品質をチェックし、118の単体テストを実行中...
✅ すべての検証が通過しました！コミットを続行します...

検証内容：

• JavaScript構文チェック
• すべての118の単体テストが合格すること
• コード品質基準
• API実装の正しさ

詳細なテストドキュメントはtests/README.mdを参照してください。

コントリビュート

1. リポジトリをフォーク
2. 機能ブランチを作成
3. 変更を加える
4. コミット時に自動的にテストが実行されます（コミット前フックによる）
5. すべての118のテストが合格することを確認
6. プルリクエストを送信

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

サポート

• 問題報告：GitHubのイシューを通じてバグや機能リクエストを報告してください。
• ドキュメント：詳細なセットアップ手順はSETUP-COMPLETE.mdを参照してください。
• コミュニティ：MCPコミュニティチャンネルで議論に参加してください。