Ceph Command Knowledge Base

Verified knowledge base of Ceph CLI commands and config parameters. Ships pre-generated JSON — the MCP does not need a live cluster.

Indexed versions (on disk under knowledge/):

Use this MCP to stop command hallucination: verify a command, flag, argument, or config exists before writing automation or tests.

For agents (read this first)

Always pass version. Accepted aliases: squid, tentacle, 8.1, 9.1, 19, 20. If the user did not name a version, ask (8.1/Squid vs 9.1/Tentacle). Do not silently default.

Typical first calls

1. Infer or ask version → pass it on every subsequent call.

2. verify_command(command="ceph osd pool create", flags=["--size"], version="squid")

3. If NOT_VERIFIED, search_commands(query="...", version=...) then retry.

Status values: VERIFIED, PARTIALLY_VERIFIED, NOT_VERIFIED. Never treat NOT_VERIFIED as “probably fine”.

The index is only as fresh as the last generate_reference.py run on a live cluster. New CLI (for example recently added auth/cipher commands) will be missing until that version is rediscovered — see Updating the knowledge base. Absence from this KB means “not indexed”, not “absent from the product”.

Related MCP server: spec-assistant

Ceph Engineering Intelligence Platform

Combined SSE config:

{
  "mcpServers": {
    "ceph-cmd-kb": { "url": "http://localhost:8081/sse", "transport": "sse" },
    "ceph-doc-kb": { "url": "http://localhost:8082/sse", "transport": "sse" },
    "ceph-issue-kb": { "url": "http://localhost:8083/sse", "transport": "sse" },
    "ceph-prio-hub": { "url": "http://localhost:8080/sse", "transport": "sse" },
    "cephci-kb": { "url": "http://localhost:8084/sse", "transport": "sse" }
  }
}

Setup

git clone https://github.com/pdhiran/ceph-command-kb.git
cd ceph-command-kb
pip install -e .

No Ceph cluster is required to serve. A cluster is required only to rebuild the index.

Incorporate into an agent

Cursor (stdio)

{
  "mcpServers": {
    "ceph-cmd-kb": {
      "command": "python3",
      "args": ["-m", "ceph_command_kb.server.mcp_server"],
      "cwd": "/path/to/ceph-command-kb"
    }
  }
}

The server auto-discovers every knowledge/ceph-*-*/ directory that contains commands.json. --kb-path is optional (a version dir or the knowledge root); sibling versions in that tree are still loaded. Omit it unless you need to point at a non-default tree.

Auto-update is on by default (no extra flags needed): git pull on startup/interval, plus a .reload_trigger watcher so ./update_index.sh hot-reloads without restarting Cursor. --no-auto-update disables both — including the trigger — so Cursor must restart the MCP subprocess after an index update. Interval: --update-interval HOURS (default 1; 0 = startup pull only, trigger still watched). Details: UPDATING.md.

SSE

python3 -m ceph_command_kb.server.mcp_server --transport sse --host 0.0.0.0 --port 8081

Point Claude Desktop (claude_desktop_config.json), Bob (.bob/mcp.json), Continue/Cline/Windsurf at http://localhost:8081/sse.

REST (LangChain, CrewAI, CI)

python3 -m ceph_command_kb.server.rest_api --host 0.0.0.0 --port 9090

curl -X POST http://localhost:9090/api/verify_command \
  -H "Content-Type: application/json" \
  -d '{"command": "ceph osd pool create", "version": "squid"}'

curl -X POST http://localhost:9090/api/verify_config \
  -H "Content-Type: application/json" \
  -d '{"name": "osd_pool_default_size", "version": "tentacle"}'

curl http://localhost:9090/health

Python client and LangChain wrappers: examples/bob_agent_integration.py. Full REST table: BOB_INTEGRATION_GUIDE.md. VS Code extension: vscode-extension/.

Tool catalog

Every command/config tool takes optional version. Omit only when the conversation already pinned a version.

Commands

Configs

Test validation

Also: capabilities, health.

Agent workflow: generating a test snippet

1. Pin version.

2. verify_command for every CLI line (include flags).

3. verify_config for every config name.

4. After drafting the file, review_test(script_content=<full file>).

5. Present automated findings, then contextual analysis (ordering, cleanup, health checks).

Agent workflow: unknown command

1. verify_command → NOT_VERIFIED

2. search_commands / list_subcommands

3. If still missing: say it is not in this KB version; check ceph-doc-kb find_docs_for_command and/or rebuild from a live cluster.

Supported binaries

ceph, rbd, rados, cephadm, ceph-volume, ceph-authtool, ceph-bluestore-tool, ceph-objectstore-tool, crushtool, monmaptool, osdmaptool

Updating the knowledge base

Same --since YYYY-MM-DD contract as python index_issues.py --since DATE.

Command --help has no date filter. --since records the delta window in metadata.json (updated_since, last_incremental_at) and runs a full rediscovery from live binaries (safe: only -h / --help / help). It is not an incremental parse of “commands added since DATE”.

Must run on a node where those binaries are on PATH (cluster admin / cephadm shell host). Copy knowledge/<version>/ back into this repo afterward.

# On a cluster node, from this repo (or a checkout of it)
python3 generate_reference.py --since 2026-08-01 --verbose --force

# Canonical wrapper (last-run tracker + .reload_trigger for in-process MCP reload)
./update_index.sh                 # since yesterday of last success (1-day overlap), or last 1 day if first run
./update_index.sh 7
./update_index.sh 2026-08-01
./update_index.sh --reset

# Re-parse stored raw_help/*.txt without a cluster (see caveats below)
python3 generate_reference.py --reparse --since 2026-08-01

After a successful ./update_index.sh, .last_index_update stores yesterday of the run date (same 1-day overlap as ceph-issue-kb), not the ISO date you passed in.

--reparse only rewrites the last sorted version directory under knowledge/ (today that is tentacle). raw_help/ is gitignored — you need a prior generate_reference.py --docs on that host. Prefer generate_reference.py --reparse over reparse_kb.py (the latter is hardcoded to tentacle).

./update_kb.sh is a compatibility wrapper that execs ./update_index.sh. Do not treat it as the canonical command.

Full maintainer help (hot-reload, git auto-update, no Cursor restart): UPDATING.md.

Other generate flags: --resume, --force, --workers N, --output DIR, --docs (also write markdown + raw help), --config config.yaml.

Config parameters are imported separately via import_configs.py (TSV from ceph --show-config-dump / project pipeline) into knowledge/<version>/configs.json. Pass --kb-dir knowledge/ceph-19.2.1-squid (or tentacle) — the default --kb-dir is tentacle only.

Architecture

Live cluster (optional, generate only)
  DiscoveryEngine runs `<binary> -h` recursively
        │
        ▼
 knowledge/ceph-19.2.1-squid/{commands,configs,search_index,metadata}.json
 knowledge/ceph-20.2.1-tentacle/...
        │
        ▼
 MCP (stdio/SSE) / REST  — no Ceph required

Generation never runs mutating cluster commands. See DEVELOPMENT.md for parsers, validation phases, and project layout.

Development

pip install -e ".[dev]"
pytest