pcp-mcp 0.1.0__tar.gz

pcp_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: pcp-mcp
+Version: 0.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 :: 3 - Alpha
+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: 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.
+
+## 🚀 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 `pmproxy` running
+  ```bash
+  # Fedora/RHEL/CentOS
+  sudo dnf install pcp
+  sudo systemctl enable --now pmproxy
+  
+  # Ubuntu/Debian
+  sudo apt install pcp
+  sudo systemctl enable --now 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_TIMEOUT` | Request timeout (seconds) | `30` |
+| `PCP_USERNAME` | HTTP basic auth user | (optional) |
+| `PCP_PASSWORD` | HTTP basic auth password | (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": "pcp-mcp"
+    }
+  }
+}
+```
+
+For remote monitoring:
+
+```json
+{
+  "mcpServers": {
+    "pcp": {
+      "command": "pcp-mcp",
+      "args": ["--target-host", "webserver1.example.com"]
+    }
+  }
+}
+```
+
+## 🛠️ 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://metrics` - List all available metrics (grouped by prefix)
+- `pcp://system/snapshot` - Latest system snapshot
+- `pcp://processes/top` - Top processes
+
+## 💡 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

pcp_mcp-0.1.0/README.md

@@ -0,0 +1,199 @@
+# 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.
+
+## 🚀 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 `pmproxy` running
+  ```bash
+  # Fedora/RHEL/CentOS
+  sudo dnf install pcp
+  sudo systemctl enable --now pmproxy
+  
+  # Ubuntu/Debian
+  sudo apt install pcp
+  sudo systemctl enable --now 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_TIMEOUT` | Request timeout (seconds) | `30` |
+| `PCP_USERNAME` | HTTP basic auth user | (optional) |
+| `PCP_PASSWORD` | HTTP basic auth password | (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": "pcp-mcp"
+    }
+  }
+}
+```
+
+For remote monitoring:
+
+```json
+{
+  "mcpServers": {
+    "pcp": {
+      "command": "pcp-mcp",
+      "args": ["--target-host", "webserver1.example.com"]
+    }
+  }
+}
+```
+
+## 🛠️ 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://metrics` - List all available metrics (grouped by prefix)
+- `pcp://system/snapshot` - Latest system snapshot
+- `pcp://processes/top` - Top processes
+
+## 💡 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

pcp_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,104 @@
+[project]
+name = "pcp-mcp"
+version = "0.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 :: 3 - Alpha",
+    "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 = [
+    "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",
+]
+
+[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__
+]
+
+[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"

pcp_mcp-0.1.0/src/pcp_mcp/__init__.py

@@ -0,0 +1,59 @@
+"""PCP MCP Server - Performance Co-Pilot metrics via Model Context Protocol."""
+
+from __future__ import annotations
+
+import argparse
+import os
+
+
+def main() -> None:
+    """Run the PCP MCP server."""
+    parser = argparse.ArgumentParser(
+        description="PCP MCP Server - Performance Co-Pilot Metrics",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Environment Variables:
+  PCP_HOST          pmproxy host (default: localhost)
+  PCP_PORT          pmproxy port (default: 44322)
+  PCP_TARGET_HOST   Target pmcd host to monitor (default: localhost)
+  PCP_USE_TLS       Use HTTPS for pmproxy connection (default: false)
+  PCP_TIMEOUT       Request timeout in seconds (default: 30)
+  PCP_USERNAME      HTTP basic auth user (optional)
+  PCP_PASSWORD      HTTP basic auth password (optional)
+
+Examples:
+  # Monitor localhost (default)
+  pcp-mcp
+
+  # Monitor a remote host
+  PCP_TARGET_HOST=webserver1.example.com pcp-mcp
+
+  # Connect to pmproxy on a different host
+  PCP_HOST=metrics.example.com pcp-mcp
+
+  # Use SSE transport
+  pcp-mcp --transport sse
+""",
+    )
+    parser.add_argument(
+        "--target-host",
+        help="Target pmcd host to monitor (overrides PCP_TARGET_HOST)",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse", "streamable-http"],
+        default="stdio",
+        help="Transport protocol (default: stdio)",
+    )
+    args = parser.parse_args()
+
+    if args.target_host:
+        os.environ["PCP_TARGET_HOST"] = args.target_host
+
+    from pcp_mcp.server import create_server
+
+    server = create_server()
+    server.run(transport=args.transport)
+
+
+__all__ = ["main"]