Skip to content

README.md

Latest commit

 

History

History
152 lines (104 loc) · 3.67 KB

README.md

File metadata and controls

152 lines (104 loc) · 3.67 KB
Raw

uProf MCP Server

A Model Context Protocol (MCP) server for profiling x86 CPU applications using AMD uProf. This package enables LLMs to analyze CPU performance hotspots through the AMD uProf profiler.

Features

CPU Hotspot Profiling (uprof-profiler-mcp)

Tool for profiling x86 CPU executables to identify performance hotspots using AMD uProf.

Capabilities:

  • Profile CPU applications for hotspot analysis
  • Identify top functions consuming CPU time
  • Generate detailed profiling reports
  • Support for custom executable arguments

Installation

You can install the package directly using uv or pip.

# Using uv (recommended)
uv pip install .

# Using pip
pip install .

Setting the uProf Path

uProf MCP needs to know where AMD uProf is installed. There are three ways to set this, in order of precedence:

  1. Environment variable INTELLIKIT_UPROF_CLI:

    export INTELLIKIT_UPROF_CLI=/opt/AMDuProf_5.3-521/bin/AMDuProfCLI

  2. Constructor argument (Python API only):

    profiler = UProfProfiler(uprof="/opt/AMDuProf_5.3-521/bin/AMDuProfCLI")

  3. Default path: /opt/AMDuProf_5.1-701/bin/AMDuProfCLI

Configuration

To use this server with an MCP client, add the following to your configuration file:

{
  "mcpServers": {
    "uprof-profiler-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/uprof_mcp", "uprof-profiler-mcp"],
      "env": {
        "INTELLIKIT_UPROF_CLI": "/opt/AMDuProf_5.3-521/bin/AMDuProfCLI"
      }
    }
  }
}

Note: Adjust /path/to/uprof_mcp to the actual path where you have cloned or installed the package, and update the uProf path to match your installation.

Usage

Python API (Non-Agentic Mode)

You can use the profiler directly without MCP:

import tempfile
from uprof_mcp.uprof_profiler import UProfProfiler

profiler = UProfProfiler()

with tempfile.TemporaryDirectory() as tmpdir:
    result = profiler.find_hotspots(
        output_dir=tmpdir,
        executable="./my_app",
        executable_args=["arg1", "arg2"],
    )

    with result.report_path.open() as report:
        print(report.read())

Example with LangChain

See examples/uprof_profiler.py for a complete example using LangChain agents:

# Agentic mode (with LLM)
python examples/uprof_profiler.py --executable ./my_app --args arg1 arg2

# Non-agentic mode (direct profiling)
python examples/uprof_profiler.py --executable ./my_app --args arg1 arg2 --classic

Requirements

  • Python >= 3.10
  • AMD uProf installed
  • x86 CPU architecture

Development

This project uses uv for dependency management.

  1. Sync dependencies:

    uv sync --dev

  2. Run the server locally (for testing):

    uv run uprof-profiler-mcp

  3. Run tests:

    pytest

API Reference

UProfProfiler Class

from uprof_mcp.uprof_profiler import UProfProfiler

profiler = UProfProfiler(logger=None, uprof=None)

Constructor parameters:

  • logger (logging.Logger | None): Logger instance. If None, a default logger is created.
  • uprof (str | PathLike | None): Path to the uProf CLI executable. If None, uses the INTELLIKIT_UPROF_CLI environment variable, or falls back to the default path.

Methods:

  • find_hotspots(output_dir, executable, executable_args) → UProfProfilerResult
    • Profiles the executable and returns hotspot analysis
    • Parameters:
      • output_dir (str | Path): Directory to store results
      • executable (str | Path): Path to executable
      • executable_args (list[str] | None): Arguments for the executable
    • Returns: UProfProfilerResult with report_path attribute