Content
# power-hmc-mcp-server
MCP server that exposes IBM Power HMC partition and capacity operations as safe, typed tools for LangGraph and other MCP-aware orchestrators.
The goal of this project is to decouple agents from the raw HMC REST API by providing a small, opinionated set of MCP tools such as `list_lpars`, `create_lpar_from_profile`, `start_lpar`, and `stop_lpar`. Agents talk MCP; this server talks HMC.
## Status
Read-only MCP tools are backed by a real IBM HMC REST client (session logon, GET-only operations). Write tools (`create_lpar_from_profile`, `start_lpar`, `stop_lpar`) exist as gated stubs on the client but are **not registered** with MCP until guardrails and approvals are in place.
### Write-tool gating
Destructive or state-changing operations are intentionally withheld from the MCP tool surface. To expose a write tool:
1. Implement and test the `hmc_client` method with dry-run / approval hooks.
2. Uncomment the corresponding `register(...)` line in `src/power_hmc_mcp/tools/__init__.py`.
Until then, agents can only call read-only tools marked with `readOnlyHint`.
### Resource identifiers
`managed_system_id` and `lpar_id` arguments are **HMC REST UUIDs** (from `list_managed_systems` / `list_lpars` results), not partition numbers.
## Architecture
High-level flow:
```text
LangGraph / MCP client
|
v
power-hmc-mcp-server (this repo)
|
v
HMC REST API (HTTPS 12443)
|
v
Power systems / LPARs
```
This server has three layers:
- **Config**: HMC connection details, credentials, and basic policy (what systems/LPARs are visible).
- **HMC client**: Thin Python wrapper over the documented HMC REST API (auth, URLs, JSON/XML parsing).
- **MCP server**: Defines tools with JSON Schemas and dispatches tool calls to the HMC client.
## Read-only tool surface
All registered tools are read-only (`readOnlyHint=true`) and return normalized JSON:
| Tool | Inputs | Purpose |
|------|--------|---------|
| `list_managed_systems` | none | List managed systems (filtered by allowlist if configured) |
| `get_managed_system` | `managed_system_id` | Single system details |
| `list_lpars` | `managed_system_id` | LPARs on a system |
| `get_lpar` | `managed_system_id`, `lpar_id` | Full LPAR detail |
| `get_lpar_status` | `lpar_id` | Quick LPAR status properties |
| `list_partition_profiles` | `lpar_id` | Partition profiles for an LPAR |
| `get_capacity` | `managed_system_id` | PCM processed-metrics feed metadata (links/timestamps, not full metric JSON) |
`managed_system_id` and `lpar_id` are **HMC REST UUIDs** from list/get results, not partition numbers.
`list_partition_profiles` only requires `lpar_id` (profiles are children of the LogicalPartition resource in the HMC API).
Write tools (`create_lpar_from_profile`, `start_lpar`, `stop_lpar`) are **not registered** yet.
Each tool will have:
- A strict JSON Schema for inputs.
- A normalized JSON result (no raw HMC XML leaking to agents).
- Optional approval gates for high-risk operations.
## Local development
### Prerequisites
- Python 3.11+ (recommended)
- Access to an IBM Power HMC with REST API enabled (typically HTTPS on port 12443)
- A technical user or certificate with appropriate permissions on the HMC
### Setup
Clone the repo:
```bash
git clone git@github.com:TylrDn/power-hmc-mcp-server.git
cd power-hmc-mcp-server
```
Create and activate a virtual environment (example with `python -m venv`):
```bash
python -m venv .venv
source .venv/bin/activate # on Windows: .venv\Scripts\activate
```
Install dependencies:
```bash
pip install -e .
```
or, if you prefer a requirements file:
```bash
pip install -r requirements.txt
```
### Configuration
Configuration is read from environment variables and/or a `.env` file:
- `HMC_HOST` – hostname or IP of the HMC (no protocol, e.g. `hmc.example.com`)
- `HMC_PORT` – port of the HMC web services API (default: `12443`)
- `HMC_USERNAME` – HMC user for API calls
- `HMC_PASSWORD` – password for the user above (or a token, depending on setup)
- `HMC_VERIFY_TLS` – `true` / `false` to control certificate verification
- `HMC_TIMEOUT_SECONDS` – HTTP timeout (default `30`)
- `HMC_CA_BUNDLE` – optional path to a CA bundle file
- `HMC_ALLOWED_MANAGED_SYSTEMS` – optional comma-separated managed system UUID allowlist; when set, read tools only return or accept those systems
- `HMC_ENABLE_WRITE_TOOLS` – `false` by default; must be `true` before write tools can be enabled in a future release
- `HMC_REQUIRE_EXECUTE_FLAG` – `true` by default; future write tools will require an explicit execute flag
You can create a `.env` file in the project root:
```bash
HMC_HOST=hmc.example.com
HMC_PORT=12443
HMC_USERNAME=api-user
HMC_PASSWORD=super-secret
HMC_VERIFY_TLS=true
```
(Do **not** commit real credentials.)
### Running the MCP server
Once configured:
```bash
python -m power_hmc_mcp.mcp_server
```
This will start an MCP server process listening over stdio or a specified transport (depending on which MCP SDK adapter you choose). From an MCP-aware client (e.g., LangGraph with MCP adapter), you can connect and call tools like `list_lpars`.
Details on the exact MCP transport and client integration will be filled in as part of the TODO items.
## Examples
Under `examples/`, we will include:
- `langgraph_list_lpars.py` – minimal LangGraph graph that calls the `list_lpars` MCP tool and prints results.
- Additional examples for `create_lpar_from_profile`, `start_lpar`, and `stop_lpar` once those tools are implemented and tested.
## Security and guardrails
This server touches live infrastructure. Design rules:
- Start **read-only**: only `list_*` and `get_*` tools should be enabled in early phases.
- Least privilege: the HMC account used by this server should have the minimum set of permissions required for the exposed tools.
- No credentials in logs: logs must not contain usernames, passwords, tokens, or full HMC URLs with embedded secrets.
- Approval for destructive operations: any future `delete_*` or destructive tools must require explicit approval (e.g., via an out-of-band mechanism, or a separate high-privilege MCP server).
- **Resource IDs** (`managed_system_id`, `lpar_id`) are validated before they are used in HMC URL paths to prevent path traversal.
- **TLS** verification is enabled by default (`HMC_VERIFY_TLS=true`). Disabling TLS or supplying `HMC_CA_BUNDLE` is intended for lab or corporate-PKI setups only.
- **Write MCP tools** remain unregistered by design; enabling them requires explicit code changes in `src/power_hmc_mcp/tools/__init__.py` after guardrails are in place.
- **Allowlist**: set `HMC_ALLOWED_MANAGED_SYSTEMS` to restrict which managed systems appear in list results and which IDs are accepted on system-scoped tools.
## Planned write-tool safety model
Scaffolding lives in [`src/power_hmc_mcp/guardrails.py`](src/power_hmc_mcp/guardrails.py) but is **not wired** to registered MCP tools yet:
- `HMC_ENABLE_WRITE_TOOLS=false` by default blocks write operations at the guardrail layer.
- `HMC_REQUIRE_EXECUTE_FLAG=true` by default will require `execute=true` on future write tool calls.
- `dry_run_response()` provides a stable shape for dry-run previews before execution.
When write tools ship, they will call `check_write_allowed()` before any HMC mutation and remain opt-in via config plus explicit registration in `tools/__init__.py`.
## Roadmap
See `TODO.md` for a detailed implementation checklist and future enhancements.
Contributions, issues, and design discussions are welcome once the basic scaffold is in place.
