Cerbero-mcp/README.md

Cerbero MCP — V2.0.0

Server MCP unificato multi-exchange per la suite Cerbero. Distribuito come singola immagine Docker; testnet e mainnet sono raggiungibili contemporaneamente attraverso un meccanismo di routing per-request basato sul token bearer fornito dal client.

Caratteristiche

• Una singola immagine Docker (cerbero-mcp) ospita tutti i router exchange in un unico processo FastAPI
• Quattro exchange (Deribit, Bybit, Hyperliquid, Alpaca) e due data provider read-only (Macro, Sentiment)
• Switch testnet/mainnet per-request tramite header Authorization: Bearer <TOKEN>: lo stesso container serve entrambi gli ambienti senza riavvii
• Configurazione interamente in .env: nessun file JSON di credenziali separato
• Documentazione interattiva OpenAPI/Swagger esposta a /apidocs

Avvio rapido (sviluppo, senza Docker)

1. Copiare il template di configurazione e compilarlo:

   cp .env.example .env
   # editare .env con le proprie credenziali e i due token
   

2. Generare i token bearer:

   python -c 'import secrets; print("TESTNET_TOKEN=" + secrets.token_urlsafe(32))'
   python -c 'import secrets; print("MAINNET_TOKEN=" + secrets.token_urlsafe(32))'
   

3. Installare le dipendenze e avviare:

   uv sync
   uv run cerbero-mcp
   

4. Aprire la documentazione interattiva: http://localhost:9000/apidocs

Avvio con Docker

cp .env.example .env  # compilare valori
docker compose up -d

Il container espone la porta indicata da PORT in .env (default 9000).

Token bearer e ambienti

Token usato	Ambiente upstream
Authorization: Bearer $TESTNET_TOKEN	URL testnet di ciascun exchange
Authorization: Bearer $MAINNET_TOKEN	URL mainnet (live)
Nessun token / token sconosciuto	401 Unauthorized

Le tool puramente read-only (/mcp-macro/* e /mcp-sentiment/*) richiedono comunque un bearer valido, ma il valore (testnet o mainnet) è indifferente perché non hanno endpoint testnet.

Endpoint principali

Path	Descrizione
GET /health	Healthcheck (no auth)
GET /apidocs	Swagger UI (no auth)
GET /openapi.json	Schema OpenAPI 3.1 (no auth)
POST /mcp-deribit/tools/{tool}	Tool exchange Deribit
POST /mcp-bybit/tools/{tool}	Tool exchange Bybit
POST /mcp-hyperliquid/tools/{tool}	Tool exchange Hyperliquid
POST /mcp-alpaca/tools/{tool}	Tool exchange Alpaca
POST /mcp-macro/tools/{tool}	Tool macro/market data
POST /mcp-sentiment/tools/{tool}	Tool sentiment/news

Tool disponibili

Common (cerbero_mcp.common.indicators + options + microstructure + stats)

Tecnici (sma, rsi, macd, atr, adx), volatilità (vol_cone, garch11_forecast), statistici (hurst_exponent, half_life_mean_reversion, cointegration_test), risk (rolling_sharpe, var_cvar), microstructure (orderbook_imbalance), options (oi_weighted_skew, smile_asymmetry, dealer_gamma_profile, vanna_charm_aggregate).

Deribit

DVOL, GEX, P/C ratio, skew_25d, term_structure, iv_rank, realized_vol, indicatori tecnici, find_by_delta, calculate_spread_payoff, get_dealer_gamma_profile, get_vanna_charm, get_oi_weighted_skew, get_smile_asymmetry, get_atm_vs_wings_vol, get_orderbook_imbalance, place_combo_order.

Bybit

Ticker, orderbook, OHLCV, funding rate, open interest, basis spot/perp, indicatori tecnici, place_batch_order, get_orderbook_imbalance, get_basis_term_structure.

Hyperliquid

Account summary, positions, orderbook, historical, indicators, funding rate, basis spot/perp, place_order, set_stop_loss, set_take_profit.

Alpaca

Account, positions, bars, snapshot, option chain, place_order, amend_order, cancel_order, close_position.

Macro

Treasury yields, FRED indicators, equity futures, asset prices, calendar, get_yield_curve_slope, get_breakeven_inflation, get_cot_tff, get_cot_disaggregated, get_cot_extreme_positioning.

Sentiment

News (CryptoPanic/CoinDesk), social (LunarCrush), funding multi-exchange, OI history, get_funding_arb_spread, get_liquidation_heatmap, get_cointegration_pairs.

Deploy su VPS con Traefik

Sul VPS la rete pubblica (TLS, allowlist IP, rate limit) è gestita da Traefik esterno a questo repository. Il container cerbero-mcp non espone porte all'esterno: si registra alla rete docker di Traefik tramite label aggiunte da un override compose esterno (es. docker-compose.override.yml versionato fuori da questo repo). La policy di sicurezza pubblica (allowlist IP per gli endpoint write) è responsabilità di Traefik.

Esempio label minime per Traefik:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.cerbero.rule=Host(`cerbero-mcp.tielogic.xyz`)"
  - "traefik.http.routers.cerbero.entrypoints=websecure"
  - "traefik.http.routers.cerbero.tls.certresolver=letsencrypt"
  - "traefik.http.services.cerbero.loadbalancer.server.port=9000"

Build & deploy pipeline

Build dell'immagine eseguita sulla macchina di sviluppo:

export GITEA_PAT='<PAT con scope write:package>'
./scripts/build-push.sh

Lo script tagga :2.0.0, :latest e :sha-<short> per rollback puntuali e pubblica al registry Gitea. Sul VPS Watchtower polla :latest e aggiorna il container automaticamente.

Smoke test post-deploy:

PORT=9000 TESTNET_TOKEN="$TESTNET_TOKEN" bash tests/smoke/run.sh

Sviluppo

uv sync
uv run pytest                   # tutta la suite
uv run pytest tests/unit -v     # solo unit
uv run ruff check src/
uv run mypy src/cerbero_mcp

Migrazione da V1 (1.x → 2.0.0)

Per chi è in produzione su V1:

1. Backup secrets/ (V2 non li userà ma servono come fonte di copia).

2. Generare i due nuovi token bearer (vedi sopra).

3. Compilare .env mappando i campi V1 ai campi V2:

   V1 (file JSON)	V2 (variabile .env)
   secrets/deribit.json client_id / client_secret	DERIBIT_CLIENT_ID / DERIBIT_CLIENT_SECRET
   secrets/bybit.json api_key / api_secret	BYBIT_API_KEY / BYBIT_API_SECRET
   secrets/hyperliquid.json wallet_address / private_key	HYPERLIQUID_WALLET_ADDRESS / HYPERLIQUID_PRIVATE_KEY
   secrets/alpaca.json api_key_id / secret_key	ALPACA_API_KEY_ID / ALPACA_SECRET_KEY
   secrets/macro.json fred_api_key / finnhub_api_key	FRED_API_KEY / FINNHUB_API_KEY
   secrets/sentiment.json cryptopanic_key / lunarcrush_key	CRYPTOPANIC_KEY / LUNARCRUSH_KEY

4. Aggiornare i client bot:

   • i path API restano identici (/mcp-{exchange}/tools/{tool})
   • sostituire core.token / observer.token con TESTNET_TOKEN o MAINNET_TOKEN a seconda dell'ambiente desiderato per la chiamata

5. Spegnere V1 (docker compose -f <vecchio compose> down) e avviare V2 (docker compose up -d).

6. Verificare /health e /apidocs.

In caso di necessità è possibile fare rollback pullando i tag immagine V1 (cerbero-mcp-*:1.x); si ricordi però che .env e secrets/ sono formati incompatibili tra V1 e V2 — tenere backup separati.

Architettura

Spec di progettazione completa in docs/superpowers/specs/2026-04-30-V2.0.0-unified-image-token-routing-design.md.

Riepilogo:

Bot → Authorization: Bearer <TESTNET|MAINNET>_TOKEN
        ↓
   FastAPI middleware auth → request.state.environment ∈ {testnet, mainnet}
        ↓
   Router /mcp-{exchange}/tools/{tool}
        ↓
   ClientRegistry.get(exchange, env) → client cached lazy (HTTP/WS pool riusato)
        ↓
   Tool function (logica pura) → exchange API

Licenza

Privato.