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 <noreply@anthropic.com>
2026-01-19 21:47:46 +02:00
parent c9a1775bb5
commit 16ee24d45f
1 changed files with 174 additions and 0 deletions
--- a/README.md
+++ 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/