# Experimental Cardano Pool MCP

> **Unmaintained — September 2026.** BEACN's own pool retired at epoch 656, so this starter will not receive updates. It stays public as a reference; read the safety notes below before adapting any of it. [BEACN archive](https://beacnpool.github.io/ABCDE/pool/)

**v0.1.0-experimental — reference implementation, not a turnkey mainnet product.**

An MCP server for inspecting the design of guarded pool maintenance and adapting
it to your own infrastructure. Built from work on a private BEACN deployment.
This distribution contains no private deployment configuration or Git history.

**The default is a local simulation in SAFE mode.** It does not contact Cardano,
read real signing keys, use SSH, or control system services. Every successful
simulation response is labeled. Its health values are synthetic.

The included Linux/SSH adapters can affect a live block producer **only after
separate operator integration**. Bugs, wrong configuration or failed recovery
can interrupt block production. No independent security audit or production
acceptance is claimed for this public version. Validate an isolated testnet
deployment before considering mainnet.

## Start here, SPOs

[Download the experimental starter](https://github.com/BEACNpool/experimental-cardano-pool-mcp/archive/refs/tags/v0.1.0-experimental.zip),
unzip it, and open the extracted folder in a terminal. Follow the quickstart
below to try the **local simulation first**. Fork the repository to adapt it.
Do not point an AI at your production node and ask it to install this blindly.

For a deeper review: [three-mode simulation](docs/DEMO.md),
[architecture and safeguards](docs/ARCHITECTURE.md),
[production integration requirements](docs/INTEGRATION.md), and
[what the tests establish](docs/VALIDATION.md).

## Try it locally

Linux with Python 3.12 or newer. Use an ordinary user, not sudo.

```sh
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock
.venv/bin/python -m pip install --no-deps .
.venv/bin/python scripts/smoke_mcp.py
```

The smoke test uses the actual MCP SDK/stdio transport. It reads simulated
health, creates an inert plan and verifies that SAFE mode refuses execution.
It neither enables maintenance nor connects to a real node.

Register the following with an MCP client, replacing only the executable path:

```json
{
  "mcpServers": {
    "experimental-cardano-pool": {
      "command": "/absolute/path/to/checkout/.venv/bin/cardano-pool-mcp",
      "args": []
    }
  }
}
```

No API token is required for this local MCP. The client may have its own model
provider/account requirements. The default demo is temporary and resets when
the server exits. [Persistent simulation and mode exercises](docs/DEMO.md)
demonstrate assisted approval, experimental execution and failure recovery.

## Three modes

| Mode | Authority |
| --- | --- |
| SAFE (default) | Observation and inert plan/audit writes; no node maintenance. |
| ASSISTED | A separate operator approves an exact, expiring plan digest. |
| EXPERIMENTAL | Explicit opt-in, accepted backend/release, allowed periods and an expiring grant. Disabled by default; maximum 90 days. |

Neither approvals nor mode changes are MCP tools. In production they must be
controlled by an independent operator identity. The demo uses your local user
for both sides to make experimentation convenient; it **does not prove OS
privilege isolation**. An agent with that user's shell access can change demo
policy. An administrator can also bypass a production MCP using separate access.

## Six tools

| Tool | Effect |
| --- | --- |
| `pool_status` | Read health, authority, KES coverage and transaction state. |
| `pool_checks` | Read backend diagnostics; demo results are explicitly synthetic. |
| `pool_audit` | Read a hash-chain-verified operational event log. |
| `rotation_plan` | Write an inert plan for a pre-signed KES period. |
| `rotation_status` | Read the outcome for the same transaction ID. |
| `rotation_execute` | Execute only an authorized plan; SAFE refuses it. |

No shell tool, arbitrary file reader, cold-key path, approval flag or mode setter
is accepted in an MCP request. Strict schemas and runtime validation reject
unexpected fields, invalid types, duplicate JSON keys and oversized frames.

## Rotation and signing boundary

The engine records intent, stages a verified pair, rechecks authority, stops the
services, atomically switches the credential generation, restarts, checks health
and commits. Failure attempts a checked rollback. Unsafe recovery ends in
`RECOVERY_REQUIRED` with startup inhibited. See [architecture](docs/ARCHITECTURE.md).

Fresh cold-key signing is not implemented. The signer interface returns
`SIGNER_REQUIRED`; a finite pre-signed inventory is the only autonomous source.
**Do not copy someone else's KES ladder, counter, genesis anchors or acceptance
record.** This adapter supports a conservative same-counter ladder whose
counter matches the observed chain state. Unknown counters and fresh issuance
require a separate operator review. [Integration limits](docs/INTEGRATION.md).

## What's included

- Runnable stdio MCP simulation, three modes and operator-only demo controls.
- Durable transaction engine, atomic generation logic, approval and audit code.
- Signature verification and a signer abstraction that refuses fresh signing.
- Linux/SSH/broker/launcher/monitor reference adapters and invalid-by-default
  example configuration; **no production installer**.
- Synthetic tests for input rejection, approval tampering, commit/rollback,
  process death, storage failure, startup guards and protocol boundaries.
- MIT license and [security reporting guidance](SECURITY.md).

The private deployment's dashboard, personal host automation, VM power helpers,
real certificates, logs, operational receipts and credentials are excluded.
`pool_status` and `pool_checks` provide the monitoring interface for an optional
dashboard. No public website, HTTP listener or automatic cron is installed.

```sh
.venv/bin/python -m pytest -q
.venv/bin/python scripts/release_check.py
```

See [validation](docs/VALIDATION.md) for what was actually tested. Passing tests
does not establish safety for another operator's production setup.