git clone https://github.com/Rushi264/mcp-kafka-observer.git
cd mcp-kafka-observer

# Install dependencies
uv sync

# Start local Kafka
docker compose up -d

# Run tests
uv run pytest -v

{
  "mcpServers": {
    "kafka-observer": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/mcp-kafka-observer",
        "run", "python", "-m", "mcp_kafka_observer.server"
      ],
      "env": {
        "KAFKA_BOOTSTRAP_SERVERS": "localhost:9092"
      }
    }
  }
}

MCP Client (Claude / Cursor / VS Code Copilot)
    │
    │  MCP Protocol (stdio)
    ▼
mcp-kafka-observer
    ├── Tools (get_broker_health, get_consumer_lag, ...)
    ├── Resources (kafka://cluster/overview)
    ├── Prompts (investigate_lag, capacity_review)
    ├── TTL Cache (prevents thundering herd on admin API)
    └── Analyzer (automated lag diagnosis)
    │
    │  confluent-kafka AdminClient
    ▼
Kafka Cluster

# Unit tests (no Kafka needed)
uv run pytest tests/test_server.py -v

# Integration tests (needs Docker Kafka running)
docker compose up -d
uv run pytest tests/test_kafka_client.py -v

# All tests
uv run pytest -v

# Linter
uv run ruff check src/ tests/