Scalene MCP

🚀 Scalene-MCP

Scalene-MCPは、PythonパッケージやC/C++バインディングの包括的なCPU、GPU、メモリプロファイリング機能を提供するFastMCP v2サーバーです。これにより、LLMはScaleneの機能に構造化されたアクセスが可能になります。

🚀 クイックスタート

サーバーの起動

開発モード

# uvを使用する場合
uv run scalene_mcp.server

# pipを使用する場合
python -m scalene_mcp.server

本番モード

python -m scalene_mcp.server

✨ 主な機能

• 完全なCPUプロファイリング：Python/Cの行ごとの時間、システム時間、CPU使用率を提供します。
• メモリプロファイリング：行ごとのピーク/平均メモリ使用量を測定し、速度メトリクスを用いたメモリリーク検出が可能です。
• GPUプロファイリング：NVIDIAとAppleのGPUをサポートし、行ごとのGPU使用量を追跡します。
• 高度な分析：スタックトレース、ボトルネックの特定、パフォーマンス改善の提案を行います。
• プロファイル比較：実行間のパフォーマンスの変化を追跡します。
• LLM最適化：構造化されたJSON出力、詳細の前に要約を提供し、コンテキストに応じたフォーマットを使用します。

📦 インストール

前提条件

• Python 3.10以上
• uv（推奨）またはpip

ソースからのインストール

git clone https://github.com/plasma-umass/scalene-mcp.git
cd scalene-mcp
uv venv
uv sync

パッケージとしてのインストール

pip install scalene-mcp

💻 使用例

基本的な使用法

from scalene_mcp.profiler import ScaleneProfiler
import asyncio

async def main():
    profiler = ScaleneProfiler()
    
    # スクリプトのプロファイリング
    result = await profiler.profile(
        type="script",
        script_path="fibonacci.py",
        include_memory=True,
        include_gpu=False
    )
    
    print(f"Profile ID: {result['profile_id']}")
    print(f"Peak memory: {result['summary'].get('total_memory_mb', 'N/A')}MB")
    
asyncio.run(main())

高度な使用法

# サーバーをプログラムで作成して実行
from fastmcp import Server

server = create_scalene_server()
# 設定と起動...

📚 ドキュメント

利用可能なサービング方法 (FastMCP)

Scalene-MCPは、FastMCPの組み込みサービング機能を使用して複数の方法でサービングできます。

1. 標準サーバー (デフォルト)

# stdio上でMCP互換サーバーを起動
python -m scalene_mcp.server

2. Claude Desktopとの連携

claude_desktop_config.jsonで設定します。

{
  "mcpServers": {
    "scalene": {
      "command": "python",
      "args": ["-m", "scalene_mcp.server"]
    }
  }
}

その後、Claude Desktopを再起動します。

3. HTTP/SSEエンドポイントとの連携

# HTTPサポート付きのfastmcpを使用する場合
uv run --help  # HTTPサービングに関するFastMCPドキュメントを参照

4. 環境変数を使用した設定

# 環境変数で設定
export SCALENE_PYTHON_EXECUTABLE=python3.11
export SCALENE_TIMEOUT=30
python -m scalene_mcp.server

5. プログラムによる使用

from fastmcp import Server

# プログラムでサーバーを作成して実行
server = create_scalene_server()
# 設定と起動...

構成

プロファイリングオプション

統一されたprofile()ツールは、以下のオプションをサポートしています。

環境変数

• SCALENE_CPU_PERCENT_THRESHOLD：デフォルトのCPU閾値を上書きします。
• SCALENE_MALLOC_THRESHOLD：デフォルトのメモリ割り当て閾値を上書きします。

アーキテクチャ

コンポーネント

• ScaleneProfiler：Scalene CLIの非同期ラッパー
• ProfileParser：ScaleneのJSON出力を構造化モデルに変換
• ProfileAnalyzer：洞察とホットスポットを抽出
• ProfileComparator：プロファイルを比較して回帰を検出
• FastMCP Server：MCPプロトコルを介してツールを公開

データフロー

Python Script
    ↓
ScaleneProfiler (subprocess)
    ↓
Scalene CLI (--json)
    ↓
Temp JSON File
    ↓
ProfileParser
    ↓
Pydantic Models (ProfileResult)
    ↓
Analyzer / Comparator
    ↓
MCP Tools
    ↓
LLM Client

🔧 技術詳細

トラブルシューティング

GPU権限エラー

GPUを使用してプロファイリングする際にPermissionErrorが表示された場合：

# テスト環境でGPUプロファイリングを無効にする
result = await profiler.profile(
    type="script",
    script_path="script.py",
    include_gpu=False
)

プロファイルが見つからない

プロファイルはサーバーセッション中にメモリに保存されます。永続化するには、ストレージインターフェースを実装します。

タイムアウト問題

タイムアウトパラメータを調整します（プロファイラーを直接使用する場合）：

result = await profiler.profile(
    type="script",
    script_path="slow_script.py"
)

開発

テストの実行

# カバレッジ付きですべてのテストを実行
uv run pytest -v --cov=src/scalene_mcp

# 特定のテストファイルを実行
uv run pytest tests/test_profiler.py -v

# カバレッジレポート付きで実行
uv run pytest --cov=src/scalene_mcp --cov-report=html

コード品質

# 型チェック
uv run mypy src/

# リンティング
uv run ruff check src/

# フォーマット
uv run ruff format src/

開発手順

前提条件

• Python 3.10以上
• uv（推奨）またはpip

セットアップ

# 依存関係のインストール
uv sync

# テストの実行
just test

# カバレッジ付きでテストを実行
just test-cov

# リンティングとフォーマット
just lint
just format

# 型チェック
just typecheck

# 完全ビルド (sync + lint + typecheck + test)
just build

プロジェクト構造

scalene-mcp/
├── src/scalene_mcp/     # メインパッケージ
│   ├── server.py        # FastMCPサーバーとツール/リソース/プロンプト
│   ├── models.py        # Pydanticデータモデル
│   ├── profiler.py      # Scalene実行ラッパー
│   ├── parser.py        # JSON出力パーサー
│   ├── analyzer.py      # 分析エンジン
│   ├── comparator.py    # プロファイル比較
│   ├── recommender.py   # 最適化提案
│   ├── storage.py       # プロファイルの永続化
│   └── utils.py         # 共有ユーティリティ
├── tests/               # テストスイート (100%カバレッジ目標)
│   ├── fixtures/        # テストデータ
│   │   ├── profiles/    # サンプルプロファイル出力
│   │   └── scripts/     # テスト用Pythonスクリプト
│   └── conftest.py      # 共有テストフィクスチャ
├── examples/            # 使用例
├── docs/                # ドキュメント
├── pyproject.toml       # プロジェクト構成
├── justfile             # タスクランナーコマンド
└── README.md            # このファイル

利用方法

サーバーの実行

# 自動リロード付きの開発モード
fastmcp dev src/scalene_mcp/server.py

# 本番モード
fastmcp run src/scalene_mcp/server.py

# MCP設定にインストール
fastmcp install src/scalene_mcp/server.py

例: スクリプトのプロファイリング

# MCPクライアントを通じて
result = await client.call_tool(
    "profile",
    arguments={
        "script_path": "my_script.py",
        "cpu": True,
        "memory": True,
        "gpu": False,
    }
)

例: 結果の分析

# 分析と提案を取得
analysis = await client.call_tool(
    "analyze",
    arguments={"profile_id": result["profile_id"]}
)

テスト

このプロジェクトは、包括的なテストスイートを使用して100%のテストカバレッジを維持しています。

# すべてのテストを実行
uv run pytest

# カバレッジレポート付きで実行
uv run pytest --cov=src --cov-report=html

# 特定のテストファイルを実行
uv run pytest tests/test_server.py

# 詳細な出力で実行
uv run pytest -v

テストフィクスチャには、以下が含まれます。

• サンプルプロファイリングスクリプト（フィボナッチ、メモリ集中型、リークのあるもの）
• 現実的なScalene JSON出力
• エッジケースとエラー条件

コード品質

このプロジェクトは、厳格なコード品質基準に従っています。

• 型安全性：100% mypyの厳格モードに準拠
• リンティング：包括的なルールを持つruffを使用
• テスト：100%のカバレッジ要件
• スタイル：洗練された現代的なドキュメント、最小限の機能的な絵文字の使用
• パターン：FastMCPのベストプラクティスを全体に適用

開発フェーズ

現在の状態: フェーズ1.1 - プロジェクトセットアップ ✓

ドキュメント

エディターセットアップガイド

• GitHub Copilotセットアップ - Copilot ChatをVSCodeで使用する
• Claude Codeセットアップ - Claude CodeのVSCode拡張機能を使用する
• Cursorセットアップ - Cursor IDEを使用する
• 一般的なVSCodeセットアップ - 一般的なVSCodeの設定

APIと使用方法

• ツールリファレンス - 完全なAPIドキュメント (7つのツール)
• クイックスタート - 3ステップのセットアップと基本的なワークフロー
• 例 - 実世界のプロファイリング例

開発ロードマップ

1. フェーズ1：プロジェクトセットアップとインフラストラクチャ ✓
2. フェーズ2：コアデータモデル (進行中)
3. フェーズ3：プロファイラーの統合
4. フェーズ4：分析と洞察
5. フェーズ5：比較機能
6. フェーズ6：リソースの実装
7. フェーズ7：プロンプトとワークフロー
8. フェーズ8：テストと品質
9. フェーズ9：ドキュメント
10. フェーズ10：仕上げとリリース

詳細なロードマップはdevelopment-plan.mdを参照してください。

📄 ライセンス

[ライセンス未定]

引用

Scalene-MCPを研究で使用する場合は、このプロジェクトとScaleneの両方を引用してください。

@software{scalene_mcp,
  title={Scalene-MCP: LLM-Friendly Profiling Server},
  year={2026}
}

@inproceedings{berger2020scalene,
  title={Scalene: Scripting-Language Aware Profiling for Python},
  author={Berger, Emery},
  year={2020}
}

サポート

• 問題報告：バグ報告や機能要求はGitHubのIssuesを使用してください。
• ディスカッション：質問やアイデアについてはGitHubのDiscussionsを使用してください。
• ドキュメント：docs/ディレクトリを参照してください。

Pythonパフォーマンスコミュニティのために愛を込めて作られました。

手動インストール

pip install -e .