FastMCP Integration Application Demo

FastMCP 統合アプリケーションのデモ

中文说明 (中国語ドキュメント)

このプロジェクトでは、FastMCP を使用して構築したモジュール型アプリケーションを紹介します。MCP サーバー、FastAPI インターフェース、LLM エージェント機能を統合しています。

プロジェクトのアーキテクチャ

このプロジェクトではモジュール型設計を採用し、機能ごとに異なるパッケージに分けています。

app/
├── __init__.py
├── api/                 # FastAPI Application Layer
│   ├── __init__.py
│   ├── main.py          # FastAPI main application entry point
│   └── routers/         # API route definitions
│       ├── __init__.py
│       ├── agent.py       # Agent mode routes
│       ├── mcp_resources.py # MCP resource routes
│       └── mcp_tools.py     # MCP tool routes
├── llm/                 # LLM (Large Language Model) Processing Layer
│   ├── __init__.py
│   ├── base.py          # Base LLM class
│   └── openai.py        # OpenAI implementation
└── mcp_server/          # MCP Server Definition Layer
    ├── __init__.py
    ├── base.py          # Base MCP Server class
    ├── run.py           # Script for internal Client connection or direct execution
    └── simple.py        # Simple MCP Server implementation (with tools & resources)
main.py                  # Main entry point (runs API or MCP server)

コアワークフロー（API モード）：

1. MCP サーバーを単独で実行：python main.py --mode mcp を使用して独立した MCP サーバープロセスを起動します。SSE トランスポートを使用し、指定したポート（デフォルト：8001）で待ち受けます。
2. API サーバーを実行：python main.py --mode api を使用して FastAPI サーバーを起動します（ポート 8080 で待ち受けます）。
3. 接続：FastAPI サーバー内の mcp_client が、SSE 経由で独立して実行中の MCP サーバーに接続します。
4. リクエストの処理：フロントエンドやその他のクライアントは、FastAPI が提供する HTTP API を通じてアプリケーションとやり取りします。
5. ツール／リソース／エージェントの呼び出し：FastAPI のルートが、リクエストを mcp_client（MCP サーバーと通信）または llm モジュール（LLM API と通信）に転送します。

機能

• モジュール型設計：API、LLM、MCP の役割を明確に分離し、拡張や保守を容易にします。
• 2 種類の実行モード：
  • api モード：FastAPI サーバーを実行します。別途起動した MCP サーバーが必要です。
  • mcp モード：テストや他のクライアントからの接続に使用する MCP サーバーを直接実行します。
• LLM 統合：OpenAI（または拡張可能なその他の LLM）を使用して、ツールの出力を処理したり、エージェントモードで実行したりできます。
• エージェントモード：LLM が自律的に MCP ツールを選択して呼び出すための /api/agent/process エンドポイントを提供します。
• 完全な API：FastAPI を通じて、MCP ツール、リソース、エージェント機能用の RESTful エンドポイントを提供します。
• 永続的な接続：API サーバーは、効率化のために MCP サーバーへの長時間接続する SSE 接続を維持します。

インストール

1. リポジトリをクローンします（必要な場合）。

2. 依存関係をインストールします（uv または pip を使用）。

   # 推奨：uv を使用
   uv pip install -e .
   
   # または、pip を使用
   # pip install -e .
   

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

   • LLM 機能を使用するには、OPENAI_API_KEY 環境変数が必要です。
   • プロジェクトのルートに .env ファイルを作成して、次のように定義できます。

     OPENAI_API_KEY=sk-...
     

使用方法

API サーバーを実行する（推奨）

このモードでは、最初にスタンドアロンの MCP サーバーを起動する必要があります。

1. MCP サーバーを起動します（1 つ目のターミナル）：

   # SSE トランスポートを使用し、127.0.0.1:8001 で待ち受けます（デフォルト）
   python main.py --mode mcp
   
   # または、別のホストとポートを指定します
   # python main.py --mode mcp --mcp-host 0.0.0.0 --mcp-port 8002
   

2. API サーバーを起動します（別のターミナル）：

   # 0.0.0.0:8080 で待ち受けます（デフォルト）
   python main.py --mode api
   
   # 別のポートを使用するか、ホットリロードを有効にします（開発用）
   # python main.py --mode api --port 9000 --reload
   

   API サーバーには http://localhost:8080（または指定したポート）でアクセスできます。ステップ 1 で起動した MCP サーバーに自動的に接続します（デフォルトの接続先：http://localhost:8001/sse）。

MCP サーバーを直接実行する

MCP サーバーのみを実行する場合（たとえば、他の FastMCP クライアントから直接接続する場合）は、次のようにします。

# Default: Use SSE transport, listening on 127.0.0.1:8001
python main.py --mode mcp

# Use Standard I/O (stdio) transport
# python main.py --mode mcp --mcp-transport stdio

API エンドポイント（API サーバー経由でアクセス）

API サーバーは http://localhost:8080（デフォルト）で実行されます。

• MCP ツール（/api/tools）：
  • GET /：利用可能なすべてのツールとそのパラメーターを一覧表示します。
  • POST /{tool_name}：指定したツールを呼び出します。リクエストボディの例：{"params": {"a": 5, "b": 3}, "use_llm": true, "system_message": "Explain the result"}
• MCP リソース（/api/resources）：
  • GET /：利用可能なすべてのリソース URI とそのタイプを一覧表示します。
  • GET /{resource_path:path}：指定したリソースの内容を取得します（例：GET /api/resources/example/greeting）。
• エージェントモード（/api/agent）：
  • POST /process：LLM がユーザーのリクエストを自律的に処理し、必要に応じてツールを呼び出します。リクエストボディの例：{"prompt": "What is 5 plus 3?"}
• ヘルスチェック：
  • GET /health：API サーバーが実行中かどうかを確認します。
  • GET /api/tools/health：API サーバーと MCP サーバー間の接続状態を確認します。

アプリケーションの拡張

ツールの追加

1. app/mcp_server/simple.py の BaseMCPServer を拡張します（または、新しいサーバーファイルを作成します）。
2. _register_tools メソッド内で @self.mcp.tool() デコレーターを使って新しいツールを定義します。
3. 新しいサーバーファイルを作成した場合は、app/mcp_server/run.py でインポートしてインスタンス化します。

新しい LLM プロバイダーの追加

1. app/llm/ ディレクトリに新しい Python ファイルを作成します（例：anthropic.py）。
2. app.llm.base.BaseLLM を継承する新しいクラスを作成します。
3. generate メソッドと generate_with_tools メソッドを実装します。
4. 必要な場所（例：agent.py）で、新しい LLM クラスをインポートして使用します。

開発

開発時に API サーバーを実行する際は、ホットリロードを有効にします。

# Ensure the standalone MCP server is still running
python main.py --mode api --reload