Cerbero-mcp/README.md

Cerbero_mcp

Server MCP riusabili (exchange + market data) per la suite Cerbero. Spinta da Cerbero/ (commit pre-split-2026-04-27) come parte dello split documentato in docs/superpowers/specs/2026-04-27-split-mcp-core-design.md (nel repo storico).

Servizi

• mcp-alpaca, mcp-bybit, mcp-deribit, mcp-hyperliquid — exchange con place_order, environment_info, leverage cap server-side
• mcp-deribit e mcp-bybit espongono inoltre place_combo_order:
  • Deribit: private/create_combo + ordine sul combo → 1 sola crociata di spread invece di N (slippage atteso ridotto su strutture liquide).
  • Bybit: place_batch_order su category=option → multi-leg atomico in un solo round-trip API (no sconto fee, solo atomicità + latenza).
• mcp-macro, mcp-sentiment — read-only market data

Indicatori quantitativi disponibili

Common (mcp_common.indicators + options + microstructure + stats)

• Tecnici: sma, rsi, macd, atr, adx
• Volatilità: vol_cone (RV multi-window con percentili), garch11_forecast
• Statistici: hurst_exponent, half_life_mean_reversion, autocorrelation, cointegration_test (Engle-Granger)
• Risk: rolling_sharpe (Sharpe + Sortino), var_cvar (historical VaR/ES)
• Microstructure: orderbook_imbalance (ratio + microprice + slope)
• Options: oi_weighted_skew, smile_asymmetry, atm_vs_wings_vol, dealer_gamma_profile, vanna_charm_aggregate

Deribit (esposti come tool MCP)

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

Bybit

Ticker, orderbook, OHLCV, funding rate (current+history), open interest, basis spot/perp, indicatori tecnici. Nuovi: get_orderbook_imbalance, get_basis_term_structure.

Macro

Treasury yields, FRED indicators, equity futures, asset prices, calendar. Nuovi: get_yield_curve_slope (slope 2y10y/5y30y + butterfly + regime), get_breakeven_inflation (T5YIE/T10YIE/T5YIFR), get_cot_tff (TFF report CFTC equity/financial: ES/NQ/RTY/ZN/ZB/6E/6J/DX), get_cot_disaggregated (Disaggregated report CFTC commodities: CL/GC/SI/HG/ZW/ZC/ZS), get_cot_extreme_positioning (scanner percentile ≤5/≥95 su watchlist).

Sentiment

News (CryptoPanic/CoinDesk), social (LunarCrush), funding multi-exchange, OI history. Nuovi: get_funding_arb_spread (opportunità arb compatte), get_liquidation_heatmap (heuristic da OI delta + funding extreme), get_cointegration_pairs (Engle-Granger su coppie crypto).

Build & deploy pipeline

Niente CI/CD su Gitea: la build delle 8 image è responsabilità della macchina di sviluppo, fatta da scripts/build-push.sh. Il flusso è:

1. Quality gate locale (sul laptop, prima di pushare):
   • uv run ruff check services/
   • uv run mypy services/common/src/mcp_common
   • uv run pytest services/
   • docker compose -f docker-compose.prod.yml config -q
2. Build & push (sul laptop):

   export GITEA_PAT='<PAT_write:package>'
   ./scripts/build-push.sh                 # tutte le 8 image
   ./scripts/build-push.sh base mcp-bybit  # solo specifiche
   

   Tagga :latest + :sha-<short_HEAD> per rollback puntuali. Cache buildx via registry stesso (run successivi 5-10× più veloci).
3. Auto-rollover su VPS: Watchtower polla il registry ogni 5 min e aggiorna i container quando il digest del tag :latest cambia.

Vedi DEPLOYMENT.md per build & push, deploy VPS no-clone (scripts/deploy-noclone.sh), smoke test, rollback.

Avvio locale (dev)

docker compose up -d
bash tests/smoke/run.sh

Configurazione

Vedi secrets/*.json e variabili *_TESTNET / ALPACA_PAPER in docker-compose.yml per override ambiente.

Deploy su VPS pubblica (cerbero-mcp.tielogic.xyz)

Vedi DEPLOYMENT.md per il runbook completo end-to-end.

Il gateway Caddy è configurato per:

• TLS automatico via Let's Encrypt (richiede DNS A/AAAA che punti al VPS e porte 80+443 raggiungibili).
• HSTS preload, header di sicurezza (X-Content-Type-Options, X-Frame-Options, Referrer-Policy).
• Rate limit per IP (60 req/min su read, 10 req/min su write) tramite plugin mholt/caddy-ratelimit.
• Allowlist IP sui write endpoint (place_*, cancel_*, set_*, close_*, transfer_*, amend_*, switch_*): IP non presenti in WRITE_ALLOWLIST ricevono 403 forbidden.

Variabili d'ambiente per il deploy:

# .env (su VPS)
ACME_EMAIL=adrianodalpastro@tielogic.com
GATEWAY_HTTP_PORT=80
GATEWAY_HTTPS_PORT=443

# Allowlist write endpoint (CIDR space-separated). Default copre:
#  - loopback IPv4/IPv6 (bot sull'host VPS chiama http://localhost)
#  - Docker bridge 172.16.0.0/12 (bot in container nella stessa compose network)
# Aggiungi gli IP pubblici dei tuoi bot esterni se li hai.
WRITE_ALLOWLIST="127.0.0.1/32 ::1/128 172.16.0.0/12 1.2.3.4/32"

Tre scenari per il trading bot:

1. Bot container nella stessa compose network → chiama http://gateway:80 internamente. Source IP = Docker bridge → coperto dalla default.
2. Bot processo sull'host VPS → chiama http://localhost. Source IP = 127.0.0.1 → coperto dalla default.
3. Bot esterno (laptop, altro server) → chiama https://cerbero-mcp.tielogic.xyz con TLS. Devi aggiungere l'IP pubblico del bot in WRITE_ALLOWLIST.

Senza configurare WRITE_ALLOWLIST la default è loopback + Docker bridge: nessun IP pubblico esterno può triggerare ordini.

Sull'host VPS i secret devono avere permessi restrittivi:

chmod 600 secrets/*.json secrets/*.token

Risoluzione environment (testnet/mainnet)

Ogni servizio exchange usa mcp_common.environment.resolve_environment() che applica la precedenza:

1. env var di override (DERIBIT_TESTNET, BYBIT_TESTNET, HYPERLIQUID_TESTNET, ALPACA_PAPER)
2. flag nel secret JSON (testnet o paper per alpaca)
3. default testnet

Gli URL canonici live/testnet sono passati come kwargs default_base_url_live / default_base_url_testnet direttamente al resolver — non serve duplicarli nel secret JSON, ma se presenti prevalgono sui default del codice.