linux-profiler-tool/
├── src/linux_profiler/
│   ├── __init__.py
│   ├── server.py              # MCP server main entry
│   └── collectors/
│       ├── __init__.py
│       ├── base.py            # Collector base class
│       ├── cpu.py             # CPU metrics collector
│       ├── memory.py          # Memory metrics collector
│       ├── disk.py            # Disk I/O collector
│       ├── network.py         # Network metrics collector
│       ├── process.py         # Process metrics & search collector
│       └── perf.py            # 🆕 Perf profiling & flame graph collector
├── examples/
│   └── profile_workflow.py    # 🆕 Interactive profiling demo
├── pyproject.toml
├── mcp_config.json            # MCP configuration example
├── FEATURES.md                # 🆕 Detailed feature documentation
├── CHANGELOG.md               # 🆕 Version changelog
├── LICENSE                    # Apache 2.0 License
└── README.md

# Clone the project
cd linux-profiler-tool

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or .venv\Scripts\activate  # Windows

# Install dependencies (development mode)
pip install -e .

# Or use uv (faster)
uv pip install -e .

# Verify installation
linux-profiler --help

# Run directly (default STDIO mode)
python -m linux_profiler.server

# Or use the installed command
linux-profiler

# Start Streamable HTTP service (default)
linux-profiler --http

# Stateless mode
linux-profiler --http --stateless

# Custom port
linux-profiler --http --port 22222

# Use SSE transport
linux-profiler --http --transport sse

# Enable both SSE and Streamable HTTP
linux-profiler --http --transport both

{
  "mcpServers": {
    "linux-profiler": {
      "command": "python",
      "args": ["-m", "linux_profiler.server"],
      "cwd": "/path/to/linux-profiler-tool",
      "env": {
        "PYTHONPATH": "/path/to/linux-profiler-tool/src"
      }
    }
  }
}

{
  "mcpServers": {
    "linux-profiler": {
      "url": "http://your-server:22222/mcp",
      "transportType": "streamable-http"
    }
  }
}

{
  "mcpServers": {
    "linux-profiler": {
      "url": "http://your-server:22222/sse"
    }
  }
}

{
  "status": "warning",
  "timestamp": "2026-01-14T10:30:00",
  "summary": {
    "cpu_percent": 45.2,
    "load_average_1min": 2.5,
    "memory_percent": 72.3,
    "swap_percent": 15.0
  },
  "issues": [],
  "warnings": [
    "Warning: Memory usage is high (72.3%)"
  ]
}

{
  "success": true,
  "keyword": "nginx",
  "case_sensitive": false,
  "matched_count": 3,
  "processes": [
    {
      "pid": 1234,
      "name": "nginx",
      "username": "www-data",
      "cmdline": "nginx: master process /usr/sbin/nginx",
      "cpu_percent": 0.5,
      "memory_percent": 0.3,
      "status": "sleeping"
    },
    {
      "pid": 1235,
      "name": "nginx",
      "username": "www-data",
      "cmdline": "nginx: worker process",
      "cpu_percent": 2.1,
      "memory_percent": 0.4,
      "status": "running"
    }
  ],
  "tip": "Use the PID from this list to profile a specific process with profile_process tool"
}

{
  "success": true,
  "pid": 1234,
  "duration": 30,
  "frequency": 99,
  "event": "cpu-clock",
  "timestamp": "2026-01-18 07:42:12",
  "statistics": {
    "total_samples": 287,
    "top_functions": [
      {
        "overhead_percent": 15.2,
        "command": "nginx",
        "function": "ngx_http_process_request"
      },
      {
        "overhead_percent": 8.7,
        "command": "nginx",
        "function": "ngx_event_process_posted"
      }
    ]
  },
  "flame_graph_data": [
    "nginx;[libc] __GI___libc_write;ngx_write_channel 12",
    "nginx;ngx_event_process_posted;ngx_http_request_handler 45"
  ],
  "help": "Use flame_graph_data to generate flame graph visualization"
}

{
  "hostname": "web-server-01",
  "system": "Linux",
  "kernel_version": "5.15.0-91-generic",
  "architecture": "x86_64",
  "python_version": "3.10.12",
  "boot_time": "2026-01-10T08:30:00"
}

{
  "cpu_percent": 35.5,
  "cpu_count": {
    "physical": 8,
    "logical": 16
  },
  "cpu_freq": {
    "current": 2400.0,
    "min": 800.0,
    "max": 3800.0
  },
  "load_average": {
    "1min": 2.15,
    "5min": 1.89,
    "15min": 1.76
  },
  "per_cpu_percent": [25.0, 38.5, 42.1, 30.0, ...],
  "cpu_times_percent": {
    "user": 25.5,
    "system": 8.0,
    "idle": 66.5,
    "iowait": 0.0
  }
}

# Temporarily (until reboot)
sudo sysctl -w kernel.perf_event_paranoid=-1

# Permanently
echo "kernel.perf_event_paranoid = -1" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# 1. Search for processes
search_processes --keyword "python"

# 2. Profile the target process
profile_process --pid 12345 --duration 30

# 3. Generate interactive flame graph
# The tool outputs flame_graph_data that can be visualized with:
# - FlameGraph tools (https://github.com/brendangregg/FlameGraph)
# - speedscope (https://www.speedscope.app/)
# - Or the built-in HTML generator

python examples/profile_workflow.py

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=linux_profiler

# Format code
black src/

# Type checking
mypy src/

# Linting
ruff check src/

Copyright 2026 Linux Profiler MCP Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.