# Scalene-MCP

A FastMCP v2 server providing LLMs with structured access to [Scalene](https://github.com/plasma-umass/scalene)'s comprehensive CPU, GPU, and memory profiling capabilities for Python packages and C/C++ bindings.

## Installation

### Prerequisites

- Python 3.10+
- uv (recommended) or pip

### From Source

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

### As a Package

```bash
pip install scalene-mcp
```

## Quick Start: Running the Server

### Development Mode

```bash
# Using uv
uv run scalene_mcp.server

# Using pip
python -m scalene_mcp.server
```

### Production Mode

```bash
python -m scalene_mcp.server
```

## 🎯 Native Integration with LLM Agents

**Works seamlessly with:**
- ✅ **[GitHub Copilot](SETUP_GITHUB_COPILOT.md)** - Direct integration
- ✅ **[Claude Code](SETUP_CLAUDE.md)** - Claude Code and Claude VSCode extension
- ✅ **[Cursor](SETUP_CURSOR.md)** - All-in-one IDE
- ✅ **Any MCP-compatible LLM client**

### Zero-Friction Setup (3 Steps)

1. **Install**
   ```bash
   pip install scalene-mcp
   ```

2. **Configure** - Choose one method:
   
   **Automated (Recommended):**
   ```bash
   python scripts/setup_vscode.py
   ```
   Interactive setup script auto-finds your editor and configures it.
   
   **Manual - GitHub Copilot:**
   ```json
   // .vscode/settings.json
   {
     "github.copilot.chat.mcp.servers": {
       "scalene": {
         "command": "uv",
         "args": ["run", "-m", "scalene_mcp.server"]
       }
     }
   }
   ```
   
   **Manual - Claude Code / Cursor:** See editor-specific setup guides

3. **Restart VSCode/Cursor** and start profiling!

### Start Profiling Immediately

Open any Python project and ask your LLM:

```
"Profile main.py and show me the bottlenecks"
```

The LLM automatically:
- 🔍 Detects your project structure
- 📄 Finds and profiles your code
- 📊 Analyzes CPU, memory, GPU usage
- 💡 Suggests optimizations

**No path thinking. No manual configuration. Zero friction.**

📚 **Editor-Specific Setup:**
- [GitHub Copilot Setup](SETUP_GITHUB_COPILOT.md)
- [Claude Code Setup](SETUP_CLAUDE.md)
- [Cursor Setup](SETUP_CURSOR.md)

📚 **Full docs:** [SETUP_VSCODE.md](SETUP_VSCODE.md) | [QUICKSTART.md](QUICKSTART.md) | [TOOLS_REFERENCE.md](TOOLS_REFERENCE.md)

### Available Serving Methods (FastMCP)

Scalene-MCP can be served in multiple ways using FastMCP's built-in serving capabilities:

#### 1. **Standard Server (Default)**
```bash
# Starts an MCP-compatible server on stdio
python -m scalene_mcp.server
```

#### 2. **With Claude Desktop**
Configure in your `claude_desktop_config.json`:

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

Then restart Claude Desktop.

#### 3. **With HTTP/SSE Endpoint**
```bash
# If using fastmcp with HTTP support
uv run --help  # Check FastMCP documentation for HTTP serving
```

#### 4. **With Environment Variables**
```bash
# Configure via environment
export SCALENE_PYTHON_EXECUTABLE=python3.11
export SCALENE_TIMEOUT=30
python -m scalene_mcp.server
```

#### 5. **Programmatically**
```python
from fastmcp import Server

# Create and run server programmatically
server = create_scalene_server()
# Configure and start...
```

## Programmatic Usage

Use Scalene-MCP directly in your Python code:

```python
from scalene_mcp.profiler import ScaleneProfiler
import asyncio

async def main():
    profiler = ScaleneProfiler()
    
    # Profile a script
    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())
```

## Overview

Scalene-MCP transforms Scalene's powerful profiling output into an LLM-friendly format through a clean, minimal set of well-designed tools. Get detailed performance insights without images or excessive context overhead.

### What Scalene-MCP Does

- ✅ **Profile Python scripts** with full Scalene feature set
- ✅ **Analyze profiles** for hotspots, bottlenecks, memory leaks
- ✅ **Compare profiles** to detect regressions
- ✅ **Pass arguments** to profiled scripts
- ✅ **Structured output** in JSON format for LLMs
- ✅ **Async execution** for non-blocking profiling

### What Scalene-MCP Doesn't Do

- ❌ **In-process profiling** (`Scalene.start()`/`stop()`) - uses subprocess instead for isolation
- ❌ **Process attachment** (`--pid` based profiling) - profiles scripts, not running processes
- ❌ **Single-function profiling** - designed for complete script analysis

**Note**: The subprocess-based approach was chosen for reliability and simplicity. LLM workflows typically profile complete scripts, which is a perfect fit. See [SCALENE_MODES_ANALYSIS.md](./SCALENE_MODES_ANALYSIS.md) for detailed scope analysis.

### Key Features

- **Complete CPU profiling**: Line-by-line Python/C time, system time, CPU utilization
- **Memory profiling**: Peak/average memory per line, leak detection with velocity metrics
- **GPU profiling**: NVIDIA and Apple GPU support with per-line attribution
- **Advanced analysis**: Stack traces, bottleneck identification, performance recommendations
- **Profile comparison**: Track performance changes across runs
- **LLM-optimized**: Structured JSON output, summaries before details, context-aware formatting

## Available Tools (7 Consolidated Tools)

Scalene-MCP provides a clean, LLM-optimized set of 7 tools:

### Discovery (3 tools)
- **get_project_root()** - Auto-detect project structure
- **list_project_files(pattern, max_depth)** - Find files by glob pattern
- **set_project_context(project_root)** - Override auto-detection

### Profiling (1 unified tool)
- **profile(type, script_path/code, ...)** - Profile scripts or code snippets
  - `type="script"` for script profiling
  - `type="code"` for code snippet profiling

### Analysis (1 mega tool)
- **analyze(profile_id, metric_type, ...)** - 9 analysis modes in one tool:
  - `metric_type="all"` - Comprehensive analysis
  - `metric_type="cpu"` - CPU hotspots
  - `metric_type="memory"` - Memory hotspots
  - `metric_type="gpu"` - GPU hotspots
  - `metric_type="bottlenecks"` - Performance bottlenecks
  - `metric_type="leaks"` - Memory leak detection
  - `metric_type="file"` - File-level metrics
  - `metric_type="functions"` - Function-level metrics
  - `metric_type="recommendations"` - Optimization suggestions

### Comparison & Storage (2 tools)
- **compare_profiles(before_id, after_id)** - Compare two profiles
- **list_profiles()** - View all captured profiles

**Full reference**: See [TOOLS_REFERENCE.md](TOOLS_REFERENCE.md)

## Configuration

### Profiling Options

The unified `profile()` tool supports these options:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `type` | str | required | "script" or "code" |
| `script_path` | str | None | Required if type="script" |
| `code` | str | None | Required if type="code" |
| `include_memory` | bool | true | Profile memory |
| `include_gpu` | bool | false | Profile GPU usage |
| `cpu_only` | bool | false | Skip memory/GPU profiling |
| `reduced_profile` | bool | false | Only report high-activity lines |
| `cpu_percent_threshold` | float | 1.0 | Minimum CPU% to report |
| `malloc_threshold` | int | 100 | Minimum allocation size (bytes) |
| `profile_only` | str | "" | Profile only paths containing this |
| `profile_exclude` | str | "" | Exclude paths containing this |
| `use_virtual_time` | bool | false | Use virtual time instead of wall time |
| `script_args` | list | [] | Command-line arguments for the script |

### Environment Variables

- `SCALENE_CPU_PERCENT_THRESHOLD`: Override default CPU threshold
- `SCALENE_MALLOC_THRESHOLD`: Override default malloc threshold

## Architecture

### Components

- **ScaleneProfiler**: Async wrapper around Scalene CLI
- **ProfileParser**: Converts Scalene JSON to structured models
- **ProfileAnalyzer**: Extracts insights and hotspots
- **ProfileComparator**: Compares profiles for regressions
- **FastMCP Server**: Exposes tools via MCP protocol

### Data Flow

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

## Troubleshooting

### GPU Permission Error

If you see `PermissionError` when profiling with GPU:

```python
# Disable GPU profiling in test environments
result = await profiler.profile(
    type="script",
    script_path="script.py",
    include_gpu=False
)
```

### Profile Not Found

Profiles are stored in memory during the server session. For persistence, implement the storage interface.

### Timeout Issues

Adjust the timeout parameter (if using profiler directly):

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

## Development

### Running Tests

```bash
# All tests with coverage
uv run pytest -v --cov=src/scalene_mcp

# Specific test file
uv run pytest tests/test_profiler.py -v

# With coverage report
uv run pytest --cov=src/scalene_mcp --cov-report=html
```

### Code Quality

```bash
# Type checking
uv run mypy src/

# Linting
uv run ruff check src/

# Formatting
uv run ruff format src/
```

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass and coverage ≥ 85%
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Citation

If you use Scalene-MCP in research, please cite both this project and Scalene:

```bibtex
@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}
}
```

## Support

- **Issues**: GitHub Issues for bug reports and feature requests
- **Discussions**: GitHub Discussions for questions and ideas
- **Documentation**: See `docs/` directory

---

Made with ❤️ for the Python performance community.

### Manual Installation

```bash
pip install -e .
```

## Development

### Prerequisites
- Python 3.10+
- uv (recommended) or pip

### Setup

```bash
# Install dependencies
uv sync

# Run tests
just test

# Run tests with coverage
just test-cov

# Lint and format
just lint
just format

# Type check
just typecheck

# Full build (sync + lint + typecheck + test)
just build
```

### Project Structure

```
scalene-mcp/
├── src/scalene_mcp/     # Main package
│   ├── server.py        # FastMCP server with tools/resources/prompts
│   ├── models.py        # Pydantic data models
│   ├── profiler.py      # Scalene execution wrapper
│   ├── parser.py        # JSON output parser
│   ├── analyzer.py      # Analysis engine
│   ├── comparator.py    # Profile comparison
│   ├── recommender.py   # Optimization recommendations
│   ├── storage.py       # Profile persistence
│   └── utils.py         # Shared utilities
├── tests/               # Test suite (100% coverage goal)
│   ├── fixtures/        # Test data
│   │   ├── profiles/    # Sample profile outputs
│   │   └── scripts/     # Test Python scripts
│   └── conftest.py      # Shared test fixtures
├── examples/            # Usage examples
├── docs/                # Documentation
├── pyproject.toml       # Project configuration
├── justfile             # Task runner commands
└── README.md            # This file
```

## Usage

### Running the Server

```bash
# Development mode with auto-reload
fastmcp dev src/scalene_mcp/server.py

# Production mode
fastmcp run src/scalene_mcp/server.py

# Install to MCP config
fastmcp install src/scalene_mcp/server.py
```

### Example: Profile a Script

```python
# Through MCP client
result = await client.call_tool(
    "profile",
    arguments={
        "script_path": "my_script.py",
        "cpu": True,
        "memory": True,
        "gpu": False,
    }
)
```

### Example: Analyze Results

```python
# Get analysis and recommendations
analysis = await client.call_tool(
    "analyze",
    arguments={"profile_id": result["profile_id"]}
)
```

## Testing

The project maintains 100% test coverage with comprehensive test suites:

```bash
# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov=src --cov-report=html

# Run specific test file
uv run pytest tests/test_server.py

# Run with verbose output
uv run pytest -v
```

Test fixtures include:
- Sample profiling scripts (fibonacci, memory-intensive, leaky)
- Realistic Scalene JSON outputs
- Edge cases and error conditions

## Code Quality

This project follows strict code quality standards:

- **Type Safety:** 100% mypy strict mode compliance
- **Linting:** ruff with comprehensive rules
- **Testing:** 100% coverage requirement
- **Style:** Sleek-modern documentation, minimal functional emoji usage
- **Patterns:** FastMCP best practices throughout

## Development Phases

Current Status: **Phase 1.1 - Project Setup** ✓

## Documentation

**Editor Setup Guides:**
- [GitHub Copilot Setup](SETUP_GITHUB_COPILOT.md) - Using Copilot Chat with VSCode
- [Claude Code Setup](SETUP_CLAUDE.md) - Using Claude Code VSCode extension
- [Cursor Setup](SETUP_CURSOR.md) - Using the Cursor IDE
- [General VSCode Setup](SETUP_VSCODE.md) - General VSCode configuration

**API & Usage:**
- [Tools Reference](TOOLS_REFERENCE.md) - Complete API documentation (7 tools)
- [Quick Start](QUICKSTART.md) - 3-step setup and basic workflows
- [Examples](examples/README.md) - Real-world profiling examples

## Development Roadmap

1. **Phase 1:** Project Setup & Infrastructure ✓
2. **Phase 2:** Core Data Models (In Progress)
3. **Phase 3:** Profiler Integration
4. **Phase 4:** Analysis & Insights
5. **Phase 5:** Comparison Features
6. **Phase 6:** Resources Implementation
7. **Phase 7:** Prompts & Workflows
8. **Phase 8:** Testing & Quality
9. **Phase 9:** Documentation
10. **Phase 10:** Polish & Release

See [development-plan.md](../development-plan.md) for detailed roadmap.

## Contributing

Contributions are welcome! Please ensure:
- All tests pass (`just test`)
- Linting passes (`just lint`)
- Type checking passes (`just typecheck`)
- Code coverage remains at 100%

## License

[License TBD]

## Links

- [Scalene Profiler](https://github.com/plasma-umass/scalene)
- [FastMCP Framework](https://github.com/jlowin/fastmcp)
- [Model Context Protocol](https://modelcontextprotocol.io/)