{
  "markdown": "<!-- mcp-name: io.github.AIops-tools/ceph-aiops -->\n\n# Ceph AIops\n\n> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by the Ceph project or any storage vendor.** Product and trademark names belong to their owners. MIT licensed.\n\nGoverned AI-ops for **Ceph** — talks to a vanilla **ceph-mgr Dashboard REST API**\n(HTTPS `:8443`, username + password exchanged for a short-lived JWT at\n`POST /api/auth`) with a **built-in governance harness**: unified audit log,\ntoken/runaway budget guard, undo-token recording, and descriptive risk tiers.\nWorks against stock ceph-mgr — **cephadm**,\n**hypervisor-bundled Ceph**, or **MicroCeph** — with **no croit and no Kubernetes\ndependency**. Self-contained: no external skill-family dependency.\n\n## What it does\n\nThe flagship analysis, plus the guarded reads and writes around it:\n\n- **`cluster_health` — HEALTH_WARN/ERR root-cause analysis.** Instead of echoing\n  raw check codes (`PG_DEGRADED`, `OSD_NEARFULL`, `SLOW_OPS`, `MON_DOWN`,\n  `LARGE_OMAP_OBJECTS`, …), it turns each *active* check into plain language:\n  **what it means, the likely cause, and the suggested next action**. This is the\n  differentiator vs the hobby Ceph MCPs that just proxy `ceph -s`.\n- **Governed destructive ops.** The operations operators actually fear —\n  `osd_purge`, `pool_delete`, `set_pool_size`, `rbd_image_delete` — carry\n  **dry-run + double-confirm** and a **high** risk tier; reversible tuning\n  (`osd_reweight`, `throttle_recovery`, `cluster_flag_set`, pool quota/pg_num/\n  autoscale) records an **undo descriptor** capturing the prior state.\n\n## What this tool does, and does not, decide\n\nIt delivers Ceph operations — reads and writes — accurately and efficiently, and\nrecords every one of them. It does **not** decide whether a write is allowed to\nhappen. That is the agent's judgement, or the permission of the account you\nconnect it with: give it a ceph-mgr Dashboard account with a read-only role and\nthe writes fail at the mgr — the place that actually owns the permission.\n\nSo there is no read-only switch, no policy file, no approval gate to configure.\nThe one thing the tool guarantees is that nothing is silent: **every call, over\nMCP and over the CLI alike, lands an audit row** in `~/.ceph-aiops/audit.db`,\nand destructive writes still capture their before-state and record an inverse\nwhere one exists.\n\n> Each tool declares a `risk_level`, kept in agreement with its `[READ]`/`[WRITE]`\n> documentation tag by a test, and carried into the audit row as a descriptive\n> tier — so a reviewer can see at a glance that a row was a high-risk delete. It\n> is a label, not a gate.\n\n## What works\n\n- **CLI** (`ceph-aiops ...`): `init`, `overview`, `health detail`/`health status`,\n  `osd tree/df/reweight/out/purge`, `secret set/list/rm/migrate/rotate-password`,\n  `doctor`, `mcp`. `osd out` and `osd purge` require `--dry-run` + double confirm.\n- **MCP server** (`ceph-aiops mcp` or `ceph-aiops-mcp`): the full **37 tools**\n  (17 read, 18 write, 2 undo), every one wrapped with the bundled `@governed_tool`\n  harness. The CLI is a convenience subset; the MCP surface is the whole tool.\n- **Encrypted credentials**: the Dashboard password lives in an encrypted store\n  `~/.ceph-aiops/secrets.enc` (Fernet + scrypt) — **never plaintext on disk**.\n  Unlock with a master password from `CEPH_AIOPS_MASTER_PASSWORD` (MCP/CI) or an\n  interactive prompt (CLI).\n- **Reversibility**: reversible writes capture the prior state and record an\n  inverse undo descriptor (e.g. `osd_reweight` → prior weight, `set_pool_quota`\n  → prior quota, `throttle_recovery` → prior backfill/recovery settings).\n- **Safety**: destructive ops (`osd_purge`, `osd_mark_out`, `pool_delete`,\n  `set_pool_size`, `rbd_image_delete`, `rbd_snapshot_delete`) are `high` risk\n  with `dry_run` and CLI double confirmation.\n\n## Capability matrix (37 MCP tools)\n\n| Group | Tools | Count | R/W |\n|-------|-------|:-----:|:---:|\n| **Health** | `cluster_health` (flagship RCA), `cluster_status` | 2 | read |\n| **OSD** | `osd_tree`, `osd_df`, `osd_perf` | 3 | read |\n| | `cluster_flag_set` (low, undo), `osd_reweight` (med, undo), `osd_mark_in` (med, undo) | 3 | write |\n| | `osd_mark_out` (high, dry-run), `osd_purge` (high, dry-run) | 2 | write |\n| **PG** | `pg_summary`, `pg_dump_stuck`, `scrub_status` | 3 | read |\n| | `trigger_scrub` (low), `trigger_deep_scrub` (low) | 2 | write |\n| **Pool** | `pool_ls`, `pool_df` | 2 | read |\n| | `set_pool_quota` (med, undo), `set_pool_pg_num` (med, undo), `set_pool_autoscale` (med, undo), `pool_create` (med) | 4 | write |\n| | `set_pool_size` (high, dry-run), `pool_delete` (high, dry-run) | 2 | write |\n| **RBD** | `rbd_ls` | 1 | read |\n| | `rbd_image_create` (med), `rbd_snapshot_create` (low) | 2 | write |\n| | `rbd_image_delete` (high, dry-run), `rbd_snapshot_delete` (high, dry-run) | 2 | write |\n| **CephFS / RGW** | `cephfs_status`, `rgw_status` | 2 | read |\n| **Cluster-ops** | `mon_status`, `mgr_status`, `slow_ops`, `capacity_forecast` | 4 | read |\n| | `throttle_recovery` (med, undo) | 1 | write |\n| **Undo** | `undo_list`, `undo_apply` | 2 | undo |\n\nTotals: **37 tools — 17 read, 18 write, 2 undo.**\n\n## Quick start\n\n### As a Claude Code plugin\n\nOne install gives an agent both the skill and the MCP server:\n\n```\n/plugin marketplace add AIops-tools/marketplace\n/plugin install ceph-aiops@aiops-tools\n```\n\nThe MCP server is fetched with [uv](https://docs.astral.sh/uv/) and pinned to the\npackage version this plugin declares, so an audit row can be traced back to the\ncode that wrote it. Credentials are still configured with `ceph-aiops init` — see below.\n\n### As a CLI or standalone MCP server\n\n```bash\nuv tool install ceph-aiops          # or: pipx install ceph-aiops\nceph-aiops init                     # wizard: add a mgr target + store the Dashboard password (encrypted)\nceph-aiops doctor                   # JWT login + mgr-dashboard reachability\nceph-aiops overview                 # HEALTH status + active checks + OSD up/in\nceph-aiops health detail            # decode the active HEALTH_WARN/ERR checks (RCA)\nceph-aiops osd df                   # per-OSD utilization, most-full first, near/backfill-full flags\n```\n\nRun as an MCP server (stdio):\n\n```bash\nexport CEPH_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively\nceph-aiops-mcp\n```\n\n## Governance\n\nEvery operation — MCP **and** CLI — passes through the bundled `@governed_tool`\nharness. It records; it does not authorize (see above).\n\n- **Audit** — every call (params, result, status, duration, risk tier, and any\n  operator-supplied approver/rationale) is logged to `~/.ceph-aiops/audit.db`\n  (relocatable via `CEPH_AIOPS_HOME`). The CLI writes the same row the MCP path\n  does — there is no unaudited entry point.\n- **Runaway guard** — a safety backstop, not an authorization gate: the same\n  call hammered in a tight loop trips a circuit breaker so a stuck agent can't\n  burn unbounded calls/time. Disable with `CEPH_RUNAWAY_MAX=0`; optional hard\n  ceilings via `CEPH_MAX_TOOL_CALLS` / `CEPH_MAX_TOOL_SECONDS`.\n- **Undo recording** — reversible writes record an inverse descriptor built from\n  the fetched before-state.\n- **Risk tier** — a descriptive label on the audit row derived from\n  `risk_level`; it gates nothing.\n\n## Supported scope & limitations\n\n- **Deployments**: vanilla ceph-mgr with the **dashboard** module enabled —\n  cephadm, hypervisor-bundled Ceph, or MicroCeph. **No croit, no Kubernetes\n  dependency.**\n- **Ceph has no ETag / pagination** on the Dashboard API, so this tool exposes\n  none — nothing is missing, the upstream API simply doesn't offer them.\n- **Validation status**: behaviour is exercised against mocked Dashboard\n  responses by the test suite; multi-node rebalance and the write ops have not\n  been run against a live cluster. The cheapest live check is a single-node\n  **MicroCeph** (`snap install microceph` → bootstrap → loop-file OSDs) running\n  `ceph-aiops doctor`; a 3-node Vagrant cluster exercises real rebalance\n  behaviour. See [`docs/VERIFICATION.md`](docs/VERIFICATION.md) for the full\n  live-verification checklist.\n\n## Missing a capability?\n\nRGW multisite, per-daemon config sprawl, NFS-Ganesha exports, orchestrator\n(cephadm) host management — not here yet. **Open an issue or send a PR** — feedback\nand contributions are welcome.\n",
  "bytes": 8364,
  "sha": "6f1a041e5610990d1fdafbdfcce089fc8a48bb56f8fc1ef76956721f5aa97c90",
  "repo_slug": "aiops-tools/ceph-aiops",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aiops_tools_ceph_aiops_c56759a8/readme"
}