MCP Cisco Support

🚀 Cisco Support MCP Server

このサーバーは、CiscoサポートAPI用のプロダクションレディなTypeScript MCP（Model Context Protocol）サーバーです。包括的なセキュリティとデュアルトランスポートをサポートし、Bug Search、Case Management、End-of-Life情報など、複数のCiscoサポートAPIにアクセスできます。

🚀 クイックスタート

NPXインストール（推奨）

Claude Desktop用のstdioモードで起動:

npx mcp-cisco-support

認証付きでHTTPサーバーを起動:

npx mcp-cisco-support --http
# 認証用のトークンがコンソールに表示されます

HTTPモード用のBearerトークンを生成:

npx mcp-cisco-support --generate-token

ヘルプを表示し、すべてのオプションを確認:

npx mcp-cisco-support --help

環境設定

1. 認証トークンを生成（HTTPモード用）:

   npx mcp-cisco-support --generate-token
   export MCP_BEARER_TOKEN=<generated_token>
   

2. Cisco APIの資格情報を設定:

   export CISCO_CLIENT_ID=your_client_id_here
   export CISCO_CLIENT_SECRET=your_client_secret_here
   export SUPPORT_API=bug,case,eox,psirt,product,software  # すべての実装済みAPI（推奨）
   

3. サーバーを起動:

   # Claude Desktop用（stdioモード）
   npx mcp-cisco-support
   
   # HTTPアクセス用（認証付き）
   npx mcp-cisco-support --http
   

ローカル開発

git clone https://github.com/sieteunoseis/mcp-cisco-support.git
cd mcp-cisco-support
npm install
npm run build
npm start

✨ 主な機能

• 複数APIサポート: 6つのCiscoサポートAPIが完全に実装されています（合計33のツール）
• Bearerトークン認証: HTTPエンドポイントに対するMCP Inspectorスタイルのセキュリティ
• APIアクセスの設定可能: アクセス権のあるCiscoサポートAPIのみを有効にできます
• 専用のプロンプト: 9つのワークフロープロンプトで、Ciscoサポートシナリオをガイドします
• デュアルトランスポート: stdio（ローカルMCPクライアント）とHTTP（認証付きのリモートサーバー）
• OAuth2認証: Cisco APIとの自動トークン管理
• リアルタイム更新: HTTPモードでのServer-Sent Events
• TypeScript: 完全な型安全性とMCP SDKの統合
• プロダクションセキュリティ: Helmet、CORS、入力検証、Bearerトークン
• Dockerサポート: ヘルスチェック付きのコンテナ化されたデプロイメント
• 包括的なロギング: タイムスタンプ付きの構造化ロギング

📦 インストール

代替インストール方法

グローバルインストール

npxを使用せずにグローバルにインストールする場合は、以下のコマンドを実行します。

npm install -g mcp-cisco-support

その後、以下の設定を使用します。

{
  "mcpServers": {
    "cisco-support": {
      "command": "mcp-cisco-support",
      "env": {
        "CISCO_CLIENT_ID": "your_client_id_here",
        "CISCO_CLIENT_SECRET": "your_client_secret_here",
        "SUPPORT_API": "bug"
      }
    }
  }
}

ローカルインストール

開発またはカスタム設定用にローカルインストールする場合は、以下のコマンドを実行します。

git clone https://github.com/sieteunoseis/mcp-cisco-support.git
cd mcp-cisco-support
npm install
npm run build

その後、以下の設定を使用します。

{
  "mcpServers": {
    "cisco-support": {
      "command": "node",
      "args": ["/path/to/mcp-cisco-support/dist/index.js"],
      "env": {
        "CISCO_CLIENT_ID": "your_client_id_here",
        "CISCO_CLIENT_SECRET": "your_client_secret_here",
        "SUPPORT_API": "bug"
      }
    }
  }
}

Dockerデプロイメント

# 事前構築済みのイメージを使用
docker pull ghcr.io/sieteunoseis/mcp-cisco-support:latest
docker run -p 3000:3000 \
  -e CISCO_CLIENT_ID=your_id \
  -e CISCO_CLIENT_SECRET=your_secret \
  -e SUPPORT_API=bug \
  ghcr.io/sieteunoseis/mcp-cisco-support:latest --http

# またはローカルでビルド
docker-compose up -d

📊 サポートされるCisco API

サーバーは、以下のCiscoサポートAPIをサポートしています（SUPPORT_API環境変数で設定可能）。

実装ステータス: 8つのAPIのうち6つが完了（75%）、合計33のツール

設定例:

• SUPPORT_API=enhanced_analysis - 拡張分析ツールのみ（6つのツール） ← ほとんどのユーザーに推奨
• SUPPORT_API=bug - 拡張分析を含むすべてのBug APIツール（14つのツール）
• SUPPORT_API=bug,case,eox,psirt - コアサポートAPI（28つのツール）
• SUPPORT_API=bug,case,eox,psirt,product,software - すべての実装済みAPI（39つのツール）
• SUPPORT_API=all - すべての利用可能なAPI（2つのプレースホルダーAPIを含む）

💻 使用例

cURLの使用例

# サーバーの接続性をテスト
curl http://localhost:3000/ping

# ヘルスステータスを確認
curl http://localhost:3000/health

# 利用可能なツールをリストする（主なMCPエンドポイント）
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/list"
  }'

# 利用可能なツールをリストする（N8N用の代替エンドポイント）
curl -X POST http://localhost:3000/messages \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/list"
  }'

# SSE接続をテストする（エンドポイントイベントが表示されます）
curl -N http://localhost:3000/sse

# キーワードでバグを検索
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/call",
    "params": {
      "name": "search_bugs_by_keyword",
      "arguments": {
        "keyword": "crash",
        "severity": "1",
        "status": "open"
      }
    }
  }'

# 特定のバグの詳細を取得
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "tools/call",
    "params": {
      "name": "get_bug_details",
      "arguments": {
        "bug_ids": "CSCab12345"
      }
    }
  }'

JavaScriptクライアントの使用例

async function searchBugs(keyword) {
  const response = await fetch('http://localhost:3000/mcp', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: Date.now(),
      method: 'tools/call',
      params: {
        name: 'search_bugs_by_keyword',
        arguments: {
          keyword: keyword,
          page_index: 1,
          status: 'open'
        }
      }
    })
  });
  
  const result = await response.json();
  return result;
}

📚 ドキュメント

詳細情報については、包括的なGitHub Wikiを参照してください。

• 📋 利用可能なツール - 6つのAPIをまたがるすべての33のMCPツールの完全なリファレンス
• 🔧 高度な設定 - 環境変数とデプロイメントオプション
• 🔒 セキュリティガイド - 認証、トークン、およびセキュリティのベストプラクティス
• 🚀 Dockerデプロイメント - コンテナ化されたデプロイメントと本番環境のセットアップ
• 🌐 SSE統合 - Server-Sent Eventsとリアルタイム通信
• 🧪 テストフレームワーク - 包括的なテストと検証
• 🔧 開発ガイド - コントリビュート、アーキテクチャ、およびAPI開発
• 🚨 トラブルシューティングガイド - 一般的な問題とデバッグ
• ⚡ MCPプロンプト - Ciscoサポートシナリオのガイド付きワークフロー

Claude Desktopとの統合

前提条件

1. Cisco APIの資格情報を取得:

   • Cisco API Consoleにアクセスします。
   • アプリケーションを作成し、Client IDとSecretを取得します。
   • アプリケーションがBug APIにアクセスできることを確認します。

2. Claude Desktopをインストール:

   • Claude.aiからダウンロードします。
   • MCPをサポートする最新バージョンを使用していることを確認します。

手順

1. Claude Desktopの設定ファイルを見つける:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 設定ファイルを作成または編集する:

   {
     "mcpServers": {
       "cisco-support": {
         "command": "npx",
         "args": ["mcp-cisco-support"],
         "env": {
           "CISCO_CLIENT_ID": "your_client_id_here",
           "CISCO_CLIENT_SECRET": "your_client_secret_here",
           "SUPPORT_API": "bug"
         }
       }
     }
   }
   

   オプション: SUPPORT_APIで有効にするAPIを設定します。

   • "enhanced_analysis" - 拡張分析ツールのみ（ほとんどのユーザーに推奨）
   • "bug" - Bug APIのみ（デフォルト）
   • "all" - すべての利用可能なAPI
   • "bug,case,eox" - 複数の特定のAPI

3. 資格情報を置き換える:

   • your_client_id_hereを実際のCisco Client IDに置き換えます。
   • your_client_secret_hereを実際のCisco Client Secretに置き換えます。

4. Claude Desktopを再起動する:

   • Claude Desktopを完全に閉じます。
   • アプリケーションを再開します。
   • MCPサーバーが自動的に読み込まれます。

検証

設定後、以下のことができるはずです。

1. ClaudeにCiscoのバグについて尋ねる:

   "Search for bugs related to memory leaks in Cisco switches"
   

2. 特定のバグの詳細を取得する:

   "Get details for Cisco bug CSCab12345"
   

3. 製品で検索する:

   "Find bugs affecting Cisco Catalyst 3560 switches"
   

Claude Desktopでの使用例

設定後、Claudeに以下のような質問をすることができます。

• 基本的なバグ検索:

  • "Search for recent bugs related to 'crash' in Cisco products"
  • "Find open bugs with severity 1 or 2"
  • "Show me bugs modified in the last 30 days"

• 製品固有の検索:

  • "Find bugs for product ID C9200-24P"
  • "Search for bugs in Cisco Catalyst 9200 Series affecting release 17.5.1"
  • "Show bugs fixed in software release 17.5.2"

• バグの詳細:

  • "Get full details for bug CSCab12345"
  • "Show me information about bugs CSCab12345,CSCcd67890"

• 高度なフィルタリング:

  • "Find resolved bugs with severity 3 modified after 2023-01-01"
  • "Search for bugs in 'Cisco ASR 9000 Series' sorted by severity"
  • "Can you show me all the cisco bugs in the last 30 days for the product Cisco Unified Communications Manager (CallManager)?" (キーワード検索を使用)
  • "Find bugs for Cisco Unified Communications Manager affecting releases 14.0 and 15.0" (製品シリーズ検索を使用)

Claudeは、適切なMCPツールを使用してCiscoのBug APIからリアルタイムデータを取得し、最新の情報を含む包括的な応答を提供します。

MCPプロンプト

サーバーには、Ciscoサポートのワークフローをガイドする5つの専用プロンプトが含まれています。

• 🚨 cisco-incident-investigation - 症状とエラーを調査する
• 🔄 cisco-upgrade-planning - アップグレード前の問題を調査する
• 🔧 cisco-maintenance-prep - メンテナンスウィンドウの準備をする
• 🔒 cisco-security-advisory - セキュリティの脆弱性を調査する
• ⚠️ cisco-known-issues - ソフトウェアリリースの問題を確認する

各プロンプトは、構造化された調査計画と専門家の推奨事項を提供します。

完全なプロンプトのドキュメントと使用例については、⚡ MCP Prompts を参照してください。

スクリーンショット

Claude Desktopとの統合

Claude DesktopがCisco Support MCPサーバーに正常に接続され、CiscoのBug APIからのリアルタイム応答を伴うバグ検索機能を示しています。

MCP Inspector

MCP Inspector v0.14.0+が利用可能なツールとサーバーの接続性テスト機能を表示しています。

ヘルスモニタリング

サーバーは包括的なヘルスチェックエンドポイントを提供します。

curl http://localhost:3000/health

レスポンスには以下が含まれます。

• サーバーのステータス
• OAuth2トークンのステータス
• メモリ使用量
• 稼働時間
• アクティブなSSE接続

セキュリティ機能

• Helmet: セキュリティヘッダー
• CORS: クロスオリジンリソース共有
• 入力検証: スキーマベースの検証
• 非ルート実行: Dockerセキュリティ
• 環境変数: 安全な資格情報の保存

トラブルシューティング

一般的な問題

1. OAuth2認証に失敗しました

   • CISCO_CLIENT_IDとCISCO_CLIENT_SECRETを確認してください。
   • https://id.cisco.comへのネットワーク接続性を確認してください。

2. API呼び出しが失敗しました

   • /healthでトークンの有効性を確認してください。
   • https://apix.cisco.comへのネットワークアクセスを確認してください。

3. Dockerの問題

   • 環境変数が設定されていることを確認してください。
   • Dockerのログを確認してください: docker-compose logs

ログ

構造化されたJSONログには以下が含まれます。

• タイムスタンプ
• ログレベル（info、error、warn）
• メッセージ
• 追加のコンテキストデータ

テスト

テストの実行

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

# ウォッチモードでテストを実行
npm run test:watch

# カバレッジ付きでテストを実行
npm run test:coverage

# 特定のテストスイートを実行
npx jest tests/auth.test.js
npx jest tests/mcp-tools.test.js

テスト構造

テストスイートには以下が含まれます。

• 認証テスト (tests/auth.test.js): OAuth2認証、トークン管理、エラーハンドリング
• MCPツールテスト (tests/mcp-tools.test.js): すべての8つのMCPツール、エラーハンドリング、ページネーション
• セットアップ (tests/setup.js): テスト環境の設定

最近のテスト修正

テストスイートで以下の問題が特定され、解決されました。

✅ 修正された問題

1. トークンリフレッシュロジック

   • 問題: getValidToken()でのトークン有効期限の計算が正しくなかった。
   • 解決策: トークンがリフレッシュマージン内にあるかどうかを適切にチェックする条件を修正した。
   • 影響: 適切なトークンキャッシュとリフレッシュ動作。

2. 複数のバグIDの処理

   • 問題: テスト間の状態漏れにより、モックシーケンスが不一致になった。
   • 解決策: resetServerState()関数を実装して適切なクリーンアップを行った。
   • 影響: 複数の実行にわたって一貫したテスト結果。

3. 検索ツールの実装

   • 問題: 同じ状態管理の問題がキーワード検索や他のツールに影響を与えていた。
   • 解決策: テスト間でサーバーの状態を適切にリセットした。
   • 影響: すべての8つのMCPツールが正しく動作するようになった。

4. エラーハンドリング

   • 問題: APIエラーやネットワークタイムアウトがMCPエラー応答に適切に変換されていなかった。
   • 解決策: handleMCPMessage()関数でエラーハンドリングを強化した。
   • 影響: クライアントアプリケーションに適切なエラー応答を提供する。

5. 認証失敗シナリオ

   • 問題: 認証失敗時にヘルスエンドポイントが200ではなく503を返していた。
   • 解決策: モジュールキャッシュをクリアし、適切な状態分離を行った。
   • 影響: 正しいヘルスステータスの報告。

6. テスト状態管理

   • 問題: モジュールレベルの変数がテスト間で保持されていた。
   • 解決策: resetServerState()をエクスポートし、モジュールキャッシュを適切にクリアした。
   • 影響: 真のテスト分離と信頼性の高いテスト結果。

テスト設定

• Jest: メインのテスト実行に--forceExitフラグを使用したJestを使用しています。
• 状態リセット: 各テストはクリーンな状態の新しいサーバーインスタンスを取得します。
• モック管理: 正しいシーケンス処理で適切なフェッチモックを使用しています。
• テスト分離: モジュールキャッシュのクリアにより状態漏れを防止しています。

主要な実装詳細

• ネイティブフェッチ: 外部ライブラリではなくNode.jsのネイティブフェッチを使用しています。
• トークン管理: 12時間のトークン有効期限と30分のリフレッシュマージン。
• エラーハンドリング: 適切なMCPエラー応答を伴う包括的なエラーハンドリング。
• セキュリティ: Helmetセキュリティヘッダー、CORSサポート、入力検証。
• ロギング: タイムスタンプ付きの構造化JSONロギング。

開発

プロジェクト構造

mcp-cisco-support/
├── src/
│   └── index.ts        # メインのTypeScriptサーバー実装
├── dist/               # コンパイルされたJavaScript（ビルドによって生成されます）
├── package.json        # 依存関係とスクリプト
├── tsconfig.json       # TypeScriptの設定
├── .env.example       # 環境変数のテンプレート
├── .env               # 実際の環境変数（例から作成）
├── .gitignore         # Gitの無視ルール
├── Dockerfile         # Dockerの設定
├── docker-compose.yml # Docker Composeのセットアップ
├── screenshots/        # ドキュメント用のスクリーンショット
│   └── mcp-inspector-screenshot.png
├── CLAUDE.md          # プロジェクトの説明とアーキテクチャ
└── README.md          # プロジェクトのドキュメント

開発コマンド

# 依存関係をインストール
npm install

# 自動リロード付きで開発サーバーを起動
npm run dev

# テストを実行
npm test

# ウォッチモードでテストを実行
npm run test:watch

# Dockerイメージをビルド
docker build -t mcp-cisco-support .

# 開発中のログを表示
npm run dev 2>&1 | jq '.'  # JSONログを整形して表示

パフォーマンスに関する考慮事項

• トークンキャッシュによりAPI呼び出しが減少します。
• ページネーションにより、ページごとの結果が10件に制限されます。
• SSEハートビートが30秒ごとに送信され、接続が維持されます。
• リクエストタイムアウトが30秒に設定されています。

セキュリティに関する注意事項

• .envファイルをバージョン管理にコミットしないでください。
• すべてのシークレットに環境変数を使用してください。
• Cisco APIの使用制限と利用規約を確認してください。
• ログを監視して、疑わしい活動を検出してください。

APIリファレンス

認証

• OAuth2 URL: https://id.cisco.com/oauth2/default/v1/token
• グラントタイプ: client_credentials
• トークンの有効期限: 12時間
• 自動リフレッシュ: 有効期限の30分前

Bug APIのベースURL

• ベースURL: https://apix.cisco.com/bug/v2.0

MCPプロトコル

サーバーは、以下のメソッドを持つModel Context Protocolを実装しています。

• initialize: MCP接続を初期化する
• tools/list: 利用可能なツールをリストする
• tools/call: ツールを実行する

MCPメッセージの例:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "search_bugs_by_keyword",
    "arguments": {
      "keyword": "memory leak",
      "status": "open"
    }
  }
}

ヘルスモニタリング

サーバーは包括的なヘルスチェックエンドポイントを提供します。

curl http://localhost:3000/health

レスポンスには、サーバーのステータス、OAuth2トークンのステータス、メモリ使用量、稼働時間、およびアクティブな接続が含まれます。

テスト

包括的なJestベースのテストフレームワークがあり、以下のことができます。

• ✅ 33/33のツールがテスト済み - 6つのAPIをまたがるすべてのMCPツール
• ✅ モックと実際のAPIのテスト - モックを使用した単体テスト + ライブAPIを使用した統合テスト
• ✅ 個々のツールのテスト - 開発用の独立したテストランナー

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

# 実際のAPI資格情報でテストを実行
CISCO_CLIENT_ID=your_id CISCO_CLIENT_SECRET=your_secret npm test

# 個々のツールをテスト
npm run test:tool search_bugs_by_keyword

完全なテストドキュメントについては、🧪 テストフレームワーク を参照してください。

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細については、LICENSEファイルを参照してください。

コントリビュート

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更を加えます。
4. 新しい機能に対するテストを追加します。
5. すべてのテストが通過することを確認します: npm test
6. プルリクエストを送信します。

サポート

リソース

• 📖 完全なドキュメント - 包括的なプロジェクトドキュメント
• 📚 Wiki - 詳細なガイドとトラブルシューティング
• 🐛 問題 - バグの報告と機能のリクエスト

外部リソース

• 🔧 Cisco Developer Documentation - 公式APIドキュメント
• 🔒 Cisco PSIRT Documentation - セキュリティ脆弱性APIのドキュメント
• 💬 Cisco Services Discussions - コミュニティサポートとAPIの議論
• 🌐 MCP Protocol - Model Context Protocolの仕様