AdrianoDev
a13e3fe045
Common (mcp_common): - indicators.py: vol_cone, hurst_exponent, half_life_mean_reversion, garch11_forecast, autocorrelation, rolling_sharpe, var_cvar - options.py (nuovo): oi_weighted_skew, smile_asymmetry, atm_vs_wings_vol, dealer_gamma_profile, vanna_charm_aggregate - microstructure.py (nuovo): orderbook_imbalance (ratio + microprice + slope) - stats.py (nuovo): cointegration_test Engle-Granger + ADF helper Deribit (+6 tool MCP): - get_dealer_gamma_profile (net dealer gamma + flip level) - get_vanna_charm (vanna/charm aggregati pesati OI) - get_oi_weighted_skew, get_smile_asymmetry, get_atm_vs_wings_vol - get_orderbook_imbalance Bybit (+2 tool MCP): - get_orderbook_imbalance, get_basis_term_structure (futures dated curve) Macro (+2 tool MCP): - get_yield_curve_slope (2y10y/5y30y + butterfly + regime) - get_breakeven_inflation (FRED T5YIE/T10YIE/T5YIFR) Sentiment (+3 tool MCP): - get_funding_arb_spread (opportunità arb compatte annualizzate) - get_liquidation_heatmap (heuristic da OI delta + funding extreme, no feed paid Coinglass) - get_cointegration_pairs (Engle-Granger su coppie crypto Binance hourly) Tutto in TDD pure-Python (no numpy/scipy in mcp_common). README aggiornato con elenco completo. 442 test totali verdi. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
125 lines
4.9 KiB
Markdown
125 lines
4.9 KiB
Markdown
# 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).
|
|
|
|
### 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).
|
|
|
|
## Avvio locale
|
|
|
|
```bash
|
|
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`)
|
|
|
|
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:
|
|
|
|
```bash
|
|
# .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:
|
|
|
|
```bash
|
|
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.
|