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 框架
• 模型上下文协议