mcp_server

MCP による RunPod Python コード実行

このプロジェクトでは、Model Context Protocol（MCP）を使用して、AI アシスタントが RunPod インフラストラクチャ上で Python コードを実行できるようにします。主に次の 2 つのコンポーネントで構成されています。

1. Python コードを実行する RunPod Serverless API
2. RunPod API に接続し、AI アシスタント向けの標準化されたインターフェースを提供する MCP サーバー

システムアーキテクチャ

┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│               │     │               │     │               │
│  AI Assistant │────▶│   MCP Server  │────▶│ RunPod API    │
│  (e.g. Cline) │     │    (Python)   │     │ (Serverless)  │
│               │     │               │     │               │
└───────────────┘     └───────────────┘     └───────────────┘

インタラクションシーケンス

UML

1. RunPod Serverless のセットアップ

前提条件

• Docker がインストールされていること
• API キーを持つ RunPod アカウント
• Docker と Python の基本的な知識

ステップ 1：Docker イメージのビルドとプッシュ

Dockerfile には、一般的なデータサイエンスライブラリとコードハンドラーが含まれています。 現在の Docker イメージ：docker.io/79c2e466/code_handler_serverless

# Clone this repository
git clone https://github.com/yourusername/runpod-python-executor.git
cd runpod-python-executor

# Build the Docker image
docker build -t yourusername/runpod-python-executor:latest .

# Login to Docker Hub
docker login

# Push the image to Docker Hub
docker push yourusername/runpod-python-executor:latest

ステップ 2：RunPod Serverless にデプロイ

1. RunPod.io にアクセスします
2. Serverless → Deploy に移動します
3. Docker イメージの URL を入力します：docker.io/79c2e466/code_handler_serverless
4. 設定を行います：
   • Worker Type：CPU または基本 GPU
   • Min/Max Workers：1/3（必要に応じて調整してください）
   • Idle Timeout：5 分
5. 「Deploy」をクリックします

ステップ 3：Endpoint ID の取得

デプロイ後、RunPod によって Endpoint ID が生成されます。MCP サーバーの設定に必要なため、この ID をコピーしてください。

Serverless API エンドポイントは次のとおりです：https://api.runpod.io/v2/{endpoint_id}/run

次のコマンドを使用してエンドポイントをテストできます。

curl -X POST \
  https://api.runpod.io/v2/{endpoint_id}/runsync \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_RUNPOD_API_KEY' \
  -d '{
    "input": {
      "code": "print(\"Hello, World!\")"
    }
  }'

2. MCP サーバーのセットアップ

MCP サーバーは、Model Context Protocol を使用して AI アシスタントを RunPod エンドポイントに接続します。

前提条件

• Python 3.8+ がインストールされていること
• RunPod API キー
• 上記のステップ 3 で取得した RunPod Endpoint ID

ステップ 1：必要なパッケージのインストール

インストール Python プロジェクトへの MCP の追加 Python プロジェクトの管理には uv の使用をおすすめします。uv で管理する Python プロジェクトでは、次のコマンドで mcp を依存関係に追加します。

uv add "mcp[cli]" 依存関係の管理に pip を使用するプロジェクトの場合は、代わりに次のコマンドを実行します。

pip install mcp スタンドアロン MCP 開発ツールの実行 uv を使用して mcp コマンドを実行するには、次のコマンドを実行します。

uv run mcp

pip install mcp requests

ステップ 2：MCP サーバーの設定

runpod_mcp_server.py という名前のファイルを作成し、提供されたテンプレートのコードを記述します。次の環境変数を更新してください。

# Update these values
RUNPOD_API_KEY = "your_runpod_api_key"
RUNPOD_ENDPOINT_ID = "your_endpoint_id"  # From serverless deployment

ステップ 3：MCP サーバーの実行

cline add mcp setting

"PythonServerlessExecutor": {
      "command": "xx/.local/bin/uv",
      "args": [
        "run",
        "xxx/mcp_server/runpod_serverless_mcp_server/server.py"
      ],
      "disabled": false,
      "autoApprove": []
    },

ステップ 4：MCP サーバーの使用

接続すると、次のツールを使用できます。

• execute_python_code：RunPod 上で Python コードを実行します
• check_runpod_status：RunPod との接続状態を確認します

Cline での使用例：

Can you run this Python code?
```python
import numpy as np
import matplotlib.pyplot as plt

x = np.linspace(0, 10, 100)
y = np.sin(x)
plt.plot(x, y)
plt.title("Sine Wave")
plt.savefig("sine_wave.png")
print("Generated sine wave plot")

Cline は MCP サーバーを使用してこのコードを実行し、結果を返します。

サンプル

仕組み

1. AI アシスタント（Cline など）が Python コードの実行リクエストを受け取ります
2. MCP プロトコルを介して execute_python_code ツールを呼び出します
3. MCP サーバーがコードを RunPod serverless エンドポイントに送信します
4. RunPod が Docker コンテナー内でコードを実行します
5. 結果（stdout、stderr、戻り値コード）が MCP サーバーに返されます
6. MCP サーバーが結果を整形し、AI アシスタントに返します
7. AI アシスタントが結果をユーザーに表示します

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

• コードは分離されたコンテナー内で実行されます
• リソースの不正利用を防ぐため、実行時間が制限されています
• 本番環境で使用する場合は、追加のセキュリティ対策を実装してください

トラブルシューティング

• MCP サーバーの接続問題：API キーと Endpoint ID を確認してください
• コード実行のタイムアウト：コードが複雑すぎるか、無限ループになっている可能性があります
• ライブラリの不足：コードで Dockerfile に含まれていないライブラリが必要かどうか確認してください

詳細設定

動作を調整するには、次の項目を変更できます。

• MAX_EXECUTION_TIME：コード実行のタイムアウト時間を変更します
• Dockerfile：必要に応じてライブラリを追加または削除します
• エラー処理：特定の状況に応じてエラーメッセージをカスタマイズします

Pod 作成ではなくサーバーレスを選んだ理由

重要な理由がいくつかあり、フルポッドを作成するのではなく、RunPod のサーバーレスインフラストラクチャを使用することにしました。

1. ログ取得の制限：RunPod では、作成したポッドのログを取得するための直接的な API が提供されていません。そのため、ポッド作成方式ではコード実行の出力を取得することが困難です。
2. 接続の複雑さ：ポッドへの永続的な接続を維持するには、SSH などのリモートアクセス方式に対応する追加のインフラストラクチャが必要になります。
3. リソース管理：ポッドはアイドル状態でも実行され続け、料金が発生します。一方、サーバーレス関数では実際の実行時間に対してのみ料金が発生します。

サーバーレス方式のデメリット

1. コールドスタートのレイテンシー：コンテナの起動に時間がかかるため、初回の実行が遅れる場合があります（コールドスタート）。
2. 永続ストレージがない：実行のたびに新しい環境が開始されるため、実行間で状態を維持することが困難です。
3. リソースの制約：サーバーレス関数は一般に、フルポッドと比べて CPU、メモリ、ディスクの割り当てが限られています。 4.GPU アクセスの制限：サーバーレスで GPU にアクセスすることも可能ですが、その利用はより制限されており、通常、専用ポッドよりも高額です。