MCP Plexus

🚀 MCP Plexus: 最新AI向けのセキュアなマルチテナントMCPサーバーフレームワーク

強力で拡張性が高く、セキュアなモデルコンテキストプロトコル（MCP）アプリケーションを簡単に構築できます。MCP Plexusは、堅牢なjlowin/fastmcp（FastMCP 2.7）ライブラリを基に構築されたPythonフレームワークで、開発者がOAuth 2.1を介して外部サービスとシームレスに統合し、ツールのAPIキーアクセスを管理するマルチテナントMCPサーバーを展開できるように設計されています。

🚀 クイックスタート

前提条件

• Python 3.10以上
• Redis（現在、MCPセッション管理に必要）
• コマンドライン/ターミナルへのアクセス

インストール / セットアップ

1. リポジトリをクローンする：

   git clone https://github.com/Super-I-Tech/mcp_plexus mcp-plexus
   cd mcp-plexus
   

2. 仮想環境を作成してアクティブ化する：

   python -m venv venv
   

   Windowsの場合

   .\venv\Scripts\activate
   

   macOS/Linuxの場合

   source venv/bin/activate
   

3. 依存関係をインストールする：

   pip install -r requirements.txt
   

4. 環境変数を設定する（.envファイル）： プロジェクトルート（mcp-plexus/.env）に.envファイルを作成します。提供されている場合は.env.exampleからコピーするか、手動で作成します。

   重要な変数：

   • HOST_APP_REGISTRATION_SECRET：必須。ホストアプリケーションがPlexusにユーザーを登録するために提供する必要がある強力で一意のシークレットです（X-Host-App-Secretヘッダーを介して）。本番環境または共有デプロイでは、デフォルトで生成された値を変更してください。
   • PLEXUS_ENCRYPTION_KEY：必須。データベースに保存されるAPIキーや外部OAuthトークンなどの機密データを暗号化するために使用されるFernet暗号化キーです。以下のコマンドで生成します：

     python -c "from mcp_plexus.utils import generate_fernet_key; print(generate_fernet_key())"
     

     出力を.envに配置します。このキーは秘密にしてバックアップしてください。キーを失うと、暗号化されたデータへのアクセスが失われます。
   • STORAGE_BACKEND：ほとんどの永続的なストア（例：Plexusユーザー認証トークン、外部OAuthプロバイダー設定）に対して、"sqlite"（デフォルト）または"redis"に設定します。
     • 重要：MCPセッション管理は現在Redisが必須であり、この設定に関係なくRedisPlexusSessionStoreを使用します。将来のアップデートでSQLiteによるセッションストレージが有効になる可能性があります。
   • SQLITE_DB_PATH：SQLiteデータベースファイルへのパス（例：./mcp_plexus_data.sqlite3）。
   • REDIS_HOST, REDIS_PORT, REDIS_DB, REDIS_PASSWORD（オプション）, REDIS_SSL（オプション）：Redisインスタンスの接続詳細（MCPセッションに必須；STORAGE_BACKEND=redisの場合、他のデータにも使用されます）。
   • DEBUG_MODE：開発用にTrueに設定します（より詳細なログ、Uvicornのリロード）。
   • PLEXUS_FASTMCP_LOG_LEVEL：FastMCPコンポーネントのログレベル（例：DEBUG, INFO）。
   • ADMIN_API_KEY：管理エンドポイントにアクセスするための秘密のAPIキー（例：テナントの管理、外部OAuthプロバイダーの管理）。強力な値を設定してください。

   .envの例：

    # Uvicorn開発サーバー
    DEV_SERVER_HOST=127.0.0.1
    DEV_SERVER_PORT=8000
    DEV_SERVER_LOG_LEVEL=info
    DEV_SERVER_RELOAD=True
   
    # アプリケーション設定
    APP_NAME=MCP Plexus Server
    DEBUG_MODE=True
   
    REDIS_HOST=localhost
    REDIS_PORT=6379
    REDIS_DB=0
    # REDIS_PASSWORD=
    # REDIS_SSL=False
   
    PLEXUS_FASTMCP_LOG_LEVEL="DEBUG"
   
    STORAGE_BACKEND=sqlite
    SQLITE_DB_PATH=./mcp_plexus_data.sqlite3
   
    HOST_APP_REGISTRATION_SECRET=host_app_secre
   
    ADMIN_API_KEY=your_super_secret_admin_api_key_here_12345
   
    PLEXUS_CLI_API_BASE_URL=http://127.0.0.1:8080
   
    PLEXUS_ENCRYPTION_KEY=your_generated_fernet_key_here # see mcp_plexus/utils/generate_key.py
   

5. データベースを初期化する（SQLiteを使用する場合）： SQLiteデータベースとテーブルは、存在しない場合は通常、初回実行時に自動的に作成されます。

サーバーを起動する（開発用）

run_dev.pyスクリプトを使用します：

python run_dev.py

これにより、通常はhttp://127.0.0.1:8000でUvicornサーバーが起動します（ホスト/ポートは.envのDEV_SERVER_HOST/DEV_SERVER_PORTで構成できます）。

✨ 主な機能

• マルチテナンシー：

  • URLパス（例：/{entity_id}/mcp/）を介して識別される複数の分離されたテナントをサポートします。
  • テナント固有のMCPセッション管理（現在はデフォルトでRedisを使用）。
  • （計画中）ツールの可視性とプロバイダー設定のテナント固有の構成。

• Plexusユーザー認証：

  • ホストアプリケーションは、セキュアなエンドポイント（/{entity_id}/plexus-auth/register-user）を介してユーザーをMCP Plexusに登録できます。
  • plexus_user_auth_tokenを取得して、ホストアプリケーションのユーザーをPlexus内の永続的なIDにリンクします。
  • 外部OAuthトークンとAPIキーをユーザーにスコープされた状態で永続的に保存できます。

• ツールの外部OAuth 2.1フローの支援：

  • MCPツールの@requires_auth(provider_name, scopes)デコレーターは、外部プロバイダー（例：GitHub）に対するOAuth 2.1 Authorization Code Grant with PKCEフローをトリガーします。
  • OAuthコールバック、トークン交換、およびセキュアなトークン保存を管理します（ゲストユーザーの場合はセッションバインド、認証されたPlexusユーザーの場合はpersistent_user_idに対して永続的に保存）。
  • ツールは、PlexusContextを介して認証されたhttpx.AsyncClientを受け取り、外部プロバイダーとやり取りできます。
  • 外部OAuthプロバイダーのテナント固有の構成を管理するための管理CLI/API（例：GitHubのクライアントID/シークレット）。

• ツールのAPIキー管理：

  • MCPツールの@requires_api_key(provider_name, key_name_display, instructions)デコレーター。
  • 保存されていない場合、ユーザーにAPIキーを提出するよう促します（構造化されたMCPエラーを介して）。
  • APIキーを安全に保存し（PLEXUS_ENCRYPTION_KEYを使用して保存時に暗号化）、persistent_user_idに対して永続的に保存します。
  • 実行時に復号化されたAPIキーをツール関数に注入します。
  • ユーザーがAPIキーを提出するためのエンドポイント（/{entity_id}/plexus-services/api-keys）。

• 標準MCPサーバー機能（FastMCP 2.7経由）：

  • FastMCPのPythonicデコレーターとクラスを使用して、MCPツール、リソース、およびプロンプトを定義する完全なサポート（例：PLEXUS_SERVER_INSTANCE.tool()）。
  • MCP通信のためのネイティブStreamable HTTPトランスポート。
  • ツール/リソース/プロンプト内でPlexusContext（fastmcp.Contextを拡張）にアクセスして、ロギング、セッションデータ、および認証されたクライアントまたはAPIキーにアクセスできます。

• 構成可能なストレージ：

  • デフォルトでSQLiteを使用して、Plexusユーザー認証トークン、ユーザー固有の外部OAuthトークン、APIキー、外部OAuthプロバイダー構成、テナント構成、およびユーザーが提出したAPIキーを永続的に保存します。
  • 現在、MCPセッション管理にはRedisが必要です（SQLiteセッションストアの強化が計画されています）。

• （開発中）内部OAuth 2.1プロバイダー：

  • MCP Plexusが独自のOAuth 2.1認可サーバーとして機能するための基礎要素。
  • 基本的なモデルとスタブエンドポイントが含まれています。完全な実装（動的クライアント登録、内部クライアントのユーザー同意、完全なトークン管理）は将来の目標です。

📚 ドキュメント

導入

MCP Plexusとは？

MCP PlexusはFastMCP 2.7の機能を拡張し、高度でマルチテナントのAIバックエンドシステムを作成するための構造化された環境を提供します。これにより、大規模言語モデル（LLM）やAIエージェントに対して、カスタマイズされたツール、リソース、およびプロンプトのセットを公開できる、個別の分離された環境（テナント）を定義できます。

主要な差別化機能は次のとおりです：

• 強力なマルチテナンシー： 単一のデプロイで複数のクライアントまたは組織をホストし、それぞれが独自のデータとツールアクセスを持ちます。
• 簡素化された外部サービス統合： 組み込みのフロー管理を使用して、MCPツールを外部のOAuth 2.1保護サービス（GitHub、Google APIなど）に安全に接続します。
• ユーザー固有の永続的なアクセス： ホストアプリケーションがPlexusにユーザーを登録できるようにし、外部OAuthトークンを永続的に保存して、再認証の摩擦を軽減します。
• ツールのAPIキー管理： 外部サービスに直接キーベースの認証を必要とするツールのAPIキーを安全に保存して注入します。
• 標準化された拡張性： FastMCPのPythonicデコレーターを活用してMCPコンポーネントを定義し、拡張のための明確な構造を提供します。

なぜMCP Plexusを選ぶのか？

AIアプリケーションの複雑さが増すにつれて、LLMに関連するコンテキストと実行可能な機能を安全に提供する必要性がますます重要になります。MCP Plexusは、次のようにしてこの問題に対処します：

• マルチテナントデプロイの簡素化： 複数の分離されたMCP環境を管理するための定型コードと複雑さを削減します。
• 外部APIアクセスの標準化： ツールがOAuth保護およびAPIキーゲートサービスとやり取りするための一貫した安全なメカニズムを提供します。
• ユーザー体験の向上： 永続的なユーザー認証とトークン保存により、外部サービスへの繰り返しのログインプロンプトを最小限に抑えます。
• 安全な実践の促進： 機密資格情報（OAuthトークン、APIキー）をコアツールロジックの外で管理します。
• FastMCPのパワーを活用： コアMCPプロトコルの処理と開発者に優しいインターフェースのために、実績のある高性能なFastMCP 2.7ライブラリを基に構築されています。

コア哲学

• セキュリティ第一： OAuth 2.1と安全な資格情報管理を中心に設計されています。
• 開発者体験： テナント、ツール、および安全な統合を定義するための直感的なAPIを目指しています。
• 拡張性と分離： 明確な関心事の分離を持つマルチテナントアーキテクチャ用に構築されています。
• 拡張性： カスタム認証プロバイダーとサービスで拡張できる基盤を提供します。

MCP Plexusの使用方法（開発者ガイド）

MCP Plexusは、カスタムマルチテナントMCPサーバーを構築するためのフレームワークまたはSDKとして機能します。通常は次のように使用します：

1. テナントの定義

テナント（エンティティ）は最上位の組織単位です。

• 管理： テナントは現在、管理CLIコマンド（または管理インターフェースを構築した場合は直接API呼び出し）を介して管理されます。

  • CLIの例：

    plexus admin tenant create --entity-id "mycompany" --name "My Company Inc."
    

• アクセス： 各テナントには独自のMCPエンドポイントがあります：http://<server>/{entity_id}/mcp/

2. ホストアプリケーションユーザーの登録

メインアプリケーション（「ホストアプリケーション」）の特定のユーザーに対して、セッションをまたいで外部OAuthトークンを永続的に保存できるようにするには、まずそのユーザーIDを特定のテナントに対してMCP Plexusに登録する必要があります。

• エンドポイント： POST /{entity_id}/plexus-auth/register-user

• リクエストヘッダー： X-Host-App-Secret: <your_HOST_APP_REGISTRATION_SECRET_value>

• リクエストボディ（JSON）：

  {
      "user_id_from_host_app": "unique_stable_user_id_from_your_main_app"
  }
  

• レスポンスボディ（JSON）：

  {
      "plexus_user_auth_token": "a_long_secure_token_string_for_this_user",
      "persistent_user_id": "unique_stable_user_id_from_your_main_app", 
      "message": "User token processed successfully."
  }
  

• ホストアプリケーションは、返されたplexus_user_auth_tokenを安全に保存し、このユーザーの後続のMCPリクエストを認証するために使用する必要があります。

3. MCPセッションの初期化

MCPクライアントは特定のテナントのMCPエンドポイントとやり取りします。

• エンドポイント： /{entity_id}/mcp/

• 認証：

  • 認証されたPlexusユーザーの場合： すべてのMCPリクエスト（初期のinitialize呼び出しを含む）に、手順2で取得したplexus_user_auth_tokenをAuthorization: Bearer <token>HTTPヘッダーを介して含めます。

• 標準MCP初期化：

  {
      "jsonrpc": "2.0",
      "method": "initialize",
      "id": "client-init-123",
      "params": {
          "protocolVersion": "2025-03-26",
          "capabilities": {},
          "clientInfo": {
              "name": "MyHostApplicationClientName",
              "version": "1.0.0"
          }
      }
  }
  

• サーバーはMcp-Session-Idヘッダーで応答し、クライアントはそのセッションの後続のリクエストにこれを含める必要があります。

4. MCPツール、リソース、およびプロンプトの作成

mcp_plexus/tool_modules/ディレクトリ内のPythonモジュールでツール、リソース、およびプロンプトを定義します。これらのモジュールは、グローバルに利用可能なPLEXUS_SERVER_INSTANCE（MCPPlexusServerのインスタンス）を使用してコンポーネントを登録します。

mcp_plexus/core/global_registry.py：

# This instance is populated at server startup
PLEXUS_SERVER_INSTANCE: Optional[MCPPlexusServer] = None

ツールモジュールの例（mcp_plexus/tool_modules/my_custom_tools.py）：

import logging
from typing import Dict, Any, Optional, List
import httpx # Required for @requires_auth example
from fastmcp import Context as FastMCPBaseContext # For type hinting standard ctx
from mcp_plexus.core.global_registry import PLEXUS_SERVER_INSTANCE
from mcp_plexus.plexus_context import PlexusContext # For specific Plexus context features
from mcp_plexus.oauth.decorators import requires_auth
from mcp_plexus.services.decorators import requires_api_key

logger = logging.getLogger(__name__)

if PLEXUS_SERVER_INSTANCE is None:
    # This check helps catch issues if tool modules are imported before PLEXUS_SERVER_INSTANCE is set
    raise RuntimeError("PLEXUS_SERVER_INSTANCE not initialized when my_custom_tools.py was imported.")

@PLEXUS_SERVER_INSTANCE.tool(
    name="get_tenant_specific_greeting",
    description="Returns a greeting specific to the current tenant.",
    allowed_tenant_ids=["mycompany", "another_tenant"] # Tool only visible to these tenants
)
async def get_greeting(ctx: FastMCPBaseContext) -> Dict[str, str]:
    plexus_ctx: PlexusContext = PlexusContext(ctx.fastmcp) # Create PlexusContext from base
    
    entity_id = plexus_ctx.entity_id
    user_id = plexus_ctx.persistent_user_id # Will be None for guest users
    session_val = await plexus_ctx.get_session_value("my_key")

    greeting = f"Hello from entity '{entity_id}'!"
    if user_id:
        greeting += f" Authenticated user: {user_id}."
    if session_val:
        greeting += f" Session value for 'my_key': {session_val}."
        
    return {"greeting": greeting}

# Example: Tool requiring external GitHub OAuth
@PLEXUS_SERVER_INSTANCE.tool(
    name="get_my_github_repos",
    description="Fetches the user's GitHub repositories.",
    tool_sets=["developer_tools"], # Categorize tool
    allowed_tenant_ids=["mycompany"] 
)
@requires_auth(provider_name="github", scopes=["repo", "read:user"])
async def get_my_github_repos(
    ctx: FastMCPBaseContext, 
    *,  # This enforces subsequent arguments as keyword-only
    _authenticated_client: httpx.AsyncClient
) -> List[Dict[str, Any]]:
    plexus_ctx = PlexusContext(ctx.fastmcp)
    logger.info(f"Fetching GitHub repos for user '{plexus_ctx.persistent_user_id}' in entity '{plexus_ctx.entity_id}'")
    response = await _authenticated_client.get("https://api.github.com/user/repos")
    response.raise_for_status()
    return response.json()

# Example: Tool requiring an API key
WEATHER_API_PROVIDER_NAME = "openweathermap"
@PLEXUS_SERVER_INSTANCE.tool(
    name="get_weather_forecast",
    description=f"Gets weather forecast using {WEATHER_API_PROVIDER_NAME}.",
    allowed_tenant_ids=["mycompany", "another_tenant"]
)
@requires_api_key(
    provider_name=WEATHER_API_PROVIDER_NAME,
    key_name_display="OpenWeatherMap API Key",
    instructions="Please provide an API key for OpenWeatherMap."
)
async def get_weather(
    ctx: FastMCPBaseContext, 
    city: str,
    *,
    openweathermap_api_key: str # Injected by @requires_api_key
) -> Dict[str, Any]:
    plexus_ctx = PlexusContext(ctx.fastmcp)
    logger.info(f"Fetching weather for {city} for user '{plexus_ctx.persistent_user_id}' in entity '{plexus_ctx.entity_id}' using provided API key.")
    # Use openweathermap_api_key to call the external weather API
    # Example: weather_data = await httpx.get(f"api.openweathermap.org/data/2.5/weather?q={city}&appid={openweathermap_api_key}")
    return {"city": city, "temperature": "20C", "condition": "Sunny (mock data)"}

logger.info("my_custom_tools.py - Tools registered with PLEXUS_SERVER_INSTANCE.")

• ツールのスコープ：
  • allowed_tenant_ids：entity_id文字列のリスト。指定された場合、ツールはそれらのテナントによってのみ検出可能で呼び出し可能です。Noneまたは空の場合、ツールはグローバル（すべてのテナントに表示され、tool_setフィルタリングの対象となります）。
  • tool_sets：文字列のリスト。クライアントは、tools/list MCP呼び出しにtool_set_filterを渡すことで、特定のセットに属するツールを要求できます。
• PlexusContext：
  • ツールは通常、fastmcp.Context（例ではFastMCPBaseContextとエイリアスされています）を受け取ります。
  • mcp_plexus.plexus_context.PlexusContext(base_ctx.fastmcp)のインスタンスを作成して、Plexus固有の機能にアクセスします：
    • plexus_ctx.entity_id：現在のテナントのID。
    • plexus_ctx.persistent_user_id：認証されたPlexusユーザーの安定したID（存在する場合）。
    • plexus_ctx.mcp_session_id：現在のMCPセッションID。
    • await plexus_ctx.get_session_value(key) / await plexus_ctx.set_session_value(key, value)：テナントとセッションにスコープされたキーバリューストア（Redisを使用）。
    • await plexus_ctx.get_authenticated_external_client(provider_name, required_scopes)：@requires_authで使用されるか、直接呼び出すことができます。
    • await plexus_ctx.get_api_key(provider_name)：@requires_api_keyで使用されるか、直接呼び出すことができます。

5. ツールのセキュリティ保護

a. 外部OAuth（@requires_auth）

ツールがユーザーの代わりにサードパーティサービス（GitHub、Googleなど）にアクセスする必要がある場合に使用します。

フロー：

1. 管理者がプロバイダーを構成する： 管理者はCLI（または管理API）を使用して、特定のテナントの外部OAuthプロバイダーの詳細（クライアントID、シークレット、URL、デフォルトのスコープ）を登録します。
   • CLIの例：

     plexus admin ext-oauth create --entity-id "mycompany" --provider-name "github" --client-id "YOUR_GITHUB_CLIENT_ID" --client-secret "YOUR_GITHUB_CLIENT_SECRET" --authorization-url "https://github.com/login/oauth/authorize" --token-url "https://github.com/login/oauth/access_token" --scopes "repo,user:email" --userinfo-url "https://api.github.com/user"
     

2. ツールを装飾する： ツール関数を@requires_auth(provider_name="github", scopes=["repo", "read:user"])で装飾します。
3. ツールを呼び出す：
   • MCPクライアントがツールを呼び出すと、デコレーター（PlexusContextを介して）は、現在のユーザー（Plexusユーザーの場合は永続的、ゲストの場合はセッション）と要求されたプロバイダー/スコープに対する有効な保存されたOAuthトークンをチェックします。
   • トークンが有効： デコレーターは認証されたhttpx.AsyncClient（authenticated_clientと名付けられています）をツールのキーワード引数に注入します。
   • トークンが無効/欠落： デコレーターはPlexusExternalAuthRequiredErrorを発生させます。これはFastMCPによって捕捉され、構造化されたMCP ToolErrorに変換されます。エラーペイロードにはauthorization_urlが含まれています。
4. クライアントがリダイレクトを処理する： MCPクライアントアプリケーションは、ユーザーをこのauthorization_urlにリダイレクトする責任があります。
5. ユーザーが認証と同意を行う： ユーザーは外部プロバイダーで認証し、同意を与えます。
6. Plexusへのコールバック： 外部プロバイダーはユーザーを/{entity_id}/oauth/external_callback/{provider_name}にリダイレクトします。
7. トークン交換と保存： MCP Plexusは認可コードをトークンに交換し、それらを安全に保存し（セッションおよび/または永続的なユーザーストア）、成功ページを表示します。
8. クライアントがツールを再試行する： ユーザーがMCPクライアントに戻り、クライアントは元のツール呼び出しを再試行する必要があります。今度は、PlexusContextが有効なトークンを見つけます。

graph TD
    subgraph Tool Developer
        A[Define Tool with @requires_auth] --> B{Tool Called by LLM/Client}
    end

    subgraph MCP Plexus
        B --> C{PlexusContext: Token Check};
        C -- Valid Token --> D[Inject Auth_Client];
        D --> E[Execute Tool Logic];
        C -- Invalid/No Token --> F[Raise PlexusExternalAuthRequiredError];
        F --> G[Return MCP ToolError with auth_url];
    end
    
    subgraph MCP Client App
        G --> H[Redirect User to auth_url];
    end

    subgraph User & External Provider
        H --> I[User Authenticates & Consents at Ext. Provider];
        I --> J[Ext. Provider Redirects to Plexus /callback];
    end

    subgraph MCP Plexus
        J --> K{Plexus /callback Endpoint};
        K --> L[Exchange Auth Code for Tokens];
        L --> M[Store Tokens Session/Persistent];
        M --> N[Show Success Page to User];
    end
    
    subgraph MCP Client App
        N --> O[User Returns to Client App];
        O --> P[Client Retries Tool Call];
    end
    
    P --> C;
    E --> Q[Return Tool Result to Client];

b. APIキーアクセス（@requires_api_key）

ツールが外部サービスとやり取りするためにユーザーから直接APIキーを必要とする場合に使用します。

フロー：

1. ツールを装飾する： ツールを@requires_api_key(provider_name="my_service", key_name_display="My Service API Key", instructions="Get your key from ...")で装飾します。
2. ツールを呼び出す：
   • デコレーター（PlexusContextを介して）は、現在のユーザー（Plexusユーザーの場合は永続的）とプロバイダーに対するAPIキーが保存されているかどうかをチェックします。
   • キーが見つかった： 復号化されたAPIキーが{provider_name}_api_key（例：my_service_api_key）としてツールのキーワード引数に注入されます。
   • キーが見つからない： PlexusApiKeyRequiredErrorを発生させます。FastMCPはこれを構造化されたMCP ToolErrorに変換し、クライアント/ユーザーにキーを提出する方法を指示します。
3. ユーザーがAPIキーを提出する： ユーザー（MCPクライアントまたは別のインターフェースを介して）はPOST /{entity_id}/plexus-services/api-keysエンドポイントを呼び出します。
   • リクエストヘッダー： Authorization: Bearer <plexus_user_auth_token>（永続的な保存に必要）。
   • リクエストボディ（JSON）：

     {
         "provider_name": "my_service",
         "api_key_value": "users_actual_api_key_value"
     }
     

4. キーを保存する： MCP PlexusはAPIキーを暗号化し、ユーザーのpersistent_user_idに関連付けて保存します。
5. クライアントがツールを再試行する： ツール呼び出しが再試行され、キーが見つかり注入されます。

graph TD
    subgraph Tool Developer
        A[Define Tool with @requires_api_key] --> B{Tool Called by LLM/Client}
    end

    subgraph MCP Plexus
        B --> C{PlexusContext: API Key Check};
        C -- Key Found & Decrypted --> D[Inject API Key into Tool];
        D --> E[Execute Tool Logic];
        C -- Key Not Found --> F[Raise PlexusApiKeyRequiredError];
        F --> G[Return MCP ToolError with submission instructions];
    end
    
    subgraph User/MCP Client App
        G --> H[User/Client Submits API Key via /api-keys endpoint];
    end

    subgraph MCP Plexus
        H --> I{Plexus /api-keys Endpoint};
        I --> J[Encrypt & Store API Key];
    end
    
    subgraph User/MCP Client App
        J --> K[Client Retries Tool Call];
    end
    
    K --> C;
    E --> L[Return Tool Result to Client];

プロジェクトの状態とロードマップ

このセクションでは、現在の実装状態と計画されている機能について説明します。

実装済み

• [x] コアマルチテナンシー： URL（/{entity_id}/mcp/）を介した基本的なテナント識別とDBベースの検証。
• [x] FastMCP 2.7統合： コアMCPプロトコル（Streamable HTTP）、ツール/リソース/プロンプト定義にjlowin/fastmcpを使用。
• [x] セッション管理： RedisベースのMCPセッションストア（PlexusSessionManager, SessionData）。
• [x] Plexusユーザー認証： ホストアプリケーションのユーザー登録（/{entity_id}/plexus-auth/register-user）を通じて、plexus_user_auth_tokenを取得してpersistent_user_idにリンク。MCPリクエストはBearerトークンまたはURLトークンパスで認証されます。
• [x] 外部OAuth 2.1フローの支援：
  • ツールの@requires_authデコレーター。
  • OAuthコールバック処理（/{entity_id}/oauth/external_callback/{provider_name}）。
  • 認証されたPlexusユーザーの外部OAuthトークンの永続的な保存（デフォルトでSQLite）。
  • ゲストユーザーの外部OAuthトークンのセッションスコープの保存。
  • テナントごとの外部OAuthプロバイダー構成を管理するための管理API/CLI。
• [x] ツールのAPIキー管理：
  • @requires_api_keyデコレーター。
  • ユーザーが提出したAPIキーの安全な（暗号化された）永続的な保存（デフォルトでSQLite）をpersistent_user_idにリンク。
  • APIキー提出用のエンドポイント（/{entity_id}/plexus-services/api-keys）。
• [x] PlexusContext： entity_id, persistent_user_id, mcp_session_idを提供し、OAuth/APIキーアクセスのためのメソッドを提供します。
• [x] 管理エンドポイントと基本的なCLI： テナントと外部OAuthプロバイダー構成の管理。
• [x] SQLite永続的ストレージ： ユーザー認証トークン、外部トークン/APIキー、プロバイダー構成、テナントデータのデフォルトのバックエンド。
• [x] ツールのスコープとセット： allowed_tenant_idsに基づくツールの可視性と、tools/listパラメーターによるtool_setsでのフィルタリングの基本的な実装。

計画中 / 開発中

• [ ] 完全な内部OAuth 2.1プロバイダー：
  • [ ] 内部OAuthクライアントの動的クライアント登録。
  • [ ] 内部OAuthクライアントのユーザー向け同意画面。
  • [ ] 完全なトークン失効と検査エンドポイント。
  • [ ] より堅牢なセキュリティとグラントタイプのサポート。
• [ ] SQLiteセッションストア： SQLitePlexusSessionStoreを実装して、Redisを完全にオプションにする。
• [ ] 細粒度のストレージバックエンド構成： 異なるデータタイプ（セッション、永続的なトークンなど）に対して、別々のバックエンド選択（Redis/SQLite）を許可する。
• [ ] Plexusユーザー認証トークンのライフサイクル： plexus_user_auth_tokenの堅牢な有効期限と失効を実装する。
• [ ] 包括的なテナント構成： テナントが環境のより多くの側面をカスタマイズできるようにする（例：デフォルトのツールセット、UIテーマ（適用可能な場合））。
• [ ] 高度なツールスコープ： ツールの可視性とアクセス制御のためのより洗練されたルール。
• [ ] 強化されたCLI： より多くのコマンド、管理とユーザータスクのための使いやすさの向上。
• [ ] すべてのストレージバックエンドでの完全な非同期サポート： すべてのデータベース操作がまだ非同期でない場合は、完全に非同期にする。
• [ ] より堅牢なエラー処理と監視： すべてのAPIで標準化されたエラー応答、改善された構造化ログ、潜在的なメトリクス。
• [ ] 本番環境デプロイガイドライン： Docker、リバースプロキシ、スケーリングのためのドキュメント。
• [ ] 包括的なテストスイート： すべての機能に対するユニット、統合、およびエンドツーエンドテストを拡張する。
• [ ] 詳細なユーザーと開発者ドキュメント： このREADMEを超えて、構造化されたドキュメントサイトに拡張する。

🔧 技術詳細

MCP PlexusはASGIアプリケーションとして動作し（通常はUvicornで実行）、MCPクライアントと基盤となるFastMCPサーバーインスタンスの間の高度な仲介者として機能します。

• FastAPI： メインのWebアプリケーションルーティング、HTTPリクエストの処理、および管理APIエンドポイントの提供に使用されます。
• FastMCP (jlowin/fastmcp)： FastMCPの共有インスタンスが、Streamable HTTPを介したMCPプロトコルメッセージ（ツール、リソース、プロンプト）の処理のためのコアエンジンとして使用されます。
• Plexusコア：
  • テナント管理： URLパス（/{entity_id}/...）からテナントを識別し、テナント構成が尊重されるようにします（完全な構成は開発中、現在はDBベースの検証）。
  • セッション管理（PlexusSessionManager）： MCPセッションデータ（例：Mcp-Session-Id）を管理し、現在はRedisを使用してセッション状態を管理します。MCPセッションをentity_idと、利用可能な場合はpersistent_user_idに関連付けます。
  • Plexusユーザー認証： ホストアプリケーションのユーザーの登録を処理し、plexus_user_auth_token値を管理してpersistent_user_idにリンクします。
  • OAuthフローオーケストレーション： 外部サービスへのアクセスが必要なツールのためのOAuth 2.1 Authorization Code grantフローを管理し、安全なトークン保存と更新を行います（更新は開発中）。
  • APIキーサービス： ツールのためのユーザーが提供したAPIキーの安全な保存と取得を管理します。
  • PlexusContext： MCPツールに注入される拡張されたコンテキストオブジェクトで、entity_id、persistent_user_id、セッションデータ、および認証されたHTTPクライアントまたはAPIキーを取得するためのヘルパーメソッドにアクセスできます。
• ストレージ：
  • Redis（セッションに必要）： 現在、一時的なMCPセッションデータに使用されています。
  • SQLite（永続的データのデフォルト）： Plexusユーザー認証トークン、ユーザー固有の外部OAuthトークン、APIキー、外部OAuthプロバイダー構成、およびテナントメタデータの保存に使用されます。

📄 ライセンス

このプロジェクトはFastMCPと同じライセンスでライセンスされています。