pcp-mcp 1.1.0__tar.gz

pcp_mcp-1.1.0/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: pcp-mcp
+Version: 1.1.0
+Summary: MCP server for Performance Co-Pilot
+Keywords: mcp,pcp,performance-co-pilot,monitoring,model-context-protocol
+Author: Major Hayden
+Author-email: Major Hayden <major@mhtx.net>
+License-Expression: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Dist: cachetools>=5.0
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: typing-extensions>=4.0 ; python_full_version < '3.11'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/major/pcp-mcp
+Project-URL: Repository, https://github.com/major/pcp-mcp
+Description-Content-Type: text/markdown
+
+# pcp-mcp
+
+MCP server for [Performance Co-Pilot (PCP)](https://pcp.io/) metrics.
+
+Query system performance metrics via the Model Context Protocol - CPU, memory, disk I/O, network, processes, and more.
+
+📖 **[Full Documentation](https://major.github.io/pcp-mcp)** | 🚀 **[Getting Started](https://major.github.io/pcp-mcp/getting-started/)**
+
+[![CI](https://github.com/major/pcp-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/major/pcp-mcp/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/major/pcp-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/major/pcp-mcp)
+[![PyPI version](https://badge.fury.io/py/pcp-mcp.svg)](https://pypi.org/project/pcp-mcp/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🚀 Quick Start (No Install)
+
+Run immediately with [uvx](https://docs.astral.sh/uv/) — no installation required:
+
+```bash
+uvx pcp-mcp
+```
+
+Or install as a persistent global tool:
+
+```bash
+uvx tool install pcp-mcp
+pcp-mcp
+```
+
+## 📦 Installation
+
+```bash
+pip install pcp-mcp
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add pcp-mcp
+```
+
+## 📋 Requirements
+
+- **Python**: 3.10+
+- **PCP**: Performance Co-Pilot with `pmcd` and `pmproxy` running
+  ```bash
+  # Fedora/RHEL/CentOS
+  sudo dnf install pcp
+  sudo systemctl enable --now pmcd pmproxy
+  
+  # Ubuntu/Debian
+  sudo apt install pcp
+  sudo systemctl enable --now pmcd pmproxy
+  ```
+
+## ⚙️ Configuration
+
+Configure via environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PCP_HOST` | pmproxy host | `localhost` |
+| `PCP_PORT` | pmproxy port | `44322` |
+| `PCP_TARGET_HOST` | Target pmcd host to monitor | `localhost` |
+| `PCP_USE_TLS` | Use HTTPS for pmproxy | `false` |
+| `PCP_TLS_VERIFY` | Verify TLS certificates | `true` |
+| `PCP_TLS_CA_BUNDLE` | Path to custom CA bundle | (optional) |
+| `PCP_TIMEOUT` | Request timeout (seconds) | `30` |
+| `PCP_USERNAME` | HTTP basic auth user | (optional) |
+| `PCP_PASSWORD` | HTTP basic auth password | (optional) |
+| `PCP_ALLOWED_HOSTS` | Hostspecs allowed via host param | (optional) |
+
+## 🎯 Usage
+
+### Monitor localhost (default)
+
+```bash
+pcp-mcp
+```
+
+### Monitor a remote host
+
+```bash
+PCP_TARGET_HOST=webserver1.example.com pcp-mcp
+```
+
+Or use the CLI flag:
+
+```bash
+pcp-mcp --target-host webserver1.example.com
+```
+
+### Connect to remote pmproxy
+
+```bash
+PCP_HOST=metrics.example.com pcp-mcp
+```
+
+### Use SSE transport
+
+```bash
+pcp-mcp --transport sse
+```
+
+## 🔌 MCP Client Configuration
+
+### Claude Desktop
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pcp": {
+      "command": "uvx",
+      "args": ["pcp-mcp"]
+    }
+  }
+}
+```
+
+For remote monitoring:
+
+```json
+{
+  "mcpServers": {
+    "pcp": {
+      "command": "uvx",
+      "args": ["pcp-mcp", "--target-host", "webserver1.example.com"]
+    }
+  }
+}
+```
+
+> 💡 Using `uvx` means you don't need pcp-mcp installed — it runs directly from PyPI.
+
+## 🛠️ Available Tools
+
+### System Monitoring
+
+- **`get_system_snapshot`** - Point-in-time system overview (CPU, memory, disk, network, load)
+- **`get_process_top`** - Top processes by CPU, memory, or I/O usage
+- **`query_metrics`** - Fetch current values for specific PCP metrics
+- **`search_metrics`** - Discover available metrics by name pattern
+- **`describe_metric`** - Get detailed metadata about a metric
+
+### Example Queries
+
+```
+"What's the current CPU usage?"
+→ Uses get_system_snapshot
+
+"Show me the top 10 processes by memory usage"
+→ Uses get_process_top(sort_by="memory", limit=10)
+
+"What metrics are available for network traffic?"
+→ Uses search_metrics(pattern="network")
+
+"Get detailed info about kernel.all.load"
+→ Uses describe_metric(name="kernel.all.load")
+```
+
+## 📚 Resources
+
+Browse metrics via MCP resources:
+
+- `pcp://health` - Quick system health summary
+- `pcp://metrics/common` - Catalog of commonly used metrics
+- `pcp://namespaces` - Live-discovered metric namespaces
+
+## 💡 Use Cases
+
+### Performance Troubleshooting
+
+Ask Claude to:
+- "Analyze current system performance and identify bottlenecks"
+- "Why is my disk I/O so high?"
+- "Which processes are consuming the most CPU?"
+
+### System Monitoring
+
+- "Give me a health check of the production server"
+- "Compare CPU usage over the last minute"
+- "Monitor network traffic on eth0"
+
+### Capacity Planning
+
+- "What's the memory utilization trend?"
+- "Show me disk usage across all filesystems"
+- "Analyze process resource consumption patterns"
+
+## 🏗️ Architecture
+
+```
+┌─────────┐         ┌─────────┐          ┌─────────┐         ┌─────────┐
+│   LLM   │ ◄─MCP─► │ pcp-mcp │ ◄─HTTP─► │ pmproxy │ ◄─────► │  pmcd   │
+└─────────┘         └─────────┘          └─────────┘         └─────────┘
+                                         (REST API)          (metrics)
+```
+
+- **pcp-mcp**: FastMCP server exposing PCP metrics via MCP tools
+- **pmproxy**: PCP's REST API server (runs on port 44322 by default)
+- **pmcd**: PCP metrics collector daemon
+- **Remote monitoring**: Set `PCP_TARGET_HOST` to query a different pmcd instance via pmproxy
+
+## 🔧 Development
+
+```bash
+# Install dependencies
+uv sync --dev
+
+# Run all checks
+make check
+
+# Individual commands
+make lint       # ruff check
+make format     # ruff format
+make typecheck  # ty check
+make test       # pytest with coverage
+```
+
+## 📖 Documentation
+
+Full documentation at [https://major.github.io/pcp-mcp](https://major.github.io/pcp-mcp)
+
+## 📄 License
+
+MIT
+
+<!-- mcp-name: io.github.major/pcp -->

pcp_mcp-1.1.0/README.md

@@ -0,0 +1,230 @@
+# pcp-mcp
+
+MCP server for [Performance Co-Pilot (PCP)](https://pcp.io/) metrics.
+
+Query system performance metrics via the Model Context Protocol - CPU, memory, disk I/O, network, processes, and more.
+
+📖 **[Full Documentation](https://major.github.io/pcp-mcp)** | 🚀 **[Getting Started](https://major.github.io/pcp-mcp/getting-started/)**
+
+[![CI](https://github.com/major/pcp-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/major/pcp-mcp/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/major/pcp-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/major/pcp-mcp)
+[![PyPI version](https://badge.fury.io/py/pcp-mcp.svg)](https://pypi.org/project/pcp-mcp/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🚀 Quick Start (No Install)
+
+Run immediately with [uvx](https://docs.astral.sh/uv/) — no installation required:
+
+```bash
+uvx pcp-mcp
+```
+
+Or install as a persistent global tool:
+
+```bash
+uvx tool install pcp-mcp
+pcp-mcp
+```
+
+## 📦 Installation
+
+```bash
+pip install pcp-mcp
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add pcp-mcp
+```
+
+## 📋 Requirements
+
+- **Python**: 3.10+
+- **PCP**: Performance Co-Pilot with `pmcd` and `pmproxy` running
+  ```bash
+  # Fedora/RHEL/CentOS
+  sudo dnf install pcp
+  sudo systemctl enable --now pmcd pmproxy
+  
+  # Ubuntu/Debian
+  sudo apt install pcp
+  sudo systemctl enable --now pmcd pmproxy
+  ```
+
+## ⚙️ Configuration
+
+Configure via environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PCP_HOST` | pmproxy host | `localhost` |
+| `PCP_PORT` | pmproxy port | `44322` |
+| `PCP_TARGET_HOST` | Target pmcd host to monitor | `localhost` |
+| `PCP_USE_TLS` | Use HTTPS for pmproxy | `false` |
+| `PCP_TLS_VERIFY` | Verify TLS certificates | `true` |
+| `PCP_TLS_CA_BUNDLE` | Path to custom CA bundle | (optional) |
+| `PCP_TIMEOUT` | Request timeout (seconds) | `30` |
+| `PCP_USERNAME` | HTTP basic auth user | (optional) |
+| `PCP_PASSWORD` | HTTP basic auth password | (optional) |
+| `PCP_ALLOWED_HOSTS` | Hostspecs allowed via host param | (optional) |
+
+## 🎯 Usage
+
+### Monitor localhost (default)
+
+```bash
+pcp-mcp
+```
+
+### Monitor a remote host
+
+```bash
+PCP_TARGET_HOST=webserver1.example.com pcp-mcp
+```
+
+Or use the CLI flag:
+
+```bash
+pcp-mcp --target-host webserver1.example.com
+```
+
+### Connect to remote pmproxy
+
+```bash
+PCP_HOST=metrics.example.com pcp-mcp
+```
+
+### Use SSE transport
+
+```bash
+pcp-mcp --transport sse
+```
+
+## 🔌 MCP Client Configuration
+
+### Claude Desktop
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "pcp": {
+      "command": "uvx",
+      "args": ["pcp-mcp"]
+    }
+  }
+}
+```
+
+For remote monitoring:
+
+```json
+{
+  "mcpServers": {
+    "pcp": {
+      "command": "uvx",
+      "args": ["pcp-mcp", "--target-host", "webserver1.example.com"]
+    }
+  }
+}
+```
+
+> 💡 Using `uvx` means you don't need pcp-mcp installed — it runs directly from PyPI.
+
+## 🛠️ Available Tools
+
+### System Monitoring
+
+- **`get_system_snapshot`** - Point-in-time system overview (CPU, memory, disk, network, load)
+- **`get_process_top`** - Top processes by CPU, memory, or I/O usage
+- **`query_metrics`** - Fetch current values for specific PCP metrics
+- **`search_metrics`** - Discover available metrics by name pattern
+- **`describe_metric`** - Get detailed metadata about a metric
+
+### Example Queries
+
+```
+"What's the current CPU usage?"
+→ Uses get_system_snapshot
+
+"Show me the top 10 processes by memory usage"
+→ Uses get_process_top(sort_by="memory", limit=10)
+
+"What metrics are available for network traffic?"
+→ Uses search_metrics(pattern="network")
+
+"Get detailed info about kernel.all.load"
+→ Uses describe_metric(name="kernel.all.load")
+```
+
+## 📚 Resources
+
+Browse metrics via MCP resources:
+
+- `pcp://health` - Quick system health summary
+- `pcp://metrics/common` - Catalog of commonly used metrics
+- `pcp://namespaces` - Live-discovered metric namespaces
+
+## 💡 Use Cases
+
+### Performance Troubleshooting
+
+Ask Claude to:
+- "Analyze current system performance and identify bottlenecks"
+- "Why is my disk I/O so high?"
+- "Which processes are consuming the most CPU?"
+
+### System Monitoring
+
+- "Give me a health check of the production server"
+- "Compare CPU usage over the last minute"
+- "Monitor network traffic on eth0"
+
+### Capacity Planning
+
+- "What's the memory utilization trend?"
+- "Show me disk usage across all filesystems"
+- "Analyze process resource consumption patterns"
+
+## 🏗️ Architecture
+
+```
+┌─────────┐         ┌─────────┐          ┌─────────┐         ┌─────────┐
+│   LLM   │ ◄─MCP─► │ pcp-mcp │ ◄─HTTP─► │ pmproxy │ ◄─────► │  pmcd   │
+└─────────┘         └─────────┘          └─────────┘         └─────────┘
+                                         (REST API)          (metrics)
+```
+
+- **pcp-mcp**: FastMCP server exposing PCP metrics via MCP tools
+- **pmproxy**: PCP's REST API server (runs on port 44322 by default)
+- **pmcd**: PCP metrics collector daemon
+- **Remote monitoring**: Set `PCP_TARGET_HOST` to query a different pmcd instance via pmproxy
+
+## 🔧 Development
+
+```bash
+# Install dependencies
+uv sync --dev
+
+# Run all checks
+make check
+
+# Individual commands
+make lint       # ruff check
+make format     # ruff format
+make typecheck  # ty check
+make test       # pytest with coverage
+```
+
+## 📖 Documentation
+
+Full documentation at [https://major.github.io/pcp-mcp](https://major.github.io/pcp-mcp)
+
+## 📄 License
+
+MIT
+
+<!-- mcp-name: io.github.major/pcp -->

pcp_mcp-1.1.0/pyproject.toml

@@ -0,0 +1,116 @@
+[project]
+name = "pcp-mcp"
+version = "1.1.0"
+description = "MCP server for Performance Co-Pilot"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Major Hayden", email = "major@mhtx.net" }]
+requires-python = ">=3.10"
+keywords = ["mcp", "pcp", "performance-co-pilot", "monitoring", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+dependencies = [
+    "cachetools>=5.0",
+    "fastmcp>=2.0.0",
+    "httpx>=0.27",
+    "pydantic-settings>=2.0.0",
+    "typing_extensions>=4.0; python_version < '3.11'",
+]
+
+[project.urls]
+Homepage = "https://github.com/major/pcp-mcp"
+Repository = "https://github.com/major/pcp-mcp"
+
+[project.scripts]
+pcp-mcp = "pcp_mcp:main"
+
+[build-system]
+requires = ["uv_build>=0.9.18"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=6",
+    "pytest-asyncio>=0.25",
+    "respx>=0.22",
+    "ty>=0.0.12",
+    "ruff>=0.9",
+    "radon>=6",
+    "pytest-randomly>=4.0.1",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.27",
+    "commitizen>=4.0",
+]
+
+[tool.uv.build-backend]
+module-name = "pcp_mcp"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "ASYNC", "D"]
+ignore = [
+    "D100", # Missing docstring in public module
+    "D104", # Missing docstring in public package
+    "D105", # Missing docstring in magic method
+    "D107", # Missing docstring in __init__
+    "UP045", # Optional[X] vs X | None - Pydantic needs Optional in Annotated params
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+addopts = "--cov=pcp_mcp --cov-report=term-missing"
+
+[tool.coverage.run]
+source = ["src/pcp_mcp"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]
+
+[tool.ty.environment]
+python-version = "3.14"
+python-platform = "linux"
+extra-paths = ["src"]
+
+[tool.pyright]
+pythonVersion = "3.10"
+pythonPlatform = "Linux"
+venvPath = "."
+venv = ".venv"
+typeCheckingMode = "standard"
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "pep621"
+tag_format = "v$version"
+update_changelog_on_bump = true
+changelog_file = "CHANGELOG.md"
+changelog_incremental = true
+bump_message = "bump: version $current_version → $new_version"

pcp_mcp-1.1.0/src/pcp_mcp/AGENTS.md

@@ -0,0 +1,70 @@
+# pcp_mcp Core Package
+
+## OVERVIEW
+
+Core MCP server package. Entry point, HTTP client, configuration, models, error handling.
+
+## STRUCTURE
+
+```
+pcp_mcp/
+├── __init__.py     # CLI entry (main() with argparse)
+├── server.py       # FastMCP setup, lifespan context
+├── client.py       # PCPClient async httpx wrapper
+├── config.py       # PCPMCPSettings (Pydantic)
+├── models.py       # Response models (SystemSnapshot, ProcessInfo, etc.)
+├── errors.py       # Exception → ToolError mapping
+├── context.py      # get_client(), get_settings() helpers
+├── middleware.py   # Request caching middleware
+├── icons.py        # System assessment icons (emoji mappings)
+├── tools/          # MCP tools (see tools/AGENTS.md)
+├── resources/      # MCP resources (health.py, catalog.py)
+├── utils/          # Extractors, builders
+└── prompts/        # LLM system prompts
+```
+
+## KEY PATTERNS
+
+### Server Lifespan
+```python
+@asynccontextmanager
+async def lifespan(mcp: FastMCP) -> AsyncIterator[dict]:
+    async with PCPClient(...) as client:
+        yield {"client": client, "settings": settings}
+```
+Tools access via `ctx.request_context.lifespan_context["client"]`.
+
+### Client Rate Calculation
+`fetch_with_rates()` takes two samples, calculates per-second rates for counters.
+Handles counter wrap-around (reset to 0) gracefully.
+
+### Error Mapping
+```python
+try:
+    result = await client.fetch(names)
+except Exception as e:
+    raise handle_pcp_error(e, "fetching metrics") from e
+```
+
+### Configuration
+Pydantic settings with `env_prefix="PCP_"`. Computed properties: `base_url`, `auth`.
+
+## WHERE TO LOOK
+
+| Task | File | Notes |
+|------|------|-------|
+| Add CLI flag | `__init__.py` | argparse in `main()` |
+| Change transport | `__init__.py` | `server.run(transport=...)` |
+| Add env var | `config.py` | Add field with `Field(default=...)` |
+| New response type | `models.py` | Inherit `BaseModel` |
+| Map new exception | `errors.py` | Add case to `handle_pcp_error()` |
+| Access client in tool | `context.py` | Use `get_client(ctx)` |
+| Add caching | `middleware.py` | Request caching layer |
+| System icons | `icons.py` | Assessment emoji mappings |
+
+## ANTI-PATTERNS
+
+- **NEVER** call `client.fetch()` for counter metrics expecting rates
+- **NEVER** use client outside `async with` context
+- **NEVER** log credentials from settings
+- **ALWAYS** use `handle_pcp_error()` for exception wrapping