Claude Integration with MCP for Microsoft Graph API

Microsoft Graph API 向け Claude と MCP の連携

このリポジトリでは、Microsoft Graph API にアクセスするために、Claude と Model Context Protocol（MCP）サーバーを連携する完全なソリューションを提供します。

実装手順ガイド

フェーズ 1：MCP サーバーのセットアップ

1. このリポジトリをクローンします

   git clone https://github.com/JBAgent/Test1.git
   cd Test1
   

2. MCP サーバーの依存関係をインストールします

   cd mcp-server
   npm install
   

3. 環境変数を設定します

   cp .env.example .env
   # Edit .env with your Azure AD credentials
   

4. MCP サーバーを起動します

   npm start
   

5. MCP サーバーをテストします

   # Using the provided test client
   node test-client.js
   
   # Or using curl
   curl -X POST http://localhost:3000/api/graph \
     -H "Content-Type: application/json" \
     -H "X-User-ID: default-user" \
     -d '{"endpoint": "/users", "method": "GET", "queryParams": {"$top": 5}, "allData": false}'
   

フェーズ 2：Claude 連携のセットアップ

1. Claude アプリケーションの依存関係をインストールします

   cd ../claude-app
   npm install
   

2. 環境変数を設定します

   cp .env.example .env
   # Edit .env with your Anthropic API key and MCP server URL
   

3. Claude アプリケーションを起動します

   npm start
   

4. Claude との連携をテストします

   curl -X POST http://localhost:4000/api/chat \
     -H "Content-Type: application/json" \
     -d '{"messages": [{"role": "user", "content": "How many users are in our organization?"}]}'
   

フェーズ 3：連携のカスタマイズ

1. Graph API の関数を追加します

   • claude-mcp-integration.js を編集して、専用の関数を追加します
   • claude-app.js の関数定義を更新します

2. システムプロンプトをカスタマイズします

   • claude-app.js のシステムプロンプトを編集して、Claude の動作を調整します
   • より適切な回答が得られるよう、ドメイン固有のコンテキストを追加します

3. キャッシュを実装します（任意）

   • 一般的な Graph API の応答をキャッシュするために Redis を追加します
   • API 呼び出しを行う前にキャッシュを確認するよう、MCP サーバーを更新します

4. 監視とログ記録を追加します

   • すべての Graph API リクエストのログ記録を実装します
   • MCP サーバーと Claude アプリケーションの監視を設定します

プロジェクト構成

Test1/
├── mcp-server/               # MCP Server for Microsoft Graph API
│   ├── server.js             # Main server implementation
│   ├── test-client.js        # Test client for verification
│   ├── package.json          # Dependencies
│   ├── Dockerfile            # Container configuration
│   └── .env.example          # Example environment variables
│
├── claude-app/               # Claude Application
│   ├── claude-app.js         # Main application server
│   ├── claude-mcp-integration.js  # Integration module
│   ├── package.json          # Dependencies
│   └── .env.example          # Example environment variables
│
└── docs/                     # Documentation
    └── integration-guide.md  # Detailed integration guide

環境変数

MCP サーバー（.env）

AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
PORT=3000
NODE_ENV=development         # Set to 'production' in production

Claude アプリケーション（.env）

ANTHROPIC_API_KEY=your-anthropic-api-key
MCP_SERVER_URL=http://localhost:3000
MCP_USER_ID=default-user
PORT=4000

API エンドポイント

MCP サーバー

• POST /api/graph
  • Microsoft Graph API にリクエストを送信します
  • 認証には X-User-ID ヘッダーが必要です
  • 本文には Graph API リクエストのオプションを指定します

Claude アプリケーション

• POST /api/chat

  • Graph API を利用できる状態で Claude にメッセージを送信します
  • 本文にはメッセージ配列と任意のシステムプロンプトを指定します

• POST /api/analyze-organization

  • 組織分析に特化したエンドポイントです
  • 組織に関する質問を簡単に行えます

Graph API リクエストのオプション

MCP サーバーにリクエストを送信する際、次のオプションを含めることができます。

{
  "endpoint": "/users",          // Required: Graph API endpoint
  "method": "GET",               // Optional: HTTP method (default: GET)
  "version": "beta",             // Optional: API version (default: beta)
  "queryParams": {},             // Optional: Query parameters
  "body": {},                    // Optional: Request body for POST/PUT/PATCH
  "allData": false               // Optional: Auto-pagination (default: false)
}

consistencyLevel に関する重要な注意事項

テストの結果、consistencyLevel パラメーターは、多くの Graph API 構成で一般にサポートされていないことがわかりました。最大限の互換性を確保するため、すべてのデフォルトリクエストからこのパラメーターを削除しました。

特定の環境でこのパラメーターを使用する必要がある場合（高度なディレクトリクエリの一部のシナリオなど）、手動で queryParams に追加できます。

{
  "endpoint": "/users",
  "method": "GET",
  "queryParams": {
    "$top": 5,
    "consistencyLevel": "eventual"
  }
}

ただし、多くの環境でエラーが発生する可能性があるため、このパラメーターを使用する前に十分にテストすることをおすすめします。

JSON 形式の要件

MCP サーバーにリクエストを送信する際は、JSON が正しくフォーマットされていることを確認してください。

1. キーと文字列値には二重引用符を使用します：

   {"endpoint": "/users", "method": "GET"}
   

2. JSON 文字列を不適切にネストしないでください：

   {"queryParams": {"$filter": "displayName eq 'John'"}}
   

3. 適切な JSON 型を使用します：

   {"allData": true, "count": 10}
   

Microsoft Azure 認証情報の取得

AZURE_CLIENT_ID と AZURE_CLIENT_SECRET を取得するには、次の手順に従います。

1. Azure Portal にサインインします
2. Azure Active Directory > アプリの登録に移動します
3. 新しいアプリの登録を作成するか、既存のものを使用します
4. アプリケーション（クライアント）ID をコピーします。これが AZURE_CLIENT_ID です
5. 証明書とシークレット > 新しいクライアントシークレットに移動します
6. 新しいシークレットを作成し、その値をコピーします。これが AZURE_CLIENT_SECRET です
7. API のアクセス許可で、Microsoft Graph のアクセス許可を追加します

セキュリティに関する考慮事項

1. 認証

   • MCP サーバーでは、Graph API の認証に Azure AD を使用します
   • Claude アプリケーションでは、適切な認証を実装してください

2. 認可

   • MCP サーバーは、ユーザーコンテキストに基づいて権限を適用します
   • 機密性の高い操作には、ロールベースのアクセス制御を実装してください

3. データ保護

   • Claude と共有するデータに注意してください
   • データ保持ポリシーを実装してください

4. 監査ログ

   • コンプライアンスのため、すべての Graph API リクエストを記録してください
   • 通常と異なるアクセスパターンを監視してください

トラブルシューティング

1. MCP サーバーの接続に関する問題

   • Azure AD の認証情報を確認してください
   • ネットワーク接続を確認してください
   • 付属の test-client.js を使用して接続を確認してください

2. JSON の解析エラー

   • リクエストで二重引用符を使用した有効な JSON を指定してください
   • 単一引用符で囲んだ文字列や、適切にエスケープされていない文字を送信しないでください
   • 例については、test-client.js のリクエスト形式を確認してください

3. Graph API エラー

   • 「Unrecognized query argument: consistencyLevel」—このエラーは、Graph API の設定がこのパラメーターをサポートしていないことを示しています。すべての例とデフォルトの動作から、このパラメーターは削除されています。
   • Azure AD のアクセス許可を確認してください。アプリケーションに正しいスコープが付与されていることを確認してください
   • リクエストの形式とパラメーターを確認してください
   • レート制限に関する問題がないか確認してください

4. Claude API エラー

   • Anthropic API キーの有効性を確認してください
   • リクエストの形式が正しいことを確認してください

コントリビューション

コントリビューションを歓迎します。お気軽にプルリクエストを送信してください。