Python Runtime Interpreter MCP Server

🚀 PRIMS – Python Runtime Interpreter MCP Server

PRIMSは、小規模なオープンソースのModel Context Protocol (MCP) サーバーです。このサーバーを使用すると、LLMエージェントが安全な使い捨てサンドボックス内で任意のPythonコードを実行できます。

• 一つのツール、一つの仕事：単一のMCPツール run_code を公開し、ユーザーが提供したPythonコードを実行し、stdout / stderr をストリーミングで返します。 • 分離かつ再現可能：各呼び出しで新しい仮想環境が起動し、要求されたpipパッケージをインストールし、オプションの読み取り専用ファイルをマウントした後、ワークスペースを破棄します。 • ゼロ設定：MCP/stdioを介して動作するか、Dockerに配置することができます。

🚀 クイックスタート

1. ローカル開発環境

chmod +x scripts/setup_env.sh   # 一度だけ、スクリプトを実行可能にする
./scripts/setup_env.sh          # .venvを作成し、依存関係をインストールする

# 新しいシェルで仮想環境をアクティブ化する
source .venv/bin/activate

2. サーバーを起動する

python -m server.main         # http://0.0.0.0:9000/mcpにバインドする

3. Docker

# クイックなワンライナー（ビルド + 実行）
chmod +x scripts/docker_run.sh
./scripts/docker_run.sh         # 準備ができるとMCP URLを表示する

💻 使用例

利用可能なツールをリストする

サーバーが公開しているすべてのツールをリストするために、提供されているスクリプトを使用できます。

python examples/list_tools.py

期待される出力（ツール名と説明は異なる場合があります）：

利用可能なツール:
- run_code: オプションの依存関係とファイルマウントを持つ安全なサンドボックス内でPythonコードを実行します。
- list_dir: セッションのワークスペース内のファイル/ディレクトリをリストします。
- preview_file: セッションのワークスペース内のテキストファイルの最大8KBをプレビューします。
- persist_artifact: 出力/ファイルを署名付きURLにアップロードして永続的に保存します。
- mount_file: リモートファイルをセッションごとに一度だけ `mounts/<path>` にダウンロードします。

MCPサーバーを介してコードを実行する

python examples/run_code.py

データセットを一度マウントして再利用する

python examples/mount_and_run.py

これは mount_file でCSVをマウントし、run_code 内でURLを再度指定せずに読み取ります。

セッションのワークスペースを調査する

python examples/inspect_workspace.py

これは、list_dir と preview_file ツールを使用して、コードが作成したファイルを閲覧する方法を示しています。

成果物を永続的に保存する

persist_artifact ツールは、output/ ディレクトリからのファイルを署名付きURLにアップロードします。

例（Python）：

await client.call_tool("persist_artifact", {
    "relative_path": "plots/plot.png",
    "presigned_url": "https://bucket.s3.amazonaws.com/...signature...",
})

成果物をダウンロードする

小さな成果物は直接取得できます。

curl -H "mcp-session-id: <your-session-id>" \
     http://localhost:9000/artifacts/plots/plot.png -o plot.png

📚 ドキュメント

利用可能なツールの詳細

エンドツーエンドのデモについては、examples/ ディレクトリを参照してください。

🤝 コントリビューション

コントリビューションは大歓迎です！PRIMSを改善するために、issueを開いたり、機能を提案したり、プルリクエストを送信したりすることができます。

もしこのプロジェクトが役に立った場合は、⭐ を付けてサポートを示してください。