pyspy-mcp: Instructions file for Codex

py-spy / pyspy-mcp workspace instructions

Project overview

This workspace now contains two things:

1. py-spy Rust source — a sampling profiler for Python programs.
2. src/pyspy_mcp/ — a Python MCP (Model Context Protocol) server that exposes py-spy based performance testing tools.

The Python package is intended for PyPI distribution. It depends on the published py-spy wheel for runtime, but during local development it will automatically use a py-spy binary built from the sibling Rust source (target/release/py-spy).

Directory layout

• src/pyspy/ — Rust source for py-spy.
  • src/pyspy/python_bindings/vX_Y_Z.rs — Auto-generated CPython struct bindings. Do not hand-edit.
  • src/pyspy/lib.rs, src/pyspy/main.rs — Library and CLI entry points.
  • src/pyspy/python_spy.rs, src/pyspy/sampler.rs — Core profiling/sampling logic.
• src/pyspy_mcp/ — Python MCP server.
  • server.py — FastMCP app and tool definitions.
  • tools.py — Wrappers that invoke py-spy and return results.
  • parser.py — Parsers for speedscope, raw, and dump JSON output.
  • process_util.py — Helper to list running Python processes.
  • py_spy_finder.py — Locates the py-spy binary (env var > local build > bundled > PATH).
• tests/pyspy_mcp/ — Unit and integration tests for the Python MCP server.
• tests/scripts/ — Python scripts used by the Rust integration tests and MCP integration tests.

Build, test, and publish

Rust (py-spy)

cargo build --release

Produces target/release/py-spy (Linux/macOS) or target/release/py-spy.exe (Windows).

Python MCP server

# Editable install (uses PyPI py-spy by default; local target/release build takes precedence if present)
pip install -e ".[dev]"

# Run the server
pyspy-mcp

# Run tests
python -m pytest tests/pyspy_mcp -v

If your environment has conflicting pytest plugins (e.g. hydra/omegaconf), run:

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest tests/pyspy_mcp -v