Which integrations are available for this server?

Enables per-line GPU usage attribution and performance profiling for Python applications running on Apple hardware. Provides native integration with GitHub Copilot in VS Code to detect project structures and identify performance bottlenecks through automated profiling. Supports per-line GPU profiling and performance analysis for Python code utilizing NVIDIA GPUs. Provides structured access to comprehensive line-by-line CPU, memory, and GPU profiling for Python scripts and code snippets to identify leaks and performance hotspots.

How do I use Scalene-MCP?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Scalene-MCP profile main.py and show me the bottlenecks" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Scalene-MCP

by ptmorris05

Overview Schema Source Related Servers Discussions Admin

Python

Local

Scalene-MCP

A FastMCP v2 server providing LLMs with structured access to 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

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

As a Package

pip install scalene-mcp

Related MCP server: HPC-MCP

Quick Start: Running the Server

Development Mode

# Using uv
uv run scalene_mcp.server

# Using pip
python -m scalene_mcp.server

Production Mode

python -m scalene_mcp.server

🎯 Native Integration with LLM Agents

Works seamlessly with:

✅ GitHub Copilot - Direct integration
✅ Claude Code - Claude Code and Claude VSCode extension
✅ Cursor - All-in-one IDE
✅ Any MCP-compatible LLM client

Zero-Friction Setup (3 Steps)

Install
```
pip install scalene-mcp
```
Configure - Choose one method:
Automated (Recommended):
```
python scripts/setup_vscode.py
```
Interactive setup script auto-finds your editor and configures it.
Manual - GitHub Copilot:
```
// .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
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:

📚 Full docs: SETUP_VSCODE.md | QUICKSTART.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)

# Starts an MCP-compatible server on stdio
python -m scalene_mcp.server

2. With Claude Desktop

Configure in your claude_desktop_config.json:

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

Then restart Claude Desktop.

3. With HTTP/SSE Endpoint

# If using fastmcp with HTTP support
uv run --help  # Check FastMCP documentation for HTTP serving

4. With Environment Variables

# Configure via environment
export SCALENE_PYTHON_EXECUTABLE=python3.11
export SCALENE_TIMEOUT=30
python -m scalene_mcp.server

5. Programmatically

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:

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 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

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:

# 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):

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

Development

Running Tests

# 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

# Type checking
uv run mypy src/

# Linting
uv run ruff check src/

# Formatting
uv run ruff format src/

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass and coverage ≥ 85%
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:

@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

pip install -e .

Development

Prerequisites

Python 3.10+
uv (recommended) or pip

Setup

# 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

# 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

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

Example: Analyze Results

# 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:

# 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 - Using Copilot Chat with VSCode
Claude Code Setup - Using Claude Code VSCode extension
Cursor Setup - Using the Cursor IDE
General VSCode Setup - General VSCode configuration

API & Usage:

Tools Reference - Complete API documentation (7 tools)
Quick Start - 3-step setup and basic workflows
Examples - Real-world profiling examples

Development Roadmap

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

See 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]

Available Tools

7 tools

analyzeA

Analyze profiling data with flexible analysis types.

Args: profile_id: Profile ID from profile() metric_type: "all", "cpu", "memory", "gpu", "bottlenecks", "leaks", "file", "functions", "recommendations" top_n: Number of items to return (for rankings) cpu_threshold: Minimum CPU % to flag bottleneck memory_threshold_mb: Minimum MB to flag bottleneck filename: Required if metric_type="file", file to analyze

Returns: {metric_type, data, summary} structure varies by metric_type

ParametersJSON Schema

Name	Required	Default
`profile_id`	Yes
`metric_type`	No	all
`top_n`	No
`cpu_threshold`	No
`memory_threshold_mb`	No
`filename`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It describes analysis as a read-like operation without side effects, but does not explicitly state non-destructiveness or address auth requirements, rate limits, or other behavioral traits. The return structure is outlined, but not all possible variations are detailed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with a clear purpose followed by a structured Args/Returns section. It is concise without extraneous words, though the parameter list could be slightly more streamlined.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, varied return structures), the description covers parameter semantics and basic return format. However, it lacks details on how each metric_type affects the output and does not reference sibling tools for context, leaving some gaps for full understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining each parameter: profile_id, metric_type with allowed values, top_n, thresholds, and conditional filename. It adds constraints and context not present in the input schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool analyzes profiling data with flexible analysis types. It lists specific metric_type options and references the profile() tool for input, distinguishing it from siblings like compare_profiles or list_profiles.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool should be used after obtaining a profile_id from profile(), but does not explicitly say when to use versus alternatives like compare_profiles. No exclusions or when-not-to-use guidance are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

compare_profilesA

Compare two profiles to measure optimization impact.

Args: before_id: Profile ID from original code after_id: Profile ID from optimized code

Returns: {runtime_change_pct, memory_change_pct, improvements, regressions, summary_text}

ParametersJSON Schema

Name	Required	Description	Default
`before_id`	Yes
`after_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool compares two profiles (non-destructive, read operation) and returns a structured result with fields like runtime_change_pct and memory_change_pct. It does not discuss permissions, errors, or side effects, but the nature of the tool suggests no destructive behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a one-sentence purpose statement followed by parameter descriptions and return fields. Every sentence adds value, and it is front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (comparison with multiple metrics) and the existence of an output schema, the description adequately covers the purpose, parameters, and return structure. It does not explain all fields in detail, but the output schema presumably provides those details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaning by labeling 'before_id' as from original code and 'after_id' from optimized code. However, it does not specify format, constraints (e.g., must exist), or validation rules beyond the schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Compare two profiles to measure optimization impact.' It uses a specific verb ('compare') and resource ('profiles'), and it distinguishes itself from sibling tools like 'profile' (which likely runs profiling) and 'list_profiles' (which lists profiles).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use it (after obtaining two profile IDs, typically before and after optimization) and provides parameter roles ('before_id from original code', 'after_id from optimized code'). It does not explicitly state when not to use or mention alternatives, but the context from sibling names helps differentiate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_project_rootA

Get the detected project root and structure type.

Returns: {root, type, markers_found}

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries burden. It discloses return format {root, type, markers_found} which adds value, but could explicitly state read-only nature and lack of side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, no wasted words, front-loaded with purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and no annotations, the description adequately specifies the return value and purpose. Could mention that no input is required.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has no parameters (100% coverage trivial). Baseline score of 4 as per guidelines for 0 parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states 'Get the detected project root and structure type' with clear verb and resource. It distinguishes from siblings like analyze or list_profiles, though no explicit differentiation is given.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like set_project_context or list_project_files. The description only states what it does.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_profilesA

List all captured profiles in this session.

Returns: [profile_id, ...]

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description states it returns a list of profile IDs, which is adequate for a simple listing operation. However, it does not disclose potential side effects (likely none), authorization needs, or any limitations like pagination. With no annotations, the description carries the full burden, and it meets minimal expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, using two sentences to convey purpose and return format. No extraneous information, front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple zero-parameter listing tool, the description covers the essential purpose and output format. With an output schema existing (though not provided), the return type is covered. It is complete enough for the tool's simplicity, though could mention if only available for current session scope.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters (schema coverage 100% for empty params). The description adds value by explaining the return format, which goes beyond the schema. According to guidelines, 0 parameters warrant a baseline of 4, and the description compensates adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists all captured profiles in the session and specifies the return format (list of profile IDs). It is specific with verb 'list' and resource 'profiles', but does not differentiate itself from sibling tools like 'profile' or 'compare_profiles'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives (e.g., 'profile' for a single profile, 'compare_profiles' for comparisons). It does not mention any prerequisites or contexts where listing is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_project_filesA

List project files matching pattern, relative to project root.

Args: pattern: Glob pattern (*.py, src/**, etc.) max_depth: Maximum directory depth to search exclude_patterns: Comma-separated patterns to exclude

Returns: [relative_path, ...] sorted alphabetically

ParametersJSON Schema

Name	Required	Default
`pattern`	No	*.py
`max_depth`	No
`exclude_patterns`	No	.git,__pycache__,node_modules,.venv,venv

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full burden. It discloses the return format (sorted relative paths) and parameters, but lacks details on side effects, permissions, performance, or handling of symlinks/hidden files. Adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (two sentences plus Args) with no fluff. Primary purpose is front-loaded, and the Args section is structured for readability. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and presence of output schema (implied from description), the description covers the main functionality and return format. It could mention behavior for empty results or error cases, but overall complete for typical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It explains 'pattern' as glob, 'max_depth' as maximum depth, and 'exclude_patterns' as comma-separated patterns, adding meaning beyond schema defaults and types. Only minor omission: no mention of default excludes like .git.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'list' and the resource 'project files' with a specific scope 'matching pattern, relative to project root'. It distinguishes from sibling tools by specifying file listing, which none of the siblings do.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing to list project files with glob patterns, but does not explicitly state when to use versus alternatives or provide exclusions. Since siblings are not file-listing tools, the intended use is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

profileA

Profile Python code using Scalene.

Args: type: "script" (profile a file) or "code" (profile code snippet) script_path: Required if type="script". Path to Python script code: Required if type="code". Python code to execute cpu_only: Skip memory/GPU profiling include_memory: Profile memory allocations include_gpu: Profile GPU usage (requires NVIDIA GPU) reduced_profile: Show only lines >1% CPU or >100 allocations profile_only: Comma-separated paths to include (e.g., "myapp") profile_exclude: Comma-separated paths to exclude (e.g., "test,vendor") use_virtual_time: Measure CPU time excluding I/O wait cpu_percent_threshold: Minimum CPU % to report malloc_threshold: Minimum allocation bytes to report script_args: Command-line arguments for the script

Returns: {profile_id, summary, text_summary}

ParametersJSON Schema

Name	Required	Description	Default
`type`	Yes
`script_path`	No
`code`	No
`cpu_only`	No
`include_memory`	No
`include_gpu`	No
`reduced_profile`	No
`profile_only`	No
`profile_exclude`	No
`use_virtual_time`	No
`cpu_percent_threshold`	No
`malloc_threshold`	No
`script_args`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses behavioral traits: profiling mode via 'type', optional exclusions (cpu_only, include_*), thresholds, and return type. It does not mention permissions or side effects, but is transparent about options.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear opening sentence and bullet list of parameters. It is slightly verbose but efficiently conveys information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 13 parameters and output schema, the description covers input semantics and return structure. It lacks guidance on error scenarios or performance implications, but is sufficient for typical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description fully compensates by explaining each parameter's purpose concisely (e.g., 'cpu_only: Skip memory/GPU profiling'). This adds meaning beyond parameter names and types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool profiles Python code using Scalene, a specific verb-resource pairing. It distinguishes from siblings like analyze and compare_profiles.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lists parameters but offers no explicit guidance on when to use this tool versus siblings. Usage context is implied by the tool name, but not elaborated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_project_contextA

Explicitly set the project root (overrides auto-detection).

Use this if auto-detection fails or gives wrong path.

Args: project_root: Absolute path to project root

Returns: {project_root, status}

ParametersJSON Schema

Name	Required	Description	Default
`project_root`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations; description mentions override behavior and returns structure, but lacks details on persistence or side effects. Adequate for simple setter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Very concise with purpose, usage, args, and returns. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter setter with output schema, description fully covers purpose, usage, parameter meaning, and return value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema only gives type string; description adds 'absolute path' clarification, compensating for 0% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it sets the project root, overriding auto-detection. Differentiates from sibling 'get_project_root' which reads.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to use when auto-detection fails or gives wrong path, providing clear when-to-use context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

7 tool updatesv0.1.0Jan 31, 2026
- First observedanalyze
- First observedcompare_profiles
- First observedget_project_root
- First observedlist_profiles
- First observedlist_project_files
- First observedprofile
- First observedset_project_context

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored 2026-05-09 07:35 across 7 tools

Disambiguation5/5

Each tool targets a distinct action: creating profiles, listing them, analyzing, comparing, and managing project context. No two tools have overlapping responsibilities, and descriptions clearly differentiate their purposes.

Naming Consistency4/5

All tool names use snake_case and follow a verb or verb_noun pattern. However, 'analyze' and 'profile' are single-word verbs while others are multi-word, which is a minor inconsistency but still clear.

Tool Count5/5

With 7 tools, the server covers the essential profiling workflow: creation, listing, analysis, comparison, and project management. This count is well-scoped without being excessive or insufficient.

Completeness5/5

The tool surface covers the full lifecycle of profiling: profile creation, listing, detailed analysis, comparison, project file selection, and root configuration. No critical gaps are apparent for typical usage.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

mcp AOAuth
io.scorecard
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
RAG Systems Monitoring Testing & QA Tools
3
TokenOracle
com.guffeyholdings
Hosted MCP server for LLM cost estimation, model comparison, and budget-aware routing.
Finance Monitoring
2
Polar SignalsOAuth
com.polarsignals.api
The Polar Signals MCP server enables AI assistants to connect directly with performance profiling data, allowing users to analyze application performance through natural language queries. Key capabilities include querying CPU performance and memory usage, exploring profiling metadata like profile types and labels, and providing AI-driven code optimization suggestions directly within development environments like Claude Code or Cursor.
Monitoring Developer Tools Observability
2
jumpcloud-genaiOAuth
com.jumpcloud
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Cloud Platforms Security Developer Tools
2

Related MCP Servers

FastMCP
RAG Systems Autonomous Agents
wanderingnature
A
license
Not graded
quality
D
maintenance
FastMCP is a comprehensive MCP server allowing secure and standardized data and functionality exposure to LLM applications, offering resources, tools, and prompt management for efficient LLM interactions.
Updated 2 years ago (2025-01-24 20:07 UTC)
3
MIT
HPC-MCP
TomMelt
A
license
B
quality
D
maintenance
A server that provides Model Control Protocol (MCP) tools for High Performance Computing, designed to integrate with Large Language Models in IDEs like Cursor and VSCode for debugging and other HPC tasks.
Updated a year ago (2025-09-26 13:58 UTC)
1
3
MIT
FastMCP Server
Developer Tools
jamesbspencer
A
license
Not graded
quality
B
maintenance
A high-performance personal Model Context Protocol (MCP) server built with the FastMCP Python framework.
Updated 2 months ago (2026-07-13 00:02 UTC)
MIT
GreenCodeMCP
Developer Tools Code Analysis
DaoudiAmir
A
license
Not graded
quality
B
maintenance
An MCP server that detects energy anti-patterns in Python code, retrieves optimization examples, suggests refactoring, validates correctness, and benchmarks resource gains, integrating with VS Code, Cursor, and Windsurf.
Updated 2 months ago (2026-07-15 10:13 UTC)
MIT

Scalene-MCP

Installation

Prerequisites

From Source

As a Package

Quick Start: Running the Server

Development Mode

Production Mode

🎯 Native Integration with LLM Agents

Zero-Friction Setup (3 Steps)

Start Profiling Immediately

Available Serving Methods (FastMCP)

1. Standard Server (Default)

2. With Claude Desktop

3. With HTTP/SSE Endpoint

4. With Environment Variables

5. Programmatically

Programmatic Usage

Overview

What Scalene-MCP Does

What Scalene-MCP Doesn't Do

Key Features

Available Tools (7 Consolidated Tools)

Discovery (3 tools)

Profiling (1 unified tool)

Analysis (1 mega tool)

Comparison & Storage (2 tools)

Configuration

Profiling Options

Environment Variables

Architecture

Components

Data Flow

Troubleshooting

GPU Permission Error

Profile Not Found

Timeout Issues

Development

Running Tests

Code Quality

Contributing

License

Citation

Support

Manual Installation

Development

Prerequisites

Setup

Project Structure

Usage

Running the Server

Example: Profile a Script

Example: Analyze Results

Testing

Code Quality

Development Phases

Documentation

Development Roadmap

Contributing

License

Links

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers