Scalene MCP

🚀 Scalene-MCP

Scalene-MCP 是一個 FastMCP v2 服務器，它為大語言模型（LLMs）提供了對 Scalene 全面的 CPU、GPU 和內存分析功能的結構化訪問，支持 Python 包和 C/C++ 綁定。

🚀 快速開始

啟動服務器

開發模式

# 使用 uv
uv run scalene_mcp.server

# 使用 pip
python -m scalene_mcp.server

生產模式

python -m scalene_mcp.server

與大語言模型代理的原生集成

無縫集成以下工具：

• ✅ GitHub Copilot - 直接集成
• ✅ Claude Code - Claude Code 和 Claude VSCode 擴展
• ✅ Cursor - 一體化集成開發環境（IDE）
• ✅ 任何支持 MCP 的大語言模型客戶端

零摩擦設置（3 個步驟）

1. 安裝

   pip install scalene-mcp
   

2. 配置 - 選擇一種方法：

   自動配置（推薦）：

   python scripts/setup_vscode.py
   

   交互式設置腳本會自動找到你的編輯器並進行配置。

   手動配置 - GitHub Copilot：

   // .vscode/settings.json
   {
     "github.copilot.chat.mcp.servers": {
       "scalene": {
         "command": "uv",
         "args": ["run", "-m", "scalene_mcp.server"]
       }
     }
   }
   

   手動配置 - Claude Code / Cursor： 請參閱特定編輯器的設置指南

3. 重啟 VSCode/Cursor 並開始分析！

立即開始分析

打開任何 Python 項目並向你的大語言模型提問：

"分析 main.py 並找出瓶頸"

大語言模型會自動執行以下操作：

• 🔍 檢測你的項目結構
• 📄 找到並分析你的代碼
• 📊 分析 CPU、內存和 GPU 使用情況
• 💡 提供優化建議

無需考慮路徑，無需手動配置，零摩擦。

📚 特定編輯器設置：

• GitHub Copilot 設置
• Claude Code 設置
• Cursor 設置

📚 完整文檔： SETUP_VSCODE.md | QUICKSTART.md | TOOLS_REFERENCE.md

可用的服務方法（FastMCP）

Scalene-MCP 可以使用 FastMCP 的內置服務功能以多種方式提供服務：

1. 標準服務器（默認）

# 在標準輸入輸出上啟動一個支持 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  # 查看 FastMCP 文檔以瞭解 HTTP 服務

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()
# 配置並啟動...

✨ 主要特性

• 完整的 CPU 分析：逐行分析 Python/C 時間、系統時間和 CPU 利用率。
• 內存分析：逐行分析峰值/平均內存使用情況，通過速度指標檢測內存洩漏。
• GPU 分析：支持 NVIDIA 和 Apple GPU，逐行分析 GPU 使用情況。
• 高級分析：提供堆棧跟蹤、瓶頸識別和性能優化建議。
• 分析結果比較：跟蹤不同運行之間的性能變化。
• 大語言模型優化：以結構化的 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"分析 ID: {result['profile_id']}")
    print(f"峰值內存: {result['summary'].get('total_memory_mb', 'N/A')}MB")
    
asyncio.run(main())

運行服務器示例

# 開發模式，支持自動重新加載
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"]}
)

📚 詳細文檔

可用工具（7 個整合工具）

Scalene-MCP 提供了一套簡潔、針對大語言模型優化的 7 個工具：

發現工具（3 個）

• get_project_root() - 自動檢測項目結構
• list_project_files(pattern, max_depth) - 通過 glob 模式查找文件
• set_project_context(project_root) - 覆蓋自動檢測結果

分析工具（1 個統一工具）

• profile(type, script_path/code, ...) - 分析腳本或代碼片段
  • type="script" 用於腳本分析
  • type="code" 用於代碼片段分析

分析工具（1 個強大工具）

• analyze(profile_id, metric_type, ...) - 一個工具包含 9 種分析模式：
  • metric_type="all" - 全面分析
  • metric_type="cpu" - CPU 熱點分析
  • metric_type="memory" - 內存熱點分析
  • metric_type="gpu" - GPU 熱點分析
  • metric_type="bottlenecks" - 性能瓶頸分析
  • metric_type="leaks" - 內存洩漏檢測
  • metric_type="file" - 文件級指標分析
  • metric_type="functions" - 函數級指標分析
  • metric_type="recommendations" - 優化建議

比較與存儲工具（2 個）

• compare_profiles(before_id, after_id) - 比較兩個分析結果
• list_profiles() - 查看所有捕獲的分析結果

完整參考： 請參閱 TOOLS_REFERENCE.md

配置

分析選項

統一的 profile() 工具支持以下選項：

環境變量

• SCALENE_CPU_PERCENT_THRESHOLD：覆蓋默認的 CPU 閾值
• SCALENE_MALLOC_THRESHOLD：覆蓋默認的內存分配閾值

架構

組件

• ScaleneProfiler：Scalene 命令行界面（CLI）的異步包裝器
• ProfileParser：將 Scalene 的 JSON 輸出轉換為結構化模型
• ProfileAnalyzer：提取分析結果和熱點信息
• ProfileComparator：比較分析結果以檢測性能迴歸
• FastMCP Server：通過 MCP 協議暴露工具

數據流

Python 腳本
    ↓
ScaleneProfiler（子進程）
    ↓
Scalene CLI（--json）
    ↓
臨時 JSON 文件
    ↓
ProfileParser
    ↓
Pydantic 模型（ProfileResult）
    ↓
分析器 / 比較器
    ↓
MCP 工具
    ↓
大語言模型客戶端

故障排除

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/

項目結構

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            # 本文件

開發階段

當前狀態：階段 1.1 - 項目設置 ✓

文檔

編輯器設置指南：

• GitHub Copilot 設置 - 在 VSCode 中使用 Copilot Chat
• Claude Code 設置 - 在 VSCode 中使用 Claude Code 擴展
• Cursor 設置 - 使用 Cursor 集成開發環境
• 通用 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 以獲取詳細的路線圖。

貢獻

歡迎貢獻代碼！請確保：

• 所有測試通過（just test）
• 代碼檢查通過（just lint）
• 類型檢查通過（just typecheck）
• 代碼覆蓋率保持在 100%

📄 許可證

[許可證待定]

引用

如果你在研究中使用 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 中報告 bug 和提出功能請求
• 討論交流：在 GitHub Discussions 中提問和分享想法
• 文檔查閱：請參閱 docs/ 目錄

為 Python 性能社區精心打造 ❤️

手動安裝

pip install -e .

開發

前提條件

• Python 3.10+
• uv（推薦）或 pip

設置

# 安裝依賴
uv sync

# 運行測試
just test

# 運行測試並生成覆蓋率報告
just test-cov

# 代碼檢查和格式化
just lint
just format

# 類型檢查
just typecheck

# 完整構建（同步 + 代碼檢查 + 類型檢查 + 測試）
just build

測試

項目通過全面的測試套件保持 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 最佳實踐

鏈接

• Scalene 分析器
• FastMCP 框架
• 模型上下文協議