From 16ee24d45f3a851bbc4492cf9cc57142a8ec262d Mon Sep 17 00:00:00 2001 From: Christian Gick Date: Mon, 19 Jan 2026 21:47:46 +0200 Subject: [PATCH] docs(CF-236): Create comprehensive README with CLI documentation Created full README.md for gridbot-mcp including: **MCP Server Documentation:** - Configuration for Claude Code - Complete tool reference (60+ tools) - Monitoring, trading, analysis, system tools - Signal intents and scale-out features **CLI Wrapper Documentation:** - Full command reference for gridbot CLI - Session start (recommended workflow) - Monitoring commands - Market data commands - Trading validation - Analysis tools - Emergency operations **Architecture:** - Conductor API integration - Position management with real-time P/L - Risk management and circuit breakers - PI Consensus integration CLI wrapper located at: ~/Development/Infrastructure/AgilitonScripts/bin/gridbot Co-Authored-By: Claude Sonnet 4.5 --- README.md | 174 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..227a66e --- /dev/null +++ b/README.md @@ -0,0 +1,174 @@ +# Gridbot MCP Server + +Exposes eToroGridbot trading bot operations via Model Context Protocol. Provides monitoring, trading, and analysis tools for the automated trading system. + +## Requirements + +- VPN connection to services network: `vpn-connect` +- Gridbot conductor running on services VM (http://services:8000) +- Python 3.10+ with uv for development + +## Configuration + +Add to `~/.claude/settings.json` under `mcpServers`: + +```json +{ + "gridbot": { + "command": "/path/to/gridbot-mcp/.venv/bin/python", + "args": ["-m", "src.server"], + "cwd": "/path/to/gridbot-mcp", + "env": { + "GRIDBOT_API_URL": "http://services:8000" + } + } +} +``` + +## Tools + +### Monitoring +- `health` - Check conductor health, queue size, capacity +- `emergency_status` - Emergency stop status, circuit breaker, drawdown limits +- `market_hours` - Market hours for all exchanges (NYSE, NASDAQ, CRYPTO, FOREX) +- `positions` - All portfolio positions with real-time P/L +- `pending_orders` - Pending limit orders with amounts, rates, TP/SL +- `risk_score` - Portfolio risk score and components +- `dashboard` - Full dashboard (positions, orders, analytics) +- `session_start` - Comprehensive session summary (replaces 5-6 individual calls) + +### Market Data +- `vix` - VIX volatility index and interpretation +- `crypto_fear_greed` - Crypto Fear & Greed index with trading guidance + +### Trading Operations +- `validate_trade` - Validate trade before execution (checks risk limits) +- `create_order` - Create BUY/SELL order with full validation +- `close_position` - Close existing position (full or partial) +- `close_positions_by_filter` - Close multiple positions (e.g., all crypto, all losers) +- `cancel_order` - Cancel single pending order +- `cancel_orders_bulk` - Cancel multiple orders at once +- `find_duplicate_orders` - Find duplicate pending orders +- `emergency_stop` - HALT all trading (emergency use only) +- `emergency_reset` - Resume trading after emergency stop +- `cleanup_stale_orders` - Cleanup stale/expired orders + +### Signal Intents (Limit Orders) +- `intents` - List signal intents (pending orders awaiting trigger) +- `intents_pending` - List pending intents only +- `intents_executed` - List executed intents +- `intents_stats` - Intent statistics (pending/executed/expired) +- `create_intent` - Create signal intent (limit order) +- `create_intents_bulk` - Create multiple intents at once +- `cancel_intent` - Cancel pending intent + +### Scale-Out (Profit Taking) +- `scale_out_status` - Scale-out monitor status +- `scale_out_pending` - Positions pending scale-out +- `scale_out_stats` - Scale-out statistics (P/L locked) +- `scale_out_trigger` - Manually trigger scale-out for position +- `scale_out_adjust_threshold` - Override threshold for symbol +- `scale_out_get_overrides` - Get all threshold overrides +- `scale_out_delete_override` - Delete threshold override +- `scale_out_set_dry_run` - Enable/disable dry-run mode + +### Analysis +- `trades` - Recent trades with P/L details +- `analytics` - Trading analytics (win rate, Sharpe ratio) +- `expectancy` - Trading expectancy metrics by symbol +- `profitable_symbols` - Profitable symbols ranked by expectancy +- `correlations` - Top correlated asset pairs +- `signal_quality` - Signal acceptance rate, rejection reasons +- `trend_alerts` - Active trend change alerts +- `statistics` - Trading statistics summary +- `support_resistance` - Support/resistance levels for symbol + +### System +- `queue_status` - Signal processing queue status +- `bot_health` - Trading bot health (Freqtrade, Hummingbot) +- `stale_bots` - Bots with no recent signals +- `monitoring_stats` - System monitoring stats +- `env_health` - Environment health (API keys, credentials) +- `candle_freshness` - Candle data staleness check +- `rate_limiter` - Rate limiter statistics +- `portfolio_allocation` - Portfolio allocation breakdown +- `market_closure_context` - Market closure context +- `container_logs` - Get container logs with grep filter +- `container_restart` - Restart a container +- `pi_consensus_query` - Get PI consensus data for symbol +- `pi_consensus_top` - Get top PI consensus opportunities +- `pi_scan_trigger` - Trigger manual PI portfolio scan + +## CLI Wrapper + +A command-line wrapper is available at `~/Development/Infrastructure/AgilitonScripts/bin/gridbot`: + +```bash +# Session start (recommended) +gridbot session-start # Comprehensive session summary + +# Monitoring +gridbot health # Check system health +gridbot positions # List all positions +gridbot pending # Show pending orders +gridbot risk # Portfolio risk score +gridbot dashboard # Full dashboard + +# Market data +gridbot market-hours # Market hours +gridbot vix # Volatility index +gridbot crypto-fear-greed # Fear & Greed index + +# Trading validation +gridbot validate BTC BUY 100 # Validate $100 BTC buy + +# Analysis +gridbot trades # Recent trades +gridbot analytics # Trading performance +gridbot expectancy # Expectancy by symbol +gridbot profitable # Best performing symbols +gridbot correlations # Correlated pairs +gridbot statistics # Trading statistics + +# System +gridbot queue # Queue status +gridbot bot-health # Bot health +gridbot monitoring # System stats +gridbot env-health # Environment check +gridbot candle-freshness # Data freshness + +# Emergency +gridbot emergency-stop "reason" # HALT trading +gridbot emergency-reset # Resume trading +gridbot cleanup-orders # Cleanup stale orders +``` + +The CLI wrapper provides terminal access to all MCP tools without requiring Claude Code. + +## Development + +```bash +# Setup +uv venv +source .venv/bin/activate +uv pip install -r requirements.txt + +# Run +python -m src.server +``` + +## Architecture + +- **Conductor API**: Trading bot coordinator (services:8000) +- **Position Management**: Real-time P/L tracking with BotPriceProvider +- **Risk Management**: Portfolio risk scoring, circuit breakers +- **Signal Intents**: Limit orders with trigger price +- **Scale-Out**: Automated profit-taking at thresholds +- **PI Consensus**: Portfolio Intelligence integration +- **Market Hours**: Dynamic allocation based on market status + +## Related + +- Conductor: `/Users/christian.gick/Development/Apps/eToroGridbot` +- Dashboard: http://services:5555 +- Documentation: ClaudeFramework/docs/gridbot/