mcp-beaker 0.1.0__tar.gz

mcp_beaker-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Caches
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+
+# Environment
+.env
+*.env.local
+
+# OS
+.DS_Store
+Thumbs.db

mcp_beaker-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: mcp-beaker
+Version: 0.1.0
+Summary: MCP server for Beaker lab automation — system provisioning, job management, distro discovery, and failure diagnosis
+Project-URL: Homepage, https://github.com/faizbawa/mcp-beaker
+Project-URL: Repository, https://github.com/faizbawa/mcp-beaker
+Project-URL: Issues, https://github.com/faizbawa/mcp-beaker/issues
+Author: faizbawa
+License-Expression: Apache-2.0
+Keywords: ai,beaker,lab-automation,llm,mcp,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1.7
+Requires-Dist: fastmcp<4,>=3.0.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic<3.0,>=2.10.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: uvicorn>=0.27.1
+Description-Content-Type: text/markdown
+
+# mcp-beaker
+
+MCP server for [Beaker](https://beaker-project.org/) lab automation -- system provisioning, job management, distro discovery, and failure diagnosis.
+
+Works with any Beaker server instance. Built on [FastMCP v3](https://gofastmcp.com/) and designed for use with AI coding assistants (Cursor, Claude Desktop, etc.).
+
+## Features
+
+- **23 tools** covering the full Beaker lifecycle: systems, jobs, distros, tasks
+- **Dual auth**: Kerberos (via `bkr` CLI) and password (via XML-RPC)
+- **Job XML validation**: auto-fills missing fields, infers distro families
+- **Failure diagnosis**: deep analysis with auto-retry on correctable failures
+- **10 documentation topics** exposed as MCP resources
+- **2 workflow prompts** for common tasks (reserve system, diagnose job)
+- **Generic**: works with any Beaker URL, configurable SSL/CA settings
+
+## Installation
+
+```bash
+# Using uv (recommended)
+pip install uv
+uvx mcp-beaker
+
+# Using pip
+pip install mcp-beaker
+mcp-beaker
+
+# Local development
+uv run --directory /path/to/mcp-beaker mcp-beaker
+```
+
+## Configuration
+
+### Cursor / VS Code
+
+Add to your `.cursor/mcp.json` (or `.vscode/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "beaker": {
+      "command": "uvx",
+      "args": ["mcp-beaker"],
+      "env": {
+        "BEAKER_URL": "https://beaker.example.com",
+        "BEAKER_AUTH_METHOD": "kerberos"
+      }
+    }
+  }
+}
+```
+
+### Streamable HTTP mode
+
+```bash
+uvx mcp-beaker --transport streamable-http --port 8000
+```
+
+```json
+{
+  "mcpServers": {
+    "beaker": {
+      "url": "http://localhost:8000/mcp",
+      "type": "streamableHttp"
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BEAKER_URL` | Yes | -- | Base URL of your Beaker server |
+| `BEAKER_AUTH_METHOD` | No | `kerberos` | `kerberos` or `password` |
+| `BEAKER_USERNAME` | For password auth | -- | Beaker username |
+| `BEAKER_PASSWORD` | For password auth | -- | Beaker password |
+| `BEAKER_OWNER` | No | `$USER` | Default owner for job queries |
+| `BEAKER_SSL_VERIFY` | No | `true` | Verify SSL certificates |
+| `BEAKER_CA_CERT` | No | -- | Path to CA certificate bundle |
+
+## CLI Options
+
+```
+mcp-beaker [OPTIONS]
+
+Options:
+  --transport [stdio|sse|streamable-http]  Transport type (default: stdio)
+  --port INTEGER                           Port for HTTP transports (default: 8000)
+  --host TEXT                              Host for HTTP transports (default: 0.0.0.0)
+  --path TEXT                              Path for streamable-http (default: /mcp)
+  --beaker-url TEXT                        Beaker server URL
+  --ssl-verify / --no-ssl-verify           Verify SSL certs (default: verify)
+  --ca-cert TEXT                           CA certificate bundle path
+  --auth-method [kerberos|password]        Authentication method
+  --read-only                              Disable all write tools
+  --enabled-tools TEXT                     Comma-separated tools to enable
+  -v, --verbose                            Increase verbosity (-v info, -vv debug)
+  --version                                Show version
+  --help                                   Show this message
+```
+
+## Tools
+
+### Read Tools (13)
+
+| Tool | Description |
+|------|-------------|
+| `list_systems` | List systems by availability (all/available/free) |
+| `get_system_details` | Hardware specs, ownership, status for a system |
+| `get_system_history` | Activity history for a system |
+| `get_system_arches` | Supported OS families and architectures |
+| `list_jobs` | Filter jobs by owner, status, whiteboard |
+| `get_job_status` | Job status with failure diagnosis |
+| `get_job_results_xml` | Export job results as XML |
+| `get_job_logs` | List log files for a job/recipe/task |
+| `list_distro_trees` | Search distros by name, family, arch, tags |
+| `list_os_families` | List all known OS families |
+| `whoami` | Show authenticated user info |
+| `list_lab_controllers` | List all lab controllers |
+| `search_tasks` | Search the task library |
+
+### Write Tools (10)
+
+| Tool | Description |
+|------|-------------|
+| `submit_job` | Submit a job from XML (with validation and auto-fill) |
+| `clone_job` | Clone and resubmit an existing job |
+| `cancel_job` | Cancel a running/queued job |
+| `watch_job` | Poll until completion with failure analysis and auto-retry |
+| `reserve_system` | Manually reserve a system |
+| `release_system` | Release a manually reserved system |
+| `power_system` | Power on/off/reboot a system |
+| `provision_system` | Provision a reserved system with a distro |
+| `extend_watchdog` | Extend a running task's watchdog timer |
+| `set_job_response` | Ack/nak (waive) a recipe set result |
+
+## Authentication
+
+### Kerberos (recommended)
+
+Ensure you have a valid ticket:
+
+```bash
+kinit your-username@YOUR.REALM
+```
+
+The server uses the `bkr` CLI for authenticated operations, which picks up the Kerberos ticket automatically.
+
+### Password
+
+Set `BEAKER_AUTH_METHOD=password` along with `BEAKER_USERNAME` and `BEAKER_PASSWORD`. The server authenticates via the XML-RPC `auth.login_password()` method.
+
+## Architecture
+
+```
+src/mcp_beaker/
+  __init__.py           # Click CLI entry point
+  config.py             # BeakerConfig dataclass
+  exceptions.py         # Custom exceptions
+  client.py             # BeakerClient (XML-RPC + REST)
+  models/               # Pydantic response models
+  servers/
+    __init__.py         # FastMCP server, lifespan, DI helper
+    systems.py          # System tools (4 read + 4 write)
+    jobs.py             # Job tools (4 read + 6 write)
+    distros.py          # Distro tools (2 read)
+    tasks.py            # Task tools (1 read)
+    general.py          # General tools (2 read)
+    prompts.py          # Workflow prompt templates
+    resources.py        # Beaker documentation resources
+  utils/
+    xml_validation.py   # Job XML validation/auto-fill
+    diagnosis.py        # Failure analysis engine
+    formatting.py       # Human-readable formatters
+    bkr_cli.py          # bkr CLI helpers
+    parsing.py          # ID parsing utilities
+```
+
+## Development
+
+```bash
+cd mcp-beaker
+uv sync --dev
+uv run pytest
+uv run ruff check src/
+```
+
+## License
+
+Apache-2.0

mcp_beaker-0.1.0/README.md

@@ -0,0 +1,191 @@
+# mcp-beaker
+
+MCP server for [Beaker](https://beaker-project.org/) lab automation -- system provisioning, job management, distro discovery, and failure diagnosis.
+
+Works with any Beaker server instance. Built on [FastMCP v3](https://gofastmcp.com/) and designed for use with AI coding assistants (Cursor, Claude Desktop, etc.).
+
+## Features
+
+- **23 tools** covering the full Beaker lifecycle: systems, jobs, distros, tasks
+- **Dual auth**: Kerberos (via `bkr` CLI) and password (via XML-RPC)
+- **Job XML validation**: auto-fills missing fields, infers distro families
+- **Failure diagnosis**: deep analysis with auto-retry on correctable failures
+- **10 documentation topics** exposed as MCP resources
+- **2 workflow prompts** for common tasks (reserve system, diagnose job)
+- **Generic**: works with any Beaker URL, configurable SSL/CA settings
+
+## Installation
+
+```bash
+# Using uv (recommended)
+pip install uv
+uvx mcp-beaker
+
+# Using pip
+pip install mcp-beaker
+mcp-beaker
+
+# Local development
+uv run --directory /path/to/mcp-beaker mcp-beaker
+```
+
+## Configuration
+
+### Cursor / VS Code
+
+Add to your `.cursor/mcp.json` (or `.vscode/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "beaker": {
+      "command": "uvx",
+      "args": ["mcp-beaker"],
+      "env": {
+        "BEAKER_URL": "https://beaker.example.com",
+        "BEAKER_AUTH_METHOD": "kerberos"
+      }
+    }
+  }
+}
+```
+
+### Streamable HTTP mode
+
+```bash
+uvx mcp-beaker --transport streamable-http --port 8000
+```
+
+```json
+{
+  "mcpServers": {
+    "beaker": {
+      "url": "http://localhost:8000/mcp",
+      "type": "streamableHttp"
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BEAKER_URL` | Yes | -- | Base URL of your Beaker server |
+| `BEAKER_AUTH_METHOD` | No | `kerberos` | `kerberos` or `password` |
+| `BEAKER_USERNAME` | For password auth | -- | Beaker username |
+| `BEAKER_PASSWORD` | For password auth | -- | Beaker password |
+| `BEAKER_OWNER` | No | `$USER` | Default owner for job queries |
+| `BEAKER_SSL_VERIFY` | No | `true` | Verify SSL certificates |
+| `BEAKER_CA_CERT` | No | -- | Path to CA certificate bundle |
+
+## CLI Options
+
+```
+mcp-beaker [OPTIONS]
+
+Options:
+  --transport [stdio|sse|streamable-http]  Transport type (default: stdio)
+  --port INTEGER                           Port for HTTP transports (default: 8000)
+  --host TEXT                              Host for HTTP transports (default: 0.0.0.0)
+  --path TEXT                              Path for streamable-http (default: /mcp)
+  --beaker-url TEXT                        Beaker server URL
+  --ssl-verify / --no-ssl-verify           Verify SSL certs (default: verify)
+  --ca-cert TEXT                           CA certificate bundle path
+  --auth-method [kerberos|password]        Authentication method
+  --read-only                              Disable all write tools
+  --enabled-tools TEXT                     Comma-separated tools to enable
+  -v, --verbose                            Increase verbosity (-v info, -vv debug)
+  --version                                Show version
+  --help                                   Show this message
+```
+
+## Tools
+
+### Read Tools (13)
+
+| Tool | Description |
+|------|-------------|
+| `list_systems` | List systems by availability (all/available/free) |
+| `get_system_details` | Hardware specs, ownership, status for a system |
+| `get_system_history` | Activity history for a system |
+| `get_system_arches` | Supported OS families and architectures |
+| `list_jobs` | Filter jobs by owner, status, whiteboard |
+| `get_job_status` | Job status with failure diagnosis |
+| `get_job_results_xml` | Export job results as XML |
+| `get_job_logs` | List log files for a job/recipe/task |
+| `list_distro_trees` | Search distros by name, family, arch, tags |
+| `list_os_families` | List all known OS families |
+| `whoami` | Show authenticated user info |
+| `list_lab_controllers` | List all lab controllers |
+| `search_tasks` | Search the task library |
+
+### Write Tools (10)
+
+| Tool | Description |
+|------|-------------|
+| `submit_job` | Submit a job from XML (with validation and auto-fill) |
+| `clone_job` | Clone and resubmit an existing job |
+| `cancel_job` | Cancel a running/queued job |
+| `watch_job` | Poll until completion with failure analysis and auto-retry |
+| `reserve_system` | Manually reserve a system |
+| `release_system` | Release a manually reserved system |
+| `power_system` | Power on/off/reboot a system |
+| `provision_system` | Provision a reserved system with a distro |
+| `extend_watchdog` | Extend a running task's watchdog timer |
+| `set_job_response` | Ack/nak (waive) a recipe set result |
+
+## Authentication
+
+### Kerberos (recommended)
+
+Ensure you have a valid ticket:
+
+```bash
+kinit your-username@YOUR.REALM
+```
+
+The server uses the `bkr` CLI for authenticated operations, which picks up the Kerberos ticket automatically.
+
+### Password
+
+Set `BEAKER_AUTH_METHOD=password` along with `BEAKER_USERNAME` and `BEAKER_PASSWORD`. The server authenticates via the XML-RPC `auth.login_password()` method.
+
+## Architecture
+
+```
+src/mcp_beaker/
+  __init__.py           # Click CLI entry point
+  config.py             # BeakerConfig dataclass
+  exceptions.py         # Custom exceptions
+  client.py             # BeakerClient (XML-RPC + REST)
+  models/               # Pydantic response models
+  servers/
+    __init__.py         # FastMCP server, lifespan, DI helper
+    systems.py          # System tools (4 read + 4 write)
+    jobs.py             # Job tools (4 read + 6 write)
+    distros.py          # Distro tools (2 read)
+    tasks.py            # Task tools (1 read)
+    general.py          # General tools (2 read)
+    prompts.py          # Workflow prompt templates
+    resources.py        # Beaker documentation resources
+  utils/
+    xml_validation.py   # Job XML validation/auto-fill
+    diagnosis.py        # Failure analysis engine
+    formatting.py       # Human-readable formatters
+    bkr_cli.py          # bkr CLI helpers
+    parsing.py          # ID parsing utilities
+```
+
+## Development
+
+```bash
+cd mcp-beaker
+uv sync --dev
+uv run pytest
+uv run ruff check src/
+```
+
+## License
+
+Apache-2.0

mcp_beaker-0.1.0/pyproject.toml

@@ -0,0 +1,103 @@
+[project]
+name = "mcp-beaker"
+version = "0.1.0"
+description = "MCP server for Beaker lab automation — system provisioning, job management, distro discovery, and failure diagnosis"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+keywords = ["mcp", "beaker", "testing", "lab-automation", "ai", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = [
+    "fastmcp>=3.0.0,<4",
+    "httpx>=0.28.0",
+    "pydantic>=2.10.0,<3.0",
+    "click>=8.1.7",
+    "uvicorn>=0.27.1",
+    "python-dotenv>=1.0.1",
+]
+
+[[project.authors]]
+name = "faizbawa"
+
+[project.urls]
+Homepage = "https://github.com/faizbawa/mcp-beaker"
+Repository = "https://github.com/faizbawa/mcp-beaker"
+Issues = "https://github.com/faizbawa/mcp-beaker/issues"
+
+[project.scripts]
+mcp-beaker = "mcp_beaker:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_beaker"]
+
+[tool.uv]
+package = true
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.3.0",
+    "mypy>=1.8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+indent-width = 4
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "B", "W", "I", "N", "UP", "ANN", "S", "C4", "ICN", "EM"]
+ignore = [
+    "ANN401",
+    "EM101",
+    "EM102",
+    "S101",
+]
+fixable = ["ALL"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S", "ANN"]
+"src/mcp_beaker/__init__.py" = ["E402", "S104"]
+"src/mcp_beaker/utils/bkr_cli.py" = ["S603", "S607"]
+"src/mcp_beaker/client.py" = ["S603", "S607"]
+"src/mcp_beaker/utils/xml_validation.py" = ["S314"]
+"src/mcp_beaker/utils/diagnosis.py" = ["S314"]
+"src/mcp_beaker/servers/systems.py" = ["S314"]
+"src/mcp_beaker/servers/__init__.py" = ["E402"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false