pyspy-mcp 0.1.0__tar.gz

pyspy_mcp-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Rust
+target/
+Cargo.lock
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+.eggs/
+dist/
+build/
+*.whl
+*.tar.gz
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Virtual environments
+venv/
+.env/
+.venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local overrides
+.env
+.pyspy-mcp-server.json
+.zcode/

pyspy_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pyspy-mcp-server contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyspy_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: pyspy-mcp
+Version: 0.1.0
+Summary: MCP server for Python performance testing with py-spy
+Project-URL: Homepage, https://github.com/LBurny/pyspy-mcp
+Project-URL: Repository, https://github.com/LBurny/pyspy-mcp
+Project-URL: Issues, https://github.com/LBurny/pyspy-mcp/issues
+Author: LBunny
+License: MIT
+License-File: LICENSE
+Keywords: mcp,performance,profiler,py-spy,python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=3.0
+Requires-Dist: psutil>=5.9
+Requires-Dist: py-spy>=0.4.2
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# py-spy MCP Server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes Python performance testing tools powered by [py-spy](https://github.com/benfred/py-spy).
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+![Python 3.10+](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white)
+![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-2ea44f)
+![tests passing](https://img.shields.io/badge/tests-passing-brightgreen)
+
+🌐 English | [简体中文](README.zh.md)
+
+**Profile Python in context.** Sample live processes, generate flamegraphs, dump stacks, and compare runs — all through MCP.
+
+## Features
+
+- **Profile by PID or command** — sample a running Python process or launch a new one directly.
+- **`record_profile`** — generate profiles in multiple formats:
+  - `speedscope` (interactive JSON)
+  - `flamegraph` (self-contained SVG)
+  - `raw` (stack-count text)
+  - `chrometrace` (Chrome DevTools timeline JSON)
+- **`dump_stacks`** — capture the current Python call stacks of a process as JSON or human-readable text.
+- **`list_python_processes`** — list running Python processes on the machine to pick a target.
+- **`analyze_profile`** — parse an existing profile and return the hottest frames.
+- **`compare_profiles`** — compare two speedscope profiles and show percentage changes.
+- **`top_profile`** — run a short `py-spy top` session and return a summary.
+  - On Windows, `py-spy top` cannot be captured through a pipe, so this tool falls back to a short raw recording and returns the hottest frames.
+- **Low-overhead sampling** — powered by [py-spy](https://github.com/benfred/py-spy); reads process memory without modifying or running inside the target process.
+- **Cross-platform** — works on Linux, macOS, and Windows (subject to OS permissions).
+- **Local-source friendly** — during development the server automatically prefers a `py-spy` binary built from the sibling Rust source (`src/pyspy/`).
+- **Optional native/C extension profiling** — enable `--native` where the platform supports it.
+- **GIL and idle filtering** — focus on active threads or GIL-holding threads.
+
+## Installation (from PyPI)
+
+Using `pip`:
+
+```bash
+pip install pyspy-mcp
+```
+
+Using `uv`:
+
+```bash
+uv pip install pyspy-mcp
+# or install as a global tool
+uv tool install pyspy-mcp
+```
+
+This will automatically install the compatible `py-spy` binary wheel for your platform.
+
+## Running with Claude Desktop / Claude Code
+
+Add the server as a **Local command** connector:
+
+```json
+{
+  "mcpServers": {
+    "pyspy": {
+      "command": "pyspy-mcp"
+    }
+  }
+}
+```
+
+Or run directly:
+
+```bash
+pyspy-mcp
+```
+
+The server speaks MCP over stdio.
+
+## Development (from source)
+
+If you want to use the local py-spy Rust source instead of the PyPI package:
+
+```bash
+# Build py-spy from the local Rust source
+cargo build --release
+
+# The binary will be at:
+#   target/release/py-spy        (Linux / macOS)
+#   target/release/py-spy.exe    (Windows)
+
+# Install the Python MCP package in editable mode
+pip install -e ".[dev]"
+
+# Or using uv
+uv pip install -e ".[dev]"
+
+# Run tests
+python -m pytest tests/pyspy_mcp -v
+```
+
+The server will automatically prefer a locally built binary at `target/release/py-spy[.exe]` over the `py-spy` installed from PyPI. You can also force a specific binary by setting the environment variable:
+
+```bash
+export PYSPY_MCP_BINARY=/path/to/py-spy
+```
+
+## Publishing to PyPI
+
+```bash
+python -m build
+python -m twine upload dist/*
+```
+
+The published wheel is a pure-Python `py3-none-any` package and depends on the upstream `py-spy` PyPI package. If you modify the Rust source and want to ship those changes, you will need to build platform-specific wheels (or bundle the rebuilt `py-spy` binary as package data).
+
+## Permissions
+
+- On Linux, profiling an existing PID usually requires `ptrace` permissions (`sudo` or `cap_sys_ptrace`).
+- On macOS, profiling often requires root due to System Integrity Protection (SIP).
+- On Windows, running as Administrator may be needed for some processes.
+
+## Configuration
+
+Set `PYSPY_MCP_BINARY` to override the bundled/development py-spy binary location.

pyspy_mcp-0.1.0/README.md

@@ -0,0 +1,119 @@
+# py-spy MCP Server
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes Python performance testing tools powered by [py-spy](https://github.com/benfred/py-spy).
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+![Python 3.10+](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white)
+![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-2ea44f)
+![tests passing](https://img.shields.io/badge/tests-passing-brightgreen)
+
+🌐 English | [简体中文](README.zh.md)
+
+**Profile Python in context.** Sample live processes, generate flamegraphs, dump stacks, and compare runs — all through MCP.
+
+## Features
+
+- **Profile by PID or command** — sample a running Python process or launch a new one directly.
+- **`record_profile`** — generate profiles in multiple formats:
+  - `speedscope` (interactive JSON)
+  - `flamegraph` (self-contained SVG)
+  - `raw` (stack-count text)
+  - `chrometrace` (Chrome DevTools timeline JSON)
+- **`dump_stacks`** — capture the current Python call stacks of a process as JSON or human-readable text.
+- **`list_python_processes`** — list running Python processes on the machine to pick a target.
+- **`analyze_profile`** — parse an existing profile and return the hottest frames.
+- **`compare_profiles`** — compare two speedscope profiles and show percentage changes.
+- **`top_profile`** — run a short `py-spy top` session and return a summary.
+  - On Windows, `py-spy top` cannot be captured through a pipe, so this tool falls back to a short raw recording and returns the hottest frames.
+- **Low-overhead sampling** — powered by [py-spy](https://github.com/benfred/py-spy); reads process memory without modifying or running inside the target process.
+- **Cross-platform** — works on Linux, macOS, and Windows (subject to OS permissions).
+- **Local-source friendly** — during development the server automatically prefers a `py-spy` binary built from the sibling Rust source (`src/pyspy/`).
+- **Optional native/C extension profiling** — enable `--native` where the platform supports it.
+- **GIL and idle filtering** — focus on active threads or GIL-holding threads.
+
+## Installation (from PyPI)
+
+Using `pip`:
+
+```bash
+pip install pyspy-mcp
+```
+
+Using `uv`:
+
+```bash
+uv pip install pyspy-mcp
+# or install as a global tool
+uv tool install pyspy-mcp
+```
+
+This will automatically install the compatible `py-spy` binary wheel for your platform.
+
+## Running with Claude Desktop / Claude Code
+
+Add the server as a **Local command** connector:
+
+```json
+{
+  "mcpServers": {
+    "pyspy": {
+      "command": "pyspy-mcp"
+    }
+  }
+}
+```
+
+Or run directly:
+
+```bash
+pyspy-mcp
+```
+
+The server speaks MCP over stdio.
+
+## Development (from source)
+
+If you want to use the local py-spy Rust source instead of the PyPI package:
+
+```bash
+# Build py-spy from the local Rust source
+cargo build --release
+
+# The binary will be at:
+#   target/release/py-spy        (Linux / macOS)
+#   target/release/py-spy.exe    (Windows)
+
+# Install the Python MCP package in editable mode
+pip install -e ".[dev]"
+
+# Or using uv
+uv pip install -e ".[dev]"
+
+# Run tests
+python -m pytest tests/pyspy_mcp -v
+```
+
+The server will automatically prefer a locally built binary at `target/release/py-spy[.exe]` over the `py-spy` installed from PyPI. You can also force a specific binary by setting the environment variable:
+
+```bash
+export PYSPY_MCP_BINARY=/path/to/py-spy
+```
+
+## Publishing to PyPI
+
+```bash
+python -m build
+python -m twine upload dist/*
+```
+
+The published wheel is a pure-Python `py3-none-any` package and depends on the upstream `py-spy` PyPI package. If you modify the Rust source and want to ship those changes, you will need to build platform-specific wheels (or bundle the rebuilt `py-spy` binary as package data).
+
+## Permissions
+
+- On Linux, profiling an existing PID usually requires `ptrace` permissions (`sudo` or `cap_sys_ptrace`).
+- On macOS, profiling often requires root due to System Integrity Protection (SIP).
+- On Windows, running as Administrator may be needed for some processes.
+
+## Configuration
+
+Set `PYSPY_MCP_BINARY` to override the bundled/development py-spy binary location.

pyspy_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "pyspy-mcp"
+version = "0.1.0"
+description = "MCP server for Python performance testing with py-spy"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "LBunny"},
+]
+keywords = ["mcp", "py-spy", "profiler", "python", "performance"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "fastmcp>=3.0",
+    "psutil>=5.9",
+    "pydantic>=2.0",
+    # PyPI-distributed py-spy command-line tool. The local source build is used
+    # automatically during development (see py_spy_finder.py).
+    "py-spy>=0.4.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/LBurny/pyspy-mcp"
+Repository = "https://github.com/LBurny/pyspy-mcp"
+Issues = "https://github.com/LBurny/pyspy-mcp/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.scripts]
+pyspy-mcp = "pyspy_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyspy_mcp"]
+# Include the bundled py-spy binary when present.
+artifacts = ["src/pyspy_mcp/bin/*"]
+
+[tool.hatch.build.targets.sdist]
+only-packages = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests/pyspy_mcp"]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]

pyspy_mcp-0.1.0/src/pyspy_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for Python performance testing with py-spy."""
+
+__version__ = "0.1.0"

pyspy_mcp-0.1.0/src/pyspy_mcp/parser.py

@@ -0,0 +1,150 @@
+"""Parsers for py-spy output formats."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List
+
+
+@dataclass
+class HotFrame:
+    name: str
+    file: str | None
+    line: int | None
+    samples: int
+    percent: float
+
+
+def parse_speedscope(profile_path: str | Path) -> Dict:
+    """Load a speedscope JSON file and return the raw dict."""
+    with open(profile_path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def analyze_speedscope(profile_path: str | Path, top_n: int = 10) -> List[HotFrame]:
+    """Aggregate a speedscope profile into the most frequently sampled frames."""
+    data = parse_speedscope(profile_path)
+    frames = data.get("shared", {}).get("frames", [])
+    counts: Counter[int] = Counter()
+    total = 0
+    for profile in data.get("profiles", []):
+        for sample in profile.get("samples", []):
+            # Deduplicate frames within a single sample to avoid overweighting deep stacks.
+            seen = set()
+            for frame_idx in sample:
+                if frame_idx not in seen:
+                    counts[frame_idx] += 1
+                    seen.add(frame_idx)
+            total += len(sample)
+
+    if total == 0:
+        return []
+
+    hot = []
+    for idx, sample_count in counts.most_common(top_n):
+        if idx < 0 or idx >= len(frames):
+            continue
+        frame = frames[idx]
+        hot.append(
+            HotFrame(
+                name=frame.get("name", "<unknown>"),
+                file=frame.get("file"),
+                line=frame.get("line"),
+                samples=sample_count,
+                percent=round(100.0 * sample_count / total, 2),
+            )
+        )
+    return hot
+
+
+def parse_raw(profile_path: str | Path, top_n: int = 10) -> List[HotFrame]:
+    """Parse py-spy raw output (semicolon-delimited stacks with counts)."""
+    counts: Counter[str] = Counter()
+    total = 0
+    with open(profile_path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            if ";" not in line:
+                continue
+            # py-spy raw format: frame1 (file:line);frame2 (file:line) count
+            try:
+                stack_str, count_str = line.rsplit(" ", 1)
+                count = int(count_str)
+            except ValueError:
+                continue
+            counts[stack_str] += count
+            total += count
+
+    if total == 0:
+        return []
+
+    hot = []
+    for stack, sample_count in counts.most_common(top_n):
+        # Use the innermost (last) frame as the representative name.
+        top_frame = stack.split(";")[-1]
+        hot.append(
+            HotFrame(
+                name=top_frame,
+                file=None,
+                line=None,
+                samples=sample_count,
+                percent=round(100.0 * sample_count / total, 2),
+            )
+        )
+    return hot
+
+
+def parse_dump_json(dump_path: str | Path) -> List[Dict]:
+    """Load the output of ``py-spy dump --json``."""
+    with open(dump_path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def format_hot_frames(frames: List[HotFrame]) -> str:
+    """Render a list of hot frames as a Markdown table."""
+    lines = ["| Function | File | Line | Samples | % |", "|---|---|---|---|---|"]
+    for f in frames:
+        file_cell = f.file or "-"
+        line_cell = str(f.line) if f.line is not None else "-"
+        lines.append(f"| {f.name} | {file_cell} | {line_cell} | {f.samples} | {f.percent} |")
+    return "\n".join(lines)
+
+
+def _frame_signature(frame: Dict) -> str:
+    """Canonical string for a frame used when comparing profiles."""
+    return f"{frame.get('name')}@{frame.get('filename')}:{frame.get('line', 0)}"
+
+
+def compare_profiles(
+    profile_a: str | Path,
+    profile_b: str | Path,
+    top_n: int = 10,
+) -> str:
+    """Compare two speedscope profiles and highlight changes."""
+    frames_a = {f.name: f for f in analyze_speedscope(profile_a, top_n=top_n * 2)}
+    frames_b = {f.name: f for f in analyze_speedscope(profile_b, top_n=top_n * 2)}
+    all_names = set(frames_a.keys()) | set(frames_b.keys())
+
+    rows = []
+    names = sorted(
+        all_names,
+        key=lambda n: -(frames_b.get(n, HotFrame(n, None, None, 0, 0.0)).percent),
+    )
+    for name in names[:top_n]:
+        a = frames_a.get(name)
+        b = frames_b.get(name)
+        pct_a = a.percent if a else 0.0
+        pct_b = b.percent if b else 0.0
+        delta = round(pct_b - pct_a, 2)
+        rows.append((name, pct_a, pct_b, delta))
+
+    lines = ["| Function | % in A | % in B | Δ |", "|---|---|---|---|"]
+    for name, pct_a, pct_b, delta in rows:
+        lines.append(f"| {name} | {pct_a} | {pct_b} | {delta:+} |")
+    return "\n".join(lines)

pyspy_mcp-0.1.0/src/pyspy_mcp/process_util.py

@@ -0,0 +1,64 @@
+"""Utilities for finding Python processes on the local machine."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List
+
+import psutil
+
+
+@dataclass
+class PythonProcess:
+    pid: int
+    cmdline: str
+    create_time: float
+    username: str | None
+    memory_mb: float
+
+
+def list_python_processes() -> List[PythonProcess]:
+    """Return a list of running processes whose executable looks like Python."""
+    processes: List[PythonProcess] = []
+    for proc in psutil.process_iter(["pid", "name", "cmdline", "create_time", "username", "memory_info"]):
+        try:
+            name = proc.info["name"] or ""
+            cmdline = proc.info["cmdline"] or []
+            cmdline_str = " ".join(cmdline) if cmdline else name
+            if not _is_python_process(name, cmdline):
+                continue
+            mem = proc.info.get("memory_info")
+            processes.append(
+                PythonProcess(
+                    pid=proc.info["pid"],
+                    cmdline=cmdline_str,
+                    create_time=proc.info["create_time"] or 0.0,
+                    username=proc.info.get("username"),
+                    memory_mb=(mem.rss / (1024 * 1024)) if mem else 0.0,
+                )
+            )
+        except (psutil.NoSuchProcess, psutil.AccessDenied):
+            continue
+    return processes
+
+
+def _is_python_process(name: str, cmdline: List[str]) -> bool:
+    """Heuristic to decide whether a process is a Python interpreter."""
+    lowered = name.lower()
+    if "python" in lowered:
+        return True
+    if not cmdline:
+        return False
+    first = cmdline[0].lower()
+    # Handle cases like /usr/bin/python3.11 or python.exe
+    if "python" in first:
+        return True
+    return False
+
+
+def format_process_list(processes: List[PythonProcess], max_count: int = 50) -> str:
+    """Format a list of Python processes as a human-readable table."""
+    lines = ["PID\tMemory(MB)\tCommand"]
+    for p in processes[:max_count]:
+        lines.append(f"{p.pid}\t{p.memory_mb:.1f}\t\t{p.cmdline[:120]}")
+    return "\n".join(lines)

pyspy_mcp-0.1.0/src/pyspy_mcp/py_spy_finder.py

@@ -0,0 +1,75 @@
+"""Locate the py-spy binary used by this MCP server."""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import sys
+from pathlib import Path
+
+
+def _binary_name() -> str:
+    return "py-spy.exe" if platform.system() == "Windows" else "py-spy"
+
+
+def _development_binary() -> Path | None:
+    """Look for a binary built from the sibling Rust workspace."""
+    # __file__ = I:/pyspy_mcp/src/pyspy_mcp/py_spy_finder.py
+    workspace_root = Path(__file__).resolve().parent.parent.parent
+    candidate = workspace_root / "target" / "release" / _binary_name()
+    if candidate.exists():
+        return candidate
+    return None
+
+
+def _bundled_binary() -> Path | None:
+    """Look for a binary shipped inside this Python package."""
+    package_dir = Path(__file__).resolve().parent
+    candidate = package_dir / "bin" / _binary_name()
+    if candidate.exists():
+        return candidate
+    return None
+
+
+def find_py_spy() -> str:
+    """Return the path to the py-spy binary.
+
+    Resolution order:
+    1. ``PYSPY_MCP_BINARY`` environment variable.
+    2. A binary built in the sibling Rust workspace (``target/release``).
+    3. A binary bundled inside this package.
+    4. ``py-spy`` on ``PATH``.
+
+    Raises:
+        FileNotFoundError: if no py-spy binary can be found.
+    """
+    env_binary = os.environ.get("PYSPY_MCP_BINARY")
+    if env_binary:
+        path = Path(env_binary)
+        if path.exists():
+            return str(path)
+        raise FileNotFoundError(
+            f"PYSPY_MCP_BINARY points to a missing file: {env_binary}"
+        )
+
+    dev = _development_binary()
+    if dev:
+        return str(dev)
+
+    bundled = _bundled_binary()
+    if bundled:
+        return str(bundled)
+
+    path_binary = shutil.which("py-spy")
+    if path_binary:
+        return path_binary
+
+    raise FileNotFoundError(
+        "Could not find a py-spy binary. Set PYSPY_MCP_BINARY, "
+        "install py-spy on PATH, or build the Rust workspace first."
+    )
+
+
+if __name__ == "__main__":
+    print(find_py_spy())

pyspy_mcp-0.1.0/src/pyspy_mcp/server.py

@@ -0,0 +1,168 @@
+"""FastMCP server exposing py-spy based Python performance tools."""
+
+from __future__ import annotations
+
+import sys
+from typing import List, Optional
+
+from fastmcp import FastMCP
+
+from . import tools
+
+mcp = FastMCP("pyspy-mcp")
+
+
+@mcp.tool()
+def record_profile(
+    pid: Optional[int] = None,
+    command: Optional[List[str]] = None,
+    duration: int = 5,
+    output_format: str = "speedscope",
+    rate: int = 100,
+    native: bool = False,
+    idle: bool = False,
+    gil: bool = False,
+    subprocesses: bool = False,
+) -> str:
+    """Record a sampling profile of a Python process or command.
+
+    Args:
+        pid: Process ID to sample. Use this OR command, not both.
+        command: Command to run and sample, e.g. ["python", "script.py"]. Use this OR pid.
+        duration: How many seconds to sample (default 5).
+        output_format: One of "speedscope" (JSON), "flamegraph" (SVG), "raw", "chrometrace".
+        rate: Samples per second (default 100).
+        native: Include native/C extension frames if supported on this platform.
+        idle: Include idle threads.
+        gil: Only include traces holding the GIL.
+        subprocesses: Include child Python processes.
+
+    Returns:
+        The generated profile content (JSON, SVG, or raw text).
+    """
+    return tools.record_profile(
+        pid=pid,
+        command=command,
+        duration=duration,
+        output_format=output_format,
+        rate=rate,
+        native=native,
+        idle=idle,
+        gil=gil,
+        subprocesses=subprocesses,
+    )
+
+
+@mcp.tool()
+def dump_stacks(
+    pid: int,
+    json_output: bool = True,
+    locals_level: int = 0,
+    subprocesses: bool = False,
+    native: bool = False,
+) -> str:
+    """Dump the current Python call stacks of a process.
+
+    Args:
+        pid: Process ID to inspect.
+        json_output: Return structured JSON instead of human-readable text.
+        locals_level: Number of times to pass --locals (0-2). Each level shows more locals.
+        subprocesses: Include child Python processes.
+        native: Include native frames if supported.
+
+    Returns:
+        The stack dump as JSON or text.
+    """
+    return tools.dump_stacks(
+        pid=pid,
+        json_output=json_output,
+        locals_level=locals_level,
+        subprocesses=subprocesses,
+        native=native,
+    )
+
+
+@mcp.tool()
+def list_python_processes() -> str:
+    """List running Python processes on this machine.
+
+    Returns:
+        A table of PID, memory usage, and command line.
+    """
+    return tools.list_python_processes_tool()
+
+
+@mcp.tool()
+def analyze_profile(profile_path: str, top_n: int = 10) -> str:
+    """Analyze an existing py-spy profile and return the hottest frames.
+
+    Args:
+        profile_path: Path to a speedscope JSON (.json) or raw (.txt) profile.
+        top_n: Number of top frames to return (default 10).
+
+    Returns:
+        A Markdown table of hot frames with sample counts and percentages.
+    """
+    return tools.analyze_profile(profile_path, top_n=top_n)
+
+
+@mcp.tool()
+def compare_profiles(profile_a: str, profile_b: str, top_n: int = 10) -> str:
+    """Compare two speedscope profiles and show percentage changes.
+
+    Args:
+        profile_a: Path to the first profile.
+        profile_b: Path to the second profile.
+        top_n: Number of frames to show (default 10).
+
+    Returns:
+        A Markdown table showing the percentage of time in each profile and the delta.
+    """
+    return tools.compare_profiles(profile_a, profile_b, top_n=top_n)
+
+
+@mcp.tool()
+def top_profile(
+    pid: Optional[int] = None,
+    command: Optional[List[str]] = None,
+    duration: int = 5,
+    rate: int = 100,
+    native: bool = False,
+    idle: bool = False,
+    gil: bool = False,
+    subprocesses: bool = False,
+) -> str:
+    """Run a live ``py-spy top`` view for a few seconds and return the summary.
+
+    Args:
+        pid: Process ID. Use this OR command.
+        command: Command to run and monitor. Use this OR pid.
+        duration: How many seconds to run top (default 5).
+        rate: Samples per second (default 100).
+        native: Include native frames if supported.
+        idle: Include idle threads.
+        gil: Only show traces holding the GIL.
+        subprocesses: Include child processes.
+
+    Returns:
+        The final top summary lines.
+    """
+    return tools.top_profile(
+        pid=pid,
+        command=command,
+        duration=duration,
+        rate=rate,
+        native=native,
+        idle=idle,
+        gil=gil,
+        subprocesses=subprocesses,
+    )
+
+
+def main() -> None:
+    """Entry point used by the ``pyspy-mcp`` console script."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

pyspy_mcp-0.1.0/src/pyspy_mcp/tools.py

@@ -0,0 +1,332 @@
+"""Core tool implementations that drive py-spy."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import List, Optional
+
+from . import parser
+from .process_util import PythonProcess, format_process_list, list_python_processes
+from .py_spy_finder import find_py_spy
+
+
+# Valid output formats supported by py-spy record.
+VALID_FORMATS = {"flamegraph", "speedscope", "raw", "chrometrace"}
+
+
+def _run_py_spy(args: List[str], timeout: Optional[int] = None) -> subprocess.CompletedProcess:
+    """Run py-spy with the given arguments and return the completed process."""
+    binary = find_py_spy()
+    env = os.environ.copy()
+    env.setdefault("RUST_LOG", "warn")
+    env.setdefault("RUST_BACKTRACE", "1")
+    return subprocess.run(
+        [binary, *args],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        env=env,
+        timeout=timeout,
+        check=False,
+    )
+
+
+# Alias kept for backwards compatibility.
+find_py_sky = find_py_spy
+
+
+def record_profile(
+    pid: Optional[int] = None,
+    command: Optional[List[str]] = None,
+    duration: int = 5,
+    output_format: str = "speedscope",
+    rate: int = 100,
+    native: bool = False,
+    idle: bool = False,
+    gil: bool = False,
+    subprocesses: bool = False,
+    output_path: Optional[str] = None,
+) -> str:
+    """Record a profile from a Python process or command.
+
+    Returns the contents of the generated profile file as a string.
+    """
+    if output_format not in VALID_FORMATS:
+        raise ValueError(f"Unsupported format: {output_format}. Use one of {VALID_FORMATS}")
+    if not (pid or command):
+        raise ValueError("Either pid or command must be provided")
+    if pid and command:
+        raise ValueError("Provide either pid or command, not both")
+    if duration <= 0:
+        raise ValueError("duration must be positive")
+
+    if output_path:
+        out = Path(output_path)
+    else:
+        suffix = ".svg" if output_format == "flamegraph" else ".json" if output_format in ("speedscope", "chrometrace") else ".txt"
+        out = Path(tempfile.mkstemp(suffix=suffix, prefix="pyspy_")[1])
+
+    args = [
+        "record",
+        "-o", str(out),
+        "--format", output_format,
+        "-d", str(duration),
+        "-r", str(rate),
+    ]
+    if native:
+        args.append("--native")
+    if idle:
+        args.append("--idle")
+    if gil:
+        args.append("--gil")
+    if subprocesses:
+        args.append("--subprocesses")
+
+    if pid:
+        args.extend(["--pid", str(pid)])
+    else:
+        args.append("--")
+        args.extend(command)
+
+    result = _run_py_spy(args, timeout=duration + 30)
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"py-spy record failed (exit {result.returncode}):\n{result.stderr}"
+        )
+
+    with open(out, "r", encoding="utf-8", errors="replace") as f:
+        return f.read()
+
+
+def dump_stacks(
+    pid: int,
+    json_output: bool = True,
+    locals_level: int = 0,
+    subprocesses: bool = False,
+    native: bool = False,
+) -> str:
+    """Dump the current Python call stacks for a process."""
+    args = ["dump", "--pid", str(pid)]
+    if json_output:
+        args.append("--json")
+    for _ in range(locals_level):
+        args.append("--locals")
+    if subprocesses:
+        args.append("--subprocesses")
+    if native:
+        args.append("--native")
+
+    result = _run_py_spy(args, timeout=30)
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"py-spy dump failed (exit {result.returncode}):\n{result.stderr}"
+        )
+    return result.stdout
+
+
+def list_python_processes_tool() -> str:
+    """List running Python processes on this machine."""
+    processes: List[PythonProcess] = list_python_processes()
+    if not processes:
+        return "No Python processes found."
+    return format_process_list(processes)
+
+
+def analyze_profile(profile_path: str, top_n: int = 10) -> str:
+    """Analyze an existing profile file and return the hottest frames."""
+    path = Path(profile_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Profile not found: {profile_path}")
+
+    suffix = path.suffix.lower()
+    if suffix == ".json":
+        frames = parser.analyze_speedscope(path, top_n=top_n)
+    elif suffix == ".txt" or suffix == ".raw":
+        frames = parser.parse_raw(path, top_n=top_n)
+    else:
+        # Best-effort: try speedscope first, then raw.
+        try:
+            frames = parser.analyze_speedscope(path, top_n=top_n)
+        except Exception:
+            frames = parser.parse_raw(path, top_n=top_n)
+
+    if not frames:
+        return "No samples found in profile."
+    return parser.format_hot_frames(frames)
+
+
+def compare_profiles(profile_a: str, profile_b: str, top_n: int = 10) -> str:
+    """Compare two profiles and return a table of changes."""
+    return parser.compare_profiles(profile_a, profile_b, top_n=top_n)
+
+
+def top_profile(
+    pid: Optional[int] = None,
+    command: Optional[List[str]] = None,
+    duration: int = 5,
+    rate: int = 100,
+    native: bool = False,
+    idle: bool = False,
+    gil: bool = False,
+    subprocesses: bool = False,
+    tail_lines: int = 40,
+) -> str:
+    """Run ``py-spy top`` for a short time and capture the final output.
+
+    On Windows, ``py-spy top`` cannot be captured through a pipe, so we fall
+    back to a short ``record --format raw`` sample and return the hottest frames.
+
+    Args:
+        pid: Process ID. Use this OR command.
+        command: Command to run and monitor. Use this OR pid.
+        duration: How many seconds to run top (default 5).
+        rate: Samples per second (default 100).
+        native: Include native frames if supported.
+        idle: Include idle threads.
+        gil: Only show traces holding the GIL.
+        subprocesses: Include child processes.
+        tail_lines: Number of trailing lines to return (default 40).
+
+    Returns:
+        The final top summary lines, or a hot-frame table on Windows.
+    """
+    if not (pid or command):
+        raise ValueError("Either pid or command must be provided")
+    if pid and command:
+        raise ValueError("Provide either pid or command, not both")
+
+    if sys.platform == "win32":
+        return _top_profile_windows(
+            pid=pid,
+            command=command,
+            duration=duration,
+            rate=rate,
+            native=native,
+            idle=idle,
+            gil=gil,
+            subprocesses=subprocesses,
+            top_n=tail_lines,
+        )
+
+    args = [
+        "top",
+        "-r", str(rate),
+    ]
+    if native:
+        args.append("--native")
+    if idle:
+        args.append("--idle")
+    if gil:
+        args.append("--gil")
+    if subprocesses:
+        args.append("--subprocesses")
+
+    if pid:
+        args.extend(["--pid", str(pid)])
+    else:
+        args.append("--")
+        args.extend(command)
+
+    # top runs indefinitely; collect output for the requested duration then terminate.
+    binary = find_py_spy()
+    env = os.environ.copy()
+    env.setdefault("RUST_LOG", "warn")
+    proc = subprocess.Popen(
+        [binary, *args],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        env=env,
+    )
+
+    from collections import deque
+    import threading
+    import time
+
+    lines: deque[str] = deque(maxlen=tail_lines)
+
+    def reader() -> None:
+        try:
+            for line in proc.stdout:
+                lines.append(line.rstrip("\n"))
+        except Exception:
+            pass
+
+    reader_thread = threading.Thread(target=reader, daemon=True)
+    reader_thread.start()
+
+    time.sleep(duration)
+    proc.terminate()
+    try:
+        proc.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait(timeout=5)
+
+    reader_thread.join(timeout=5)
+
+    if not lines and proc.stderr:
+        return proc.stderr.read()
+    return "\n".join(lines)
+
+
+def _top_profile_windows(
+    pid: Optional[int],
+    command: Optional[List[str]],
+    duration: int,
+    rate: int,
+    native: bool,
+    idle: bool,
+    gil: bool,
+    subprocesses: bool,
+    top_n: int,
+) -> str:
+    """Windows fallback for top_profile using a short raw recording."""
+    fd, path = tempfile.mkstemp(suffix=".txt", prefix="pyspy_top_")
+    os.close(fd)
+    try:
+        args = [
+            "record",
+            "-o", path,
+            "--format", "raw",
+            "-d", str(duration),
+            "-r", str(rate),
+        ]
+        if native:
+            args.append("--native")
+        if idle:
+            args.append("--idle")
+        if gil:
+            args.append("--gil")
+        if subprocesses:
+            args.append("--subprocesses")
+
+        if pid:
+            args.extend(["--pid", str(pid)])
+        else:
+            args.append("--")
+            args.extend(command)
+
+        result = _run_py_spy(args, timeout=duration + 30)
+        if result.returncode != 0:
+            raise RuntimeError(
+                f"py-spy top (Windows fallback) failed (exit {result.returncode}):\n{result.stderr}"
+            )
+
+        frames = parser.parse_raw(path, top_n=top_n)
+        if not frames:
+            return "No samples collected."
+        return parser.format_hot_frames(frames)
+    finally:
+        try:
+            os.unlink(path)
+        except OSError:
+            pass
+