MCP Graph API Demo

MCP Graph API デモ

このプロジェクトでは、Azure テナントのアプリケーション登録を照会するために、Azure Graph API と Model Context Protocol（MCP）を使用する方法を紹介します。

このアプリケーションでは、MCP プロトコルを実装した ASP.NET Core サーバーと通信する Blazor WebAssembly クライアントを使用します。サーバーは Microsoft Graph API に接続してアプリケーション登録データを取得し、そのデータは AI アシスタント付きのチャットインターフェースを通じて処理、表示されます。

アーキテクチャの概要

+---------------------+                 +---------------------+
|     MCP Client      |                 |     MCP Server      |
|                     |                 |                     |
|  +---------------+  |    MCP API      |  +--------------+   |
|  |     LLM       |  |  Requests &     |  |   Graph API  |   |
|  | Integration   |<-+-->Functions     |  |   Functions  |<--+--> Microsoft Graph API
|  | (SK + OpenAI) |  |                 |  |              |   |
|  +---------------+  |                 |  +--------------+   |
|                     |                 |                     |
|  +---------------+  |                 |  +--------------+   |
|  |    UI/UX      |  |                 |  | Azure AD     |   |
|  |  (Blazor WASM)|  |                 |  | Integration  |<--+--> Azure Active Directory
|  +---------------+  |                 |  +--------------+   |
+---------------------+                 +---------------------+

Client handles:                        Server handles:
- User Interface                       - Function Definitions
- Prompt Engineering                   - Graph API Integration
- LLM Integration                      - Azure AD Authentication
- Function Orchestration               - Data Processing

このアーキテクチャは、以下の MCP の原則に厳密に従っています。

1. MCP クライアントが、すべての LLM とのやり取りとユーザーエクスペリエンスを担当します
2. MCP サーバーが、関数の定義を提供し、実際の Graph API 呼び出しを処理します
3. 標準化された MCP プロトコルを介して通信します

プロジェクト構成

• MCP.Client：MCP サーバーと連携する Blazor WebAssembly クライアント

  • ユーザーインターフェースとチャットエクスペリエンスを処理します
  • Azure OpenAI または OpenAI API と連携します
  • Semantic Kernel を使用して、LLM とのやり取りと関数呼び出しを調整します

• MCP.Server：Azure Graph API 向けに MCP プロトコルを実装する ASP.NET Core サーバー

  • Graph API の操作に関する関数定義を提供します
  • Azure AD による認証を処理します
  • クライアントから要求されたときに Graph API の呼び出しを実行します
  • 構造化データをクライアントに返します

• MCP.Shared：クライアントとサーバーで共有するモデルとインターフェース

  • MCP プロトコルの構造を定義します
  • 共有データモデルとインターフェースを含みます

Model Context Protocol（MCP）とは？

Model Context Protocol（MCP）は、LLM を活用するアプリケーションで、以下を分離するためのアーキテクチャパターンです。

1. LLM 連携（クライアント側）：ユーザーインターフェース、プロンプトエンジニアリング、LLM 呼び出し
2. ツール／関数連携（サーバー側）：LLM が使用できる機能

MCP により、責務が明確に分離されます。

• クライアントが、すべての LLM とのやり取りとユーザーエクスペリエンスを処理します
• サーバーは、関数定義の提供と、呼び出し時の実行に専念します
• この分離により、セキュリティ、モジュール性、スケーラビリティが向上します

このプロジェクトでは、以下の方法で MCP を実装しています。

1. サーバー上の関数として Graph API の機能を公開します
2. クライアントの LLM がこれらの関数を検出して呼び出せるようにします
3. LLM のキーをサーバーに公開せず、関数の実装詳細をクライアントに公開しません

前提条件

• .NET 9.0
• アプリケーション登録のアクセス許可がある Azure サブスクリプション
• Azure OpenAI リソースまたは OpenAI API キー

構成

アプリケーションを実行する前に、お使いの Azure 認証情報を設定する必要があります。

MCP サーバーの構成

MCP.Server/appsettings.json を編集し、以下の設定を更新します。

"AzureAd": {
  "Instance": "https://login.microsoftonline.com/",
  "TenantId": "<YOUR_TENANT_ID>",
  "ClientId": "<YOUR_CLIENT_ID>",
  "ClientSecret": "<YOUR_CLIENT_SECRET>",
  "Scopes": ["User.Read", "Application.Read.All"]
}

MCP クライアントの構成

MCP.Client/wwwroot/appsettings.json を編集し、以下の設定を更新します。

"AzureAd": {
  "Authority": "https://login.microsoftonline.com/<YOUR_TENANT_ID>",
  "ClientId": "<YOUR_CLIENT_ID>",
  "ValidateAuthority": true
},
"ApiBaseUrl": "http://localhost:5197",
"AzureOpenAI": {
  "Endpoint": "https://your-resource.openai.azure.com/",
  "ApiKey": "<YOUR_AZURE_OPENAI_API_KEY>",
  "DeploymentName": "gpt-35-turbo"
}

注：MCP サーバーは LLM と直接やり取りしないため、OpenAI の構成は不要になりました。LLM との連携はすべてクライアントが処理します。

セットアップ手順

1. 前提条件：

   • .NET 9.0 SDK をインストールします
   • アプリ登録を作成する権限がある Azure サブスクリプションを用意します
   • Azure OpenAI または OpenAI API にアクセスできるようにします

2. Azure AD にアプリケーションを登録する：

   • Azure Portal > Azure Active Directory > App registrations に移動します
   • 新しい登録を作成します
   • クライアントシークレットを設定します
   • 以下の API アクセス許可を付与します。
     • Microsoft Graph API > Application.Read.All
     • 管理者の同意を必ず付与してください
   • アクセス許可の詳細なトラブルシューティングについては、GraphApiPermissionFix.md を参照してください

3. Azure OpenAI を構成する：

   • Azure OpenAI リソースを作成するか、OpenAI を直接使用します
   • GPT モデル用のデプロイを作成します（例：gpt-35-turbo または gpt-4）
   • API キーとエンドポイントを取得します

4. 構成ファイルを更新する：

   • 上記の「構成」セクションの説明に従って、サーバーとクライアントの構成ファイルを更新します

アプリケーションの実行

1. MCP サーバーを起動します：

   cd MCP.Server
   dotnet run
   

2. MCP クライアントを起動します（新しいターミナルで）：

   cd MCP.Client
   dotnet run
   

3. ブラウザーを開き、次の URL にアクセスします：

   • http://localhost:5268（クライアント）
   • http://localhost:5197/swagger（サーバー API ドキュメント）

4. チャットインターフェイスで、Azure アプリの登録について質問します：

   • 「テナント内のすべてのアプリの登録を一覧表示してください」
   • 「ID が [app-id] のアプリの登録の詳細を取得してください」
   • 「[app-name] にはどのようなアクセス許可がありますか？」

MCP を使用した開発

このアプリケーションを新しい Graph API 機能で拡張するには：

1. MCP.Server/Services/McpGraphService.cs に新しい関数宣言を追加します
2. 同じファイルに関数のロジックを実装します
3. 新しい関数を処理するように ExecuteFunctionAsync メソッドを更新します
4. クライアントの LLM は、適切な場合に新しい関数を自動的に検出して使用します

関数宣言の例：

new McpFunctionDeclaration
{
    Name = "get_user_details",
    Description = "Get details for a specific user in the tenant",
    Parameters = new McpFunctionParameters
    {
        Type = "object",
        Properties = new Dictionary<string, McpParameterProperty>
        {
            ["user_id"] = new McpParameterProperty
            {
                Type = "string",
                Description = "The ID of the user"
            }
        },
        Required = new List<string> { "user_id" }
    }
}

GitHub への公開準備

このプロジェクトをパブリックな GitHub リポジトリにプッシュする前に：

1. 同梱のクリーニングスクリプトを実行して、設定ファイル内の情報を安全な状態にします：

   .\clean-for-github.ps1
   

2. 機密データが含まれていないことを確認します：

   • すべての appsettings.json ファイルでプレースホルダー（<YOUR_*>）を使用してください
   • 実際の API キーや認証情報を含めないでください
   • .bak ファイルや .private ファイルをコミットしないでください

3. 公開前のチェックリストについては、GITHUB-CHECKLIST.md ファイルを確認してください

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

• 実際の API キーやシークレットを GitHub にコミットしないでください
• MCP アーキテクチャでは LLM キーをクライアント側のみに保持することで、セキュリティを強化します
• サーバーが必要とするのは Graph API へのアクセスのみで、LLM サービスへのアクセスは不要です
• 本番環境へのデプロイでは、API キーを安全に保管するために Azure Key Vault を使用してください
• セキュリティのベストプラクティスについては、CONTRIBUTING.md を参照してください

ライセンス

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

• 「設定」セクションに従って設定ファイルを更新します

アプリケーションの実行

1. サーバーを起動します：

   cd MCP.Server
   dotnet run --launch-profile https
   

2. クライアントを起動します：

   cd MCP.Client
   dotnet run
   

3. アプリケーションにアクセスします： ブラウザーを開き、https://localhost:7030/chat にアクセスします

トラブルシューティング

アクセス許可に関する問題が発生した場合は、次の点を確認してください：

1. API のアクセス許可を確認する：アプリの登録に必要な Microsoft Graph のアクセス許可が設定され、管理者の同意が付与されていることを確認してください。

2. 認証を確認する：設定ファイル内の Azure AD 認証情報が正しいことを確認してください。

3. テストスクリプトを実行する：付属の PowerShell スクリプトを使用して、Graph API のアクセス許可をテストします：

   ./TestGraphPermissions.ps1
   

機能

• Azure テナントの情報を問い合わせるチャットインターフェイス
• MCP を介した Graph API 関数へのアクセス
• LLM 関数向けの Semantic Kernel 統合

GitHub への公開準備

このプロジェクトをパブリックリポジトリにプッシュする前に、クリーニングスクリプトを実行して機密情報を削除してください：

./clean-for-github.ps1

このスクリプトは次の処理を行います：

1. 不要なファイル（bin、obj フォルダー）を削除します
2. Azure ストレージエミュレーターのファイルを削除します
3. 機密データをプレースホルダーに置き換えて、設定ファイルを安全な状態にします
4. 元のファイルのバックアップを .private.bak 拡張子で作成します

貢献

このプロジェクトへの貢献を希望される場合は、行動規範とプルリクエストの提出手順について、貢献ガイドラインをお読みください。

ライセンス

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

謝辞

• Model Context Protocol (MCP) - AI モデルとのやり取りのためのフレームワークを提供
• Microsoft Graph API - Azure AD データへのアクセスを提供