Metadata-Version: 2.5
Name: mirastack-redfish-mcp
Version: 0.1.0
Summary: Schema-aware MCP server for Redfish-enabled infrastructure.
Project-URL: Homepage, https://mirastacklabs.ai
Project-URL: Repository, https://github.com/mirastacklabs-ai/mirastack-redfish-mcp
Project-URL: Issues, https://github.com/mirastacklabs-ai/mirastack-redfish-mcp/issues
Project-URL: Documentation, https://github.com/mirastacklabs-ai/mirastack-redfish-mcp#readme
Author: Mirastack Labs
License: Apache-2.0
License-File: LICENSE
Keywords: bmc,idrac,ilo,mcp,openbmc,redfish,xcc
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
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 :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: httpx2>=2.5.0
Requires-Dist: mcp>=2.0.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pyyaml>=6.0.2
Provides-Extra: dev
Requires-Dist: mypy>=1.11.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.2; extra == 'dev'
Requires-Dist: ruff>=0.6.4; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12.20250822; extra == 'dev'
Description-Content-Type: text/markdown

# MIRASTACK Redfish MCP Server

> Governed MCP server for DMTF Redfish-compliant BMCs — iDRAC, iLO, XCC,
> OpenBMC and compatible implementations. **Read-only by default**: mutating
> tools are not registered unless you explicitly raise the write mode, and
> every mutation is a dry-run until confirmed.
>
> Built by [MIRASTACK LABS](https://mirastacklabs.ai). Apache-2.0.

<!-- mcp-name: ai.mirastacklabs/mirastack-redfish-mcp -->

## Highlights

- MCP `stdio` and `streamable-http` transports via the official Python MCP SDK.
- Distilled schema metadata from [DMTF Redfish-Publications](https://github.com/DMTF/Redfish-Publications), pinned to release `2026.1`.
- Protocol-correct Redfish behavior: session auth, ETag/`If-Match`, `202` task polling, and registry-backed error rendering.
- Safe write controls: tiered registration plus dry-run-first confirmations.

## Why this exists

A BMC is a pre-OS, out-of-band control plane with authority above normal host-level root access. Giving an autonomous agent BMC access without strong guardrails creates immediate blast-radius risk across power, boot, firmware, and account boundaries. This server forces dangerous actions behind deliberate write-mode elevation, and keeps every mutation dry-run by default so intent can be reviewed before application. The result is a governed operational interface rather than an always-armed remote control. The model can still move fast on diagnostics, but privilege transitions become explicit and auditable.

## Installation

```bash
pip install mirastack-redfish-mcp
```

## Try it in 60 seconds (no hardware)

Run a local DMTF mockup, start the MCP server in read-only mode, and call a read tool:

```bash
docker compose -f examples/mockup/docker-compose.yml up -d
export MIRASTACK_REDFISH_HOST="http://127.0.0.1:18000"
export MIRASTACK_REDFISH_USERNAME="<bmc-username>"
export MIRASTACK_REDFISH_PASSWORD="<bmc-password>"
export MIRASTACK_REDFISH_WRITE_MODE="off"
mirastack-redfish-mcp --transport stdio
```

Example tool call:

```json
{"tool":"service_info","arguments":{}}
```

Expected output shape:

```json
{
  "endpoint": "default",
  "service_root": {
    "@odata.id": "/redfish/v1"
  },
  "capabilities": {
    "redfish_version": "..."
  }
}
```

## Quick Start (hardware, stdio)

```bash
export MIRASTACK_REDFISH_HOST="https://192.0.2.10"
export MIRASTACK_REDFISH_USERNAME="<bmc-username>"
export MIRASTACK_REDFISH_PASSWORD="<bmc-password>"
export MIRASTACK_REDFISH_WRITE_MODE="off"
mirastack-redfish-mcp --transport stdio
```

## Quick Start (streamable-http)

```bash
mirastack-redfish-mcp \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --path /mcp \
  --stateless-http \
  --json-response
```

> **Warning:** binding to `0.0.0.0` exposes BMC control to every host that can reach this port. Bind to loopback unless the listener sits behind an authenticating proxy on a trusted management network.

## Configuration

### Canonical environment variables

Use `MIRASTACK_REDFISH_*` variables:

- `MIRASTACK_REDFISH_HOST`
- `MIRASTACK_REDFISH_USERNAME`
- `MIRASTACK_REDFISH_PASSWORD` or `MIRASTACK_REDFISH_PASSWORD_FILE`
- optional: `MIRASTACK_REDFISH_VERIFY_SSL` (**default: `true`**), `MIRASTACK_REDFISH_CA_BUNDLE`, `MIRASTACK_REDFISH_TIMEOUT_SEC`, `MIRASTACK_REDFISH_AUTH_MODE`

### Multi-endpoint configuration

Set `MIRASTACK_REDFISH_ENDPOINTS` to inline JSON or a YAML/JSON file:

```json
{
  "idrac-prod": {
    "base_url": "https://192.0.2.10",
    "username": "<bmc-username>",
    "password_file": "/run/secrets/idrac_password",
    "verify_ssl": true,
    "read_only": true
  },
  "ilo-lab": {
    "base_url": "https://192.0.2.11",
    "username": "<bmc-username>",
    "password": "<bmc-password>",
    "verify_ssl": true
  }
}
```

Lab-only override (not recommended for production):

```json
{
  "ilo-lab": {
    "verify_ssl": false
  }
}
```

Set `MIRASTACK_REDFISH_DEFAULT_ENDPOINT` to choose the default endpoint.

### Compatibility

Legacy bare `REDFISH_*` environment variables are still read as a fallback, with a one-time deprecation warning per variable.

### Tool registration profile

- `MIRASTACK_REDFISH_TOOL_PROFILE=full` (default): all toolsets allowed by write mode.
- `MIRASTACK_REDFISH_TOOL_PROFILE=standard`: excludes raw write escape hatches.
- `MIRASTACK_REDFISH_TOOL_PROFILE=core`: curated 15-tool small-model surface.
- `MIRASTACK_REDFISH_TOOLSETS` (comma-separated) overrides profiles with explicit toolsets.

Measured advertised tool-schema payload at `MIRASTACK_REDFISH_WRITE_MODE=full`: core 20,795 bytes (15 tools), standard 43,669 bytes (33 tools), full 54,745 bytes (40 tools). Re-measure with `python3 scripts/check_tool_metadata.py --sizes`.

## Write Safety Model

- `MIRASTACK_REDFISH_WRITE_MODE=off` (default): mutating tools are not registered.
- `MIRASTACK_REDFISH_WRITE_MODE=power`: power/reset/boot control tools are registered.
- `MIRASTACK_REDFISH_WRITE_MODE=config`: config-tier tools are registered.
- `MIRASTACK_REDFISH_WRITE_MODE=full`: full-tier tools are registered.

Every mutating tool accepts `confirm`:

- `confirm=false`: dry-run response (`dry_run=true`, `applied=false`) with `next_step`.
- `confirm=true`: action is applied.

Per-endpoint `read_only=true` overrides global write mode and blocks all writes on that endpoint.

### Tier contract

- **Power tier:** `set_power_state`, `set_boot_override`, `reset_manager`, `cancel_task`
- **Config tier:** `set_bios_attributes`, `eject_virtual_media`, `redfish_patch`, `redfish_post`, `redfish_delete`, `redfish_invoke_action`
- **Full tier:** `insert_virtual_media`, `clear_logs`, `manage_account`, `simple_update`, `reset_to_defaults`

## Development

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
make build-index
make verify
```

The schema index is generated from DMTF Redfish-Publications, pinned to one release for reproducibility. See [CONTRIBUTING.md](CONTRIBUTING.md#schema-corpus) for refresh procedure.

## Registry Publishing Notes

- `server.json` includes PyPI and OCI package definitions for MCP Registry.
- This README carries the required marker: `mcp-name: ai.mirastacklabs/mirastack-redfish-mcp`.
- Docker image includes the `io.modelcontextprotocol.server.name` OCI label.
- Install the official publisher CLI via Homebrew: `brew install mcp-publisher`.
- Do not use `npx mcp-publisher` or `pip install mcp-publisher` for registry publishing.

## Contributing

GitHub is a public **read-only mirror**. Issues are welcome on GitHub, but pull requests opened on GitHub cannot be merged. See [CONTRIBUTING.md](CONTRIBUTING.md) for accepted contribution paths.

## Security

See [SECURITY.md](SECURITY.md).

## License

Apache-2.0.
