Ceph Issue Intelligence KB

Searchable knowledge base of 14,600+ Ceph issues from IBM Ceph JIRA and Red Hat KB. Ships pre-built — clone, install, and immediately search known issues, workarounds, and fixes from your AI agent.

Setup

1. Clone and install

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

2. Connect your agent

Choose the integration that matches your agent:

Cursor — add to ~/.cursor/mcp.json:

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

Restart Cursor. The MCP server starts automatically and pulls the latest issue data on startup — no manual git pull needed.

To disable auto-update, add "--no-auto-update" to args.

Claude Desktop — start the server, then add to claude_desktop_config.json:

python -m ceph_issue_kb.server.mcp_server --transport sse --port 8083

{
  "mcpServers": {
    "ceph-issue-kb": { "url": "http://localhost:8083/sse" }
  }
}

Continue / Cline / Windsurf — start the server and point to the SSE endpoint:

python -m ceph_issue_kb.server.mcp_server --transport sse --port 8083

Connect to http://localhost:8083/sse in the tool's MCP settings.

IBM Bob — Bob supports MCP over SSE natively:

python -m ceph_issue_kb.server.mcp_server --transport sse --host 0.0.0.0 --port 8083

Add to Bob's .bob/mcp.json:

{
  "mcpServers": {
    "ceph-issue-kb": {
      "url": "http://localhost:8083/sse",
      "transport": "sse"
    }
  }
}

If running on a shared server, replace localhost with the hostname.

REST API — for LangChain, CrewAI, or CI pipelines:

python -m ceph_issue_kb.server.rest_api --host 0.0.0.0 --port 8200

# Search issues
curl -X POST http://localhost:8200/api/search_issues \
  -H "Content-Type: application/json" \
  -d '{"query": "OSD slow ops", "component": "rados"}'

# Check if an error is a known issue
curl -X POST http://localhost:8200/api/is_known_issue \
  -H "Content-Type: application/json" \
  -d '{"error_message": "FAILED ceph_assert(googly > 0)", "version": "19.2.0"}'

# Find workaround
curl -X POST http://localhost:8200/api/find_workaround \
  -H "Content-Type: application/json" \
  -d '{"query": "too many PGs per OSD"}'

# Health check
curl http://localhost:8200/health

See BOB_INTEGRATION_GUIDE.md for the full REST API reference and agent integration examples.

3. Use it

Once connected, agents automatically check for known Ceph issues. You can also ask directly:

• "Is FAILED ceph_assert(googly > 0) a known issue?"

• "Find workarounds for OSD slow ops during recovery"

• "Search for issues related to HEALTH_WARN too many PGs per OSD"

• "What are the hot issues in the rgw component?"

• "Find issues with this stacktrace: #0 in BlueStore::_do_write"

Related MCP server: ClimateTriage MCP Server

Available Tools

Active Sources

The knowledge base is updated daily by the maintainer with the latest bugs and articles. Your MCP server automatically pulls new data every 12 hours — no action needed on your part.

VS Code Extension

Coming soon. See ceph-doc-kb and ceph-command-kb for existing VS Code extensions that complement this knowledge base.

Documentation

Running All Ceph MCPs Together

Three specialized MCPs work together as the Ceph Engineering Intelligence Platform:

Start all three for SSE clients (Bob, Claude Desktop, etc.):

python -m ceph_command_kb.server.mcp_server --transport sse --port 8081 &
python -m ceph_doc_kb.server.mcp_server --transport sse --port 8082 &
python -m ceph_issue_kb.server.mcp_server --transport sse --port 8083 &

Combined agent config (.bob/mcp.json, claude_desktop_config.json, etc.):

{
  "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" }
  }
}

Development

pip install -e ".[dev]"
pytest

See DEVELOPMENT.md for architecture details and contributing.