git clone https://github.com/your-org/mcp-soc-middleware.git && cd mcp-soc-middleware
cp .env.example .env          # fill in ANTHROPIC_API_KEY at minimum
docker compose up -d          # starts all 5 services

┌─────────────────────────────────────────────────────┐
│                   AI Agent Layer                     │
│         (SOCOrchestrator + Anthropic Claude)         │
└───────────────────────┬─────────────────────────────┘
                        │  MCP  (Bearer Token)
┌───────────────────────▼─────────────────────────────┐
│          MCP Unified Access Layer  :8000             │
│   FastAPI · ToolRegistry · AuditLog · RateLimit      │
└──────────┬────────────────────────┬─────────────────┘
           │                        │
┌──────────▼──────────┐  ┌──────────▼──────────────┐
│   SplunkAdapter     │  │   TheHiveAdapter         │
│  5 MCP tools        │  │  7 MCP tools             │
└──────────┬──────────┘  └──────────┬───────────────┘
           │                        │
┌──────────▼──────────┐  ┌──────────▼──────────────┐
│  Splunk Enterprise  │  │  TheHive 5 + ES 7        │
│  REST API :8089     │  │  REST API :9000          │
└─────────────────────┘  └─────────────────────────┘

mcp-soc-middleware/
├── mcp_server/                  # FastAPI MCP server package
│   ├── main.py                  # App factory, lifespan, MCP endpoints
│   ├── core/
│   │   ├── registry.py          # Dynamic tool registry and adapter loader
│   │   └── auth.py              # Bearer token authentication dependency
│   ├── adapters/
│   │   ├── base_adapter.py      # Abstract adapter contract
│   │   ├── splunk_adapter.py    # Splunk SIEM adapter (5 tools)
│   │   └── thehive_adapter.py   # TheHive SOAR adapter (7 tools)
│   ├── middleware/
│   │   ├── audit.py             # JSONL audit logging middleware
│   │   └── rate_limit.py        # slowapi rate limiter
│   ├── models/
│   │   ├── tool_models.py       # MCP ToolDefinition, Request, Response models
│   │   └── alert_models.py      # Normalised alert / observable schemas
│   └── utils/                   # (extensible — logging helpers, etc.)
│
├── agent/
│   ├── orchestrator.py          # ReAct loop + MCP client + Anthropic API
│   ├── workflows/
│   │   └── triage_workflow.py   # Pre-built task strings for common workflows
│   └── prompts/                 # (extensible — prompt template files)
│
├── config/
│   └── settings.py              # Pydantic-Settings configuration model
│
├── tests/
│   ├── unit/adapters/
│   │   ├── test_splunk_adapter.py
│   │   └── test_thehive_adapter.py
│   ├── integration/             # (full end-to-end tests against live services)
│   └── fixtures/                # Shared test data and factory-boy factories
│
├── scripts/
│   ├── bootstrap.sh             # One-time local setup (venv + .env)
│   └── splunk_bootstrap.sh      # Generate Splunk API token post-startup
│
├── docker/
│   ├── Dockerfile               # Multi-stage image for mcp-middleware service
│   ├── splunk/
│   │   ├── inputs.conf          # Splunk monitor stanza for sample data
│   │   └── sample_alerts.json   # Synthetic SOC alerts for dev seeding
│   └── thehive/
│       └── application.conf     # TheHive minimal config pointing to ES
│
├── logs/                        # Audit JSONL logs (git-ignored)
├── docs/                        # Architecture diagrams and runbooks
├── docker-compose.yml           # Full local dev stack (5 services)
├── requirements.txt             # Pinned Python dependencies
├── pyproject.toml               # Build config, ruff, mypy, pytest settings
├── .env.example                 # All required environment variables with defaults
└── README.md                    # This file

# 1. Bootstrap virtual environment
bash scripts/bootstrap.sh
source .venv/bin/activate

# 2. Start only the platform dependencies via Docker
docker compose up -d splunk elasticsearch thehive

# 3. Generate a Splunk API token (first time only)
bash scripts/splunk_bootstrap.sh
# → Paste the printed token into .env as SPLUNK_TOKEN=...

# 4. Run the MCP server
python -m mcp_server.main
# Server starts at http://localhost:8000

# 5. In a separate terminal: run the AI agent on a triage task
python - <<'EOF'
import asyncio
from agent.orchestrator import SOCOrchestrator
from agent.workflows.triage_workflow import alert_triage_task

async def main():
    agent = SOCOrchestrator()
    result = await agent.run(alert_triage_task(time_window="-4h", severity="high"))
    print(result)

asyncio.run(main())
EOF

pytest                          # all tests with coverage
pytest tests/unit -v            # unit tests only (no live services needed)
pytest tests/integration -v     # requires docker compose up -d

{
  "name": "splunk.search_alerts",
  "arguments": {
    "severity": "high",
    "earliest": "-4h",
    "limit": 50
  }
}

ANTHROPIC_API_KEY=sk-ant-api03-...   # required for AI agent
MCP_BEARER_TOKEN=...                  # any strong random string
SPLUNK_TOKEN=...                      # from scripts/splunk_bootstrap.sh
THEHIVE_API_KEY=...                   # from TheHive UI → Admin → Users