Cerbero-mcp/docs/superpowers/specs/2026-04-30-V2.0.0-unified-image-token-routing-design.md

# Cerbero MCP — V2.0.0: Unified Image, Token-Based Environment Routing

**Branch:** `V2.0.0`
**Data spec:** 2026-04-30
**Autore:** Adriano

## Sommario esecutivo

Riscrittura architetturale di Cerbero MCP per ridurre superficie operativa e
semplificare la gestione di testnet/mainnet. Si passa da 7 immagini Docker
(gateway Caddy + 6 servizi MCP) a una **singola immagine** che ospita tutti
i router exchange in un unico processo FastAPI. La distinzione fra ambiente
testnet e mainnet, oggi decisa al boot del container tramite variabili di
override e flag nei secret JSON, viene spostata **a runtime per-request**:
il bearer token presentato dal client (`Authorization: Bearer <token>`)
determina quale endpoint upstream viene contattato per quella specifica
chiamata. Tutta la configurazione confluisce in un singolo file `.env`,
eliminando i secret JSON separati. Viene infine esposta documentazione
OpenAPI interattiva via Swagger UI all'indirizzo `/apidocs`.

## Motivazioni

- **Operatività**: 7 container, 8 secret file, 4 docker-compose overlay e un
  gateway Caddy con plugin di rate-limit sono troppo per il volume di
  traffico atteso. Un singolo container è sufficiente.
- **Flessibilità ambiente**: oggi un bot che vuole leggere mainnet e
  scrivere testnet deve coordinare due deploy. Con il routing per-request
  basta scegliere il bearer giusto per ogni chiamata.
- **Configurazione**: 8 secret JSON + 2 token file + variabili di override
  in 4 compose file = stato distribuito difficile da auditare. Un singolo
  `.env` rende ovvio cosa è configurato.
- **DX dev**: oggi serve `docker compose up` anche per iterare. V2 punta a
  `uv run cerbero-mcp` diretto su laptop senza Docker.
- **Discovery API**: senza Swagger l'unica fonte sulle tool è il codice.
  `/apidocs` rende le tool esplorabili dal browser, e `/openapi.json` le
  rende leggibili a LLM senza bisogno del protocollo MCP completo.

## Decisioni di design

| # | Domanda | Decisione |
|---|---|---|
| 1 | Significato di "passare il token alla funzione" | Routing per-request via bearer: lo stesso container serve testnet e mainnet contemporaneamente, decide URL upstream a runtime |
| 2 | Granularità token | 2 token globali (`TESTNET_TOKEN`, `MAINNET_TOKEN`) validi per tutti gli exchange |
| 3 | ACL core/observer (read-only) | Eliminata. Protezione write rimane via leverage cap server-side e via firewall (Traefik su VPS) |
| 4 | Scope "single image" | Un'unica immagine, **un solo container** con multi-router interno (un processo Python) |
| 5 | Gateway L7 | Eliminato dal repo. Su VPS prod c'è Traefik gestito esternamente. In dev nessun gateway |
| 6 | Formato configurazione | Tutto in `.env`. Nessun JSON. La porta è in `.env` |
| 7 | Swagger | `/apidocs` ON, `/openapi.json` ON, `/redoc` OFF, `/docs` OFF |
| 8a | Dispatch exchange | Path-based: `/mcp-{exchange}/tools/{tool}` (backward-compat con bot V1) |
| 8b | Lifecycle client exchange | Cache lazy `(exchange, env) → client`, max 8 client (4 exchange × 2 env) + 2 client read-only (macro, sentiment) |

Decisioni esplicite anche su:

- **Macro e sentiment richiedono token valido**: anche le tool puramente
  read-only passano dal middleware auth. Bearer assente o non riconosciuto
  → 401. Il valore del token (testnet o mainnet) è ignorato per macro e
  sentiment perché non hanno endpoint testnet, ma uno dei due deve essere
  presente.
- **Nessuna policy `ALLOW_MAINNET`**: la protezione contro uso accidentale
  di mainnet è demandata a (a) custodia dei token (mainnet token solo a bot
  autorizzati), (b) Traefik IP allowlist sul VPS, (c) leverage cap
  server-side già esistente per ogni exchange.
- **`docker-compose.yml` minimo** mantenuto per chi vuole usare Docker
  localmente; `docker-compose.{prod,traefik,local}.yml` eliminati.

## Architettura

### Stack runtime

```
Prod (VPS):
  Traefik (TLS, allowlist) ──▶ container cerbero-mcp:9000

Dev (laptop):
  uv run cerbero-mcp ──▶ http://localhost:9000
```

Nessun gateway nel repo. Traefik è gestito fuori da questo progetto, con
label aggiunte tramite override compose esterno. In dev FastAPI è esposto
direttamente via uvicorn.

### Struttura sorgenti

```
Cerbero_mcp/
├── pyproject.toml              # singolo package "cerbero-mcp"
├── uv.lock
├── Dockerfile                  # multi-stage builder + runtime slim
├── docker-compose.yml          # minimo: 1 servizio, env_file: .env
├── .env.example                # template completo, versionato
├── .gitignore                  # .env escluso
├── README.md                   # riscritto V2
│
├── docs/
│   └── superpowers/
│       ├── specs/
│       │   ├── 2026-04-27-cot-report-design.md           (storico)
│       │   └── 2026-04-30-V2.0.0-unified-image-...-design.md
│       └── plans/
│           ├── 2026-04-27-cot-report.md                  (storico)
│           └── 2026-04-30-V2.0.0-unified-image-...-plan.md
│
├── src/cerbero_mcp/
│   ├── __init__.py
│   ├── __main__.py             # entrypoint: uvicorn.run(app, ...)
│   ├── settings.py             # Pydantic Settings per .env
│   ├── auth.py                 # bearer → environment
│   ├── server.py               # build_app(): FastAPI + middleware + handlers + swagger
│   ├── client_registry.py      # cache lazy {(exchange, env): client}
│   ├── routers/
│   │   ├── __init__.py
│   │   ├── deribit.py
│   │   ├── bybit.py
│   │   ├── hyperliquid.py
│   │   ├── alpaca.py
│   │   ├── macro.py
│   │   └── sentiment.py
│   ├── exchanges/
│   │   ├── deribit/{client.py, tools.py, leverage_cap.py}
│   │   ├── bybit/{client.py, tools.py, leverage_cap.py}
│   │   ├── hyperliquid/{client.py, tools.py, leverage_cap.py}
│   │   ├── alpaca/{client.py, tools.py, leverage_cap.py}
│   │   ├── macro/{client.py, tools.py}
│   │   └── sentiment/{client.py, tools.py}
│   └── common/
│       ├── indicators.py
│       ├── options.py
│       ├── microstructure.py
│       ├── stats.py
│       ├── http.py
│       ├── audit.py
│       ├── logging.py
│       └── errors.py           # error envelope
│
├── tests/
│   ├── unit/
│   ├── integration/
│   └── smoke/
│
└── scripts/
    └── build-push.sh           # build di 1 sola immagine
```

**Cosa viene eliminato:**

- `services/` (intera struttura monorepo a 7 sub-package, sostituita da
  `src/cerbero_mcp/`)
- `gateway/` (Caddy + Caddyfile + landing page)
- `secrets/` (8 file JSON + 2 token file)
- `docker/` (7 Dockerfile separati, sostituiti da `Dockerfile` in root)
- `docker-compose.prod.yml`, `docker-compose.local.yml`,
  `docker-compose.traefik.yml`
- `DEPLOYMENT.md` (i contenuti ancora validi confluiscono in `README.md`)
- `mcp_common.environment` (resolver boot-time, sostituito da `auth.py`
  runtime)
- `mcp_common.env_validation` (sostituito da Pydantic Settings)
- `mcp_common.app_factory` (boilerplate boot, integrato in `server.py`)

**Cosa resta uguale:**

- Path layout `/mcp-{exchange}/tools/{tool}` (backward-compat con bot V1)
- Tool MCP individuali: firme, response shape, error envelope, header
  `X-Data-Timestamp` e `X-Duration-Ms`
- Logica indicatori quantitativi (`indicators`, `options`,
  `microstructure`, `stats`)
- Healthcheck `/health` (formato identico)
- Leverage cap server-side per exchange
- Tool MCP-bridge (se in uso) preservato in `common/mcp_bridge.py`

### Flusso request

```
1. Bot HTTP request
   POST /mcp-deribit/tools/place_order
   Authorization: Bearer tk_test_xxx
   { "symbol":"BTC-PERPETUAL", "side":"buy", "qty": 0.1 }

2. Middleware AuthBearer (auth.py)
   - whitelist path: /apidocs, /openapi.json, /health → bypass
   - estrae bearer
   - confronta con settings.testnet_token / settings.mainnet_token
   - match testnet  → request.state.environment = "testnet"
   - match mainnet  → request.state.environment = "mainnet"
   - nessun match   → 401 UNAUTHORIZED

3. Router deribit (routers/deribit.py)
   - FastAPI valida body con Pydantic schema
   - dependency get_env(request) -> "testnet"|"mainnet"
   - dependency get_client(env) -> DeribitClient

4. Client Registry (client_registry.py)
   - chiave (exchange="deribit", env="testnet")
   - cache hit → return; miss → costruisce client lazy + auth iniziale + cache

5. Tool impl (exchanges/deribit/tools.py)
   - leverage_cap.enforce(qty, max_leverage)
   - client.place_order(...)
   - response shape standard con data_timestamp, request_id

6. Response middleware
   - X-Duration-Ms header
   - data_timestamp injection se mancante

7. 200 JSON
```

### Auth

```python
# src/cerbero_mcp/auth.py (esempio sintetico)
from fastapi import Request, HTTPException, status
from typing import Literal

Environment = Literal["testnet", "mainnet"]

WHITELIST_PATHS = {"/health", "/apidocs", "/openapi.json"}

async def auth_middleware(request: Request, call_next):
    if request.url.path in WHITELIST_PATHS:
        return await call_next(request)
    auth = request.headers.get("Authorization", "")
    if not auth.startswith("Bearer "):
        raise HTTPException(401, "missing bearer token")
    token = auth[len("Bearer "):].strip()
    settings = request.app.state.settings
    if token == settings.testnet_token.get_secret_value():
        request.state.environment = "testnet"
    elif token == settings.mainnet_token.get_secret_value():
        request.state.environment = "mainnet"
    else:
        raise HTTPException(401, "invalid token")
    return await call_next(request)
```

Confronto token con `secrets.compare_digest` per evitare timing attack.

### Client registry

```python
# src/cerbero_mcp/client_registry.py (sintesi)
class ClientRegistry:
    def __init__(self, settings):
        self._settings = settings
        self._clients: dict[tuple[str, Environment], Any] = {}
        self._locks: dict[tuple[str, Environment], asyncio.Lock] = defaultdict(asyncio.Lock)

    async def get(self, exchange: str, env: Environment) -> Any:
        key = (exchange, env)
        if key in self._clients:
            return self._clients[key]
        async with self._locks[key]:
            if key in self._clients:
                return self._clients[key]
            client = await self._build(exchange, env)
            self._clients[key] = client
            return client

    async def aclose(self):
        for c in self._clients.values():
            await c.aclose()
```

- Costruzione **lazy** al primo uso → boot rapido, no auth verso exchange
  non usati
- **Lock per chiave** evita doppia istanziazione in caso di race
- Macro e sentiment usano stesso client per testnet e mainnet (l'env è
  ignorato), ma per uniformità API ricevono ugualmente la chiave
  `(exchange, env)`
- Lifespan FastAPI: registry creato in `startup`, chiuso in `shutdown`
  (chiude HTTP pool, websocket eventuali, sessioni)

### Configurazione: `.env`

Singola sorgente di verità, letta da Pydantic Settings al boot. File
versionato come `.env.example` con placeholder vuoti; `.env` reale
gitignored.

```bash
# SERVER
HOST=0.0.0.0
PORT=9000
LOG_LEVEL=info

# AUTH
TESTNET_TOKEN=
MAINNET_TOKEN=

# DERIBIT
DERIBIT_CLIENT_ID=
DERIBIT_CLIENT_SECRET=
DERIBIT_URL_LIVE=https://www.deribit.com/api/v2
DERIBIT_URL_TESTNET=https://test.deribit.com/api/v2
DERIBIT_MAX_LEVERAGE=3

# BYBIT
BYBIT_API_KEY=
BYBIT_API_SECRET=
BYBIT_URL_LIVE=https://api.bybit.com
BYBIT_URL_TESTNET=https://api-testnet.bybit.com
BYBIT_MAX_LEVERAGE=3

# HYPERLIQUID
HYPERLIQUID_WALLET_ADDRESS=
HYPERLIQUID_API_WALLET_ADDRESS=
HYPERLIQUID_PRIVATE_KEY=
HYPERLIQUID_URL_LIVE=https://api.hyperliquid.xyz
HYPERLIQUID_URL_TESTNET=https://api.hyperliquid-testnet.xyz
HYPERLIQUID_MAX_LEVERAGE=3

# ALPACA
ALPACA_API_KEY_ID=
ALPACA_SECRET_KEY=
ALPACA_URL_LIVE=https://api.alpaca.markets
ALPACA_URL_TESTNET=https://paper-api.alpaca.markets
ALPACA_MAX_LEVERAGE=1

# MACRO
FRED_API_KEY=
FINNHUB_API_KEY=

# SENTIMENT
CRYPTOPANIC_KEY=
LUNARCRUSH_KEY=
```

Pydantic Settings con `SecretStr` per i valori sensibili evita leak nei
log/repr. `extra="ignore"` ammette env aggiuntive (variabili di sistema,
Docker) senza crash. Validation fail-fast al boot.

### Swagger / OpenAPI

```python
app = FastAPI(
    title="Cerbero MCP",
    version="2.0.0",
    description="Multi-exchange MCP server. Bearer token decides environment (testnet/mainnet).",
    docs_url="/apidocs",
    redoc_url=None,
    openapi_url="/openapi.json",
    swagger_ui_parameters={
        "persistAuthorization": True,
        "displayRequestDuration": True,
        "filter": True,
        "tryItOutEnabled": True,
        "tagsSorter": "alpha",
        "operationsSorter": "alpha",
    },
)
```

Aggiunto `securityScheme = BearerAuth` su tutti gli endpoint sotto `/mcp-*`.
Click su Authorize in Swagger → input bearer → tutte le richieste "Try it
out" mandano il header. Cambio token = cambio ambiente senza ricaricare.

Tag organizzati per exchange:
- `system` → `/health`
- `deribit`, `bybit`, `hyperliquid`, `alpaca`, `macro`, `sentiment` → tool
  rispettive

Ogni request body Pydantic include `examples=[...]` con almeno un esempio
realistico. Per response shape complesse (gamma profile, orderbook
imbalance) anche le response Pydantic includono examples.

### Dockerfile e immagine

```dockerfile
# syntax=docker/dockerfile:1.7

FROM python:3.11-slim AS builder
RUN apt-get update && apt-get install -y --no-install-recommends \
        build-essential curl && rm -rf /var/lib/apt/lists/*
RUN pip install --no-cache-dir "uv>=0.5,<0.7"
WORKDIR /app
COPY pyproject.toml uv.lock ./
COPY src ./src
RUN uv sync --frozen --no-dev

FROM python:3.11-slim AS runtime
LABEL org.opencontainers.image.title="cerbero-mcp" \
      org.opencontainers.image.version="2.0.0"
WORKDIR /app
COPY --from=builder /app /app
ENV PATH="/app/.venv/bin:$PATH" \
    HOST=0.0.0.0 \
    PORT=9000 \
    PYTHONUNBUFFERED=1
RUN useradd -m -u 1000 app && chown -R app:app /app
USER app
EXPOSE 9000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 --start-period=10s \
    CMD python -c "import os, urllib.request; urllib.request.urlopen(f'http://localhost:{os.environ.get(\"PORT\",\"9000\")}/health', timeout=3).close()"
CMD ["cerbero-mcp"]
```

- 1 sola immagine `cerbero-mcp:2.0.0` (+ `:latest`)
- Build attesa: ~2-3 min (vs ~12 min × 7 immagini in V1)
- Image size attesa: ~200 MB
- Non-root user `app:1000`
- Healthcheck legge `PORT` da env (rispetta override `.env`)

### docker-compose.yml minimo

```yaml
services:
  cerbero-mcp:
    image: cerbero-mcp:2.0.0
    build: .
    container_name: cerbero-mcp
    ports:
      - "${PORT:-9000}:${PORT:-9000}"
    env_file: .env
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-c",
             "import os, urllib.request; urllib.request.urlopen(f'http://localhost:{os.environ.get(\"PORT\",\"9000\")}/health', timeout=3).close()"]
      interval: 30s
      timeout: 5s
      retries: 3
```

Su VPS si estende con override esterno per applicare label Traefik (file
non versionato in questo repo).

## Errori

| Caso | Status | Code |
|---|---|---|
| Manca header Authorization | 401 | UNAUTHORIZED |
| Token non in `{testnet, mainnet}` | 401 | UNAUTHORIZED |
| Body invalido (Pydantic) | 422 | INVALID_INPUT |
| Exchange upstream 5xx | 502 | UPSTREAM_ERROR |
| Rate limit upstream | 429 | RATE_LIMIT |
| Eccezione non gestita | 500 | UNHANDLED_EXCEPTION |

Error envelope identico a V1: campi `error.{type, code, message,
retryable, suggested_fix?, details?}`, `request_id`, `data_timestamp`.

## Test plan

**Unit:**

- `auth.py`: 4 casi (no header, header malformato, token testnet, token
  mainnet, token invalido). Verifica che `request.state.environment` sia
  settato correttamente.
- `auth.py`: confronto token usa `secrets.compare_digest` (verifica con
  test che attivi entrambi i rami).
- `auth.py`: path whitelist (`/health`, `/apidocs`, `/openapi.json`)
  bypassano il middleware.
- `client_registry.py`: concorrenza — 10 task `get(deribit, testnet)` in
  parallelo, `_build` chiamato 1 sola volta.
- `client_registry.py`: chiavi diverse istanziano client diversi
  (deribit/testnet ≠ deribit/mainnet ≠ bybit/testnet).
- `settings.py`: `.env` valido carica senza errori; campo mandatory
  mancante solleva ValidationError al boot.
- `common/`: tutti i test esistenti su indicators, options,
  microstructure, stats migrano 1:1.
- Per ogni `exchanges/{exchange}/tools.py`: tool con stub client
  restituisce response shape attesa (test esistenti V1 migrati).

**Integration:**

- Stub HTTP che intercetta richieste verso URL deribit:
  - request con `Bearer TESTNET_TOKEN` colpisce `DERIBIT_URL_TESTNET`
  - request con `Bearer MAINNET_TOKEN` colpisce `DERIBIT_URL_LIVE`
- Stesso pattern per bybit, hyperliquid, alpaca.
- Macro e sentiment: request con bearer testnet o mainnet entrambe
  funzionanti, request senza bearer → 401.
- Swagger UI: `GET /apidocs` ritorna HTML con securityScheme BearerAuth
  presente.
- OpenAPI: `GET /openapi.json` ritorna schema valido OpenAPI 3.1 con tag
  per ogni exchange.

**Smoke (post-deploy):**

```bash
curl -s http://localhost:9000/health
curl -s http://localhost:9000/apidocs | grep -q "Cerbero MCP"
curl -s -H "Authorization: Bearer $TESTNET_TOKEN" \
     http://localhost:9000/mcp-deribit/tools/get_ticker \
     -d '{"instrument": "BTC-PERPETUAL"}'
```

## Migrazione da V1

Per chi è in produzione su V1:

1. **Backup**: `cp -r secrets/ secrets.v1.bak/`.
2. **Genera token V2**:
   ```bash
   python -c 'import secrets; print("TESTNET_TOKEN=" + secrets.token_urlsafe(32))'
   python -c 'import secrets; print("MAINNET_TOKEN=" + secrets.token_urlsafe(32))'
   ```
3. **Compila `.env`**: mappa V1 → V2 (i campi nei JSON V1 hanno nomi
   leggermente diversi; vedi tabella in README V2 sezione "Migrazione").
4. **Aggiorna bot client**:
   - URL invariato (`/mcp-{exchange}/tools/{tool}` non cambia)
   - Bearer cambia: dove prima usavi `core.token` o `observer.token`, ora
     usi `TESTNET_TOKEN` o `MAINNET_TOKEN` a seconda dell'ambiente
     desiderato per quella richiesta.
5. **Spegni V1**: `docker compose down` (vecchio compose).
6. **Avvia V2**: `docker compose up -d` (nuovo compose minimo) +
   verifica `curl /health` e `curl /apidocs`.
7. **Rollback** disponibile pullando i tag immagine V1 (`cerbero-mcp-*:1.x`)
   se necessario, ma .env e secrets/ sono incompatibili tra V1 e V2 —
   tenere backup separati.

## Pulizia documentazione

| File | V1 | Azione V2 |
|---|---|---|
| `README.md` | descrive 6 servizi + Caddy + 8 secret + build push 8 immagini | Riscritto da zero |
| `DEPLOYMENT.md` | runbook 7 immagini, gateway Caddy, allowlist Caddy, deploy no-clone | **Eliminato**. Contenuti utili in `README.md` |
| `docs/superpowers/specs/2026-04-27-cot-report-design.md` | spec feature passata | Mantenuto (storico) |
| `docs/superpowers/plans/2026-04-27-cot-report.md` | plan feature passata | Mantenuto (storico) |
| `docs/superpowers/specs/2026-04-30-V2.0.0-...-design.md` | (nuovo) | Creato |
| `docs/superpowers/plans/2026-04-30-V2.0.0-...-plan.md` | (nuovo) | Creato dopo writing-plans |

Razionale eliminazione `DEPLOYMENT.md`: 16 KB di doc su build-push 8
immagini, gateway Caddy, secret mounts, IP allowlist Caddy, deploy
no-clone — tutto obsoleto in V2. Le 30 righe ancora valide (smoke test,
rollback Watchtower) sono integrate nella sezione "Deploy" del nuovo
`README.md`.

## Out of scope

Per evitare scope creep nello stesso sprint, restano fuori:

- **HSTS / security headers** custom: in V1 li gestiva Caddy. In V2 si
  delegano a Traefik su VPS (gestito esternamente). Aggiunta a livello
  applicativo non in V2.
- **Rate limit applicativo** (`slowapi` o simile): demandato a Traefik.
- **Metriche Prometheus**: rinviate a iterazione successiva.
- **Token rotation automatica**: fuori scope V2. Rotation manuale
  modificando `.env` + restart container.
- **Telemetria audit trail**: `mcp_common.audit` viene preservato, ma
  evoluzioni (struttura log, sink) rinviate.
- **Multi-account per exchange**: V2 supporta 1 account per exchange. Più
  account = future iterazione.

## Rischi e mitigazioni

| Rischio | Probabilità | Mitigazione |
|---|---|---|
| Bug auth → token testnet finisce su URL mainnet | Bassa, alto impatto | Test integration con stub HTTP per ogni exchange; leverage cap server-side resta secondo livello di difesa |
| Cache `client_registry` non rilascia connessioni → leak fd | Media | Lifespan FastAPI chiama `aclose()` su shutdown; healthcheck monitora processo |
| Boot fail per env var mancante in `.env` | Alta in dev | Pydantic Settings fail-fast con messaggio chiaro; `.env.example` versionato |
| Migrazione V1→V2 disallineata bot | Media | Path API invariato; documentare mapping V1→V2 in README |
| Concorrenza: prima request mainnet e testnet sullo stesso exchange in parallelo | Media | Lock per chiave nel registry impedisce race su `_build` |
| Image size cresce inattesa | Bassa | Multi-stage slim, base python:3.11-slim, no dipendenze inutili |

## Criteri di successo

- ✅ `docker compose up -d` avvia 1 container che risponde su `/health`
  entro 5 secondi
- ✅ `curl /apidocs` rende Swagger UI navigabile
- ✅ Bot V1 funziona con cambio bearer e basta (path identici)
- ✅ Stesso bot può alternare testnet e mainnet su request consecutive
  cambiando solo bearer
- ✅ Tutti i test V1 migrati passano in V2
- ✅ Tempo di build immagine ridotto da ~12 min a ~3 min
- ✅ `services/`, `gateway/`, `secrets/`, `docker/`, `DEPLOYMENT.md`,
  3 docker-compose overlay rimossi dal repo