fix: update server.json with real SHA256 and shorten description

- Description: 96 chars (was >100) - SHA256: calculated from local MCP package build
2026-04-20 02:54:28 +07:00
parent a1434914e9
commit 63c0470c6b
18 changed files with 3891 additions and 2 deletions
@@ -0,0 +1,247 @@
+# MT5-Quant
+
+**MCP server for MT5 strategy development on macOS/Linux.** 85 tools to compile, backtest, analyze, optimize, debug crashes, and manage MQL5 Expert Advisors — no Windows required.
+
+```
+You: "Backtest MyEA Jan-Mar, what caused the February drawdown?"
+
+Claude: [compile → clean → backtest → analyze 1,847 deals]
+        → Feb 14: BUY grid at L6, locking lot 1.75× base
+        → Cutloss fired 17 points later
+        → Recommendation: cap locking multiplier to ≤1.2×
+```
+
+## Why MT5-Quant
+
+| | MT5-Quant | Other MT5 MCPs | QuantConnect |
+|---|---|---|---|
+| Backtest pipeline | ✅ Full | ❌ | Cloud only |
+| Deal-level analytics | ✅ 15+ dims | ❌ | ❌ |
+| MQL5 compilation | ✅ | ❌ | ❌ |
+| macOS/Linux native | ✅ | Windows only | Cloud |
+| Optimization | ✅ Background | ❌ | ✅ Paid |
+| Crash debugging | ✅ Wine/MT5 diagnostics | ❌ | ❌ |
+
+## Quick Install
+
+### 1. Download & Setup
+
+```bash
+curl -L -o mt5.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-macos-arm64.tar.gz
+tar -xzf mt5.tar.gz
+bash scripts/setup.sh
+```
+
+### 2. Register MCP Server
+
+| Platform | Command / Config | Docs |
+|----------|------------------|------|
+| **Claude Code** | `claude mcp add mt5-quant -- $(pwd)/mt5-quant` | [Setup →](docs/QUICKSTART.md) |
+| **Windsurf** | Edit `~/.codeium/windsurf/mcp_config.json` | [WINDSURF.md →](docs/WINDSURF.md) |
+| **Cursor** | Edit `~/.cursor/mcp.json` or use Settings → MCP | [CURSOR.md →](docs/CURSOR.md) |
+| **VS Code** | Edit `.vscode/mcp.json` or run `MCP: Add Server` | [VSCODE.md →](docs/VSCODE.md) |
+| **Antigravity** | Agent Panel → ... → MCP Servers → Edit configuration | [ANTIGRAVITY.md →](docs/ANTIGRAVITY.md) |
+
+> **Note:** Use absolute paths like `/Users/name/mt5-quant/mt5-quant` or `$(pwd)/mt5-quant`, not relative paths like `./mt5-quant`.
+
+## Quick Start
+
+```
+Run a backtest on MyEA from 2025.01.01 to 2025.03.31
+```
+
+The AI runs the full pipeline: compile → clean cache → backtest → extract → analyze.
+
+## Documentation
+
+| Doc | Purpose |
+|-----|---------|
+| [QUICKSTART.md](docs/QUICKSTART.md) | Complete setup for macOS/Linux |
+| [WINDSURF.md](docs/WINDSURF.md) | Windsurf IDE setup |
+| [CURSOR.md](docs/CURSOR.md) | Cursor IDE setup |
+| [VSCODE.md](docs/VSCODE.md) | VS Code setup |
+| [ANTIGRAVITY.md](docs/ANTIGRAVITY.md) | Antigravity IDE setup |
+| [CONFIG.md](docs/CONFIG.md) | Configuration reference |
+| [TOOLS.md](docs/MCP_TOOLS.md) | All 75 tools documented |
+| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Design and internals |
+| [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common issues |
+| [REMOTE_AGENTS.md](docs/REMOTE_AGENTS.md) | Linux optimization agents |
+
+## MCP Tools (75)
+
+### Core workflow
+
+| Tool | Description |
+|------|-------------|
+| `run_backtest` | Full pipeline: compile → clean → backtest → extract → analyze |
+| `run_optimization` | Genetic optimization (background, returns immediately) |
+| `get_optimization_results` | Parse optimization results after MT5 finishes |
+| `analyze_report` | Read `analysis.json` from any report directory |
+| `compare_baseline` | Compare report vs baseline, return winner/loser verdict |
+| `compile_ea` | Compile MQL5 EA via MetaEditor |
+| `list_experts` | List all EAs in MQL5/Experts directory |
+| `list_indicators` | List all indicators in MQL5/Indicators directory |
+| `list_scripts` | List all scripts in MQL5/Scripts directory |
+| `healthcheck` | Quick server health check |
+
+### Granular Analytics (individual analysis)
+
+| Tool | Description |
+|------|-------------|
+| `analyze_monthly_pnl` | Monthly P/L breakdown only |
+| `analyze_drawdown_events` | Drawdown events and causes only |
+| `analyze_top_losses` | Worst losing deals only |
+| `analyze_loss_sequences` | Consecutive loss patterns only |
+| `analyze_position_pairs` | Position hold time and P/L pairs |
+| `analyze_direction_bias` | Buy vs Sell performance |
+| `analyze_streaks` | Win/loss streak analysis |
+| `analyze_concurrent_peak` | Peak simultaneous positions |
+
+Use these for targeted analysis, or `analyze_report` to run all at once.
+
+### Deal-Level Analytics (New)
+
+| Tool | Description |
+|------|-------------|
+| `list_deals` | List individual deals with filters (type, profit range, volume, dates) |
+| `search_deals_by_comment` | Full-text search in deal comments (e.g., "Layer #3") |
+| `search_deals_by_magic` | Filter deals by EA magic number |
+| `analyze_profit_distribution` | Profit histogram: small/medium/large wins and losses |
+| `analyze_time_performance` | Performance by hour of day and day of week |
+| `analyze_hold_time_distribution` | Hold time buckets + correlation with profit |
+| `analyze_layer_performance` | Grid/martingale layer analysis from comments |
+| `analyze_volume_vs_profit` | Volume correlation + performance by lot size |
+| `analyze_costs` | Commission and swap impact on profitability |
+| `analyze_efficiency` | Profit per hour/day, annualized return, trade frequency |
+
+### Monitoring
+
+| Tool | Description |
+|------|-------------|
+| `verify_setup` | Check Wine/MT5 paths, Wine version, and EA/set file counts |
+| `get_backtest_status` | Check live progress of a running backtest pipeline |
+| `get_optimization_status` | Check live state of a background optimization job |
+| `list_jobs` | All optimization jobs with compact status in one call |
+
+### Reports & logs
+
+| Tool | Description |
+|------|-------------|
+| `list_reports` | Compact table of all runs with key metrics — no full analysis needed |
+| `get_latest_report` | Get most recent report with optional equity chart |
+| `search_reports` | Find reports by EA, symbol, date range, or profit criteria |
+| `get_report_by_id` | Get specific report by ID with equity chart |
+| `get_reports_summary` | Aggregate stats: counts, averages, pass rates |
+| `get_best_reports` | Top N reports sorted by any metric (profit factor, drawdown, etc.) |
+| `search_reports_by_tags` | Find reports by tags |
+| `search_reports_by_date_range` | Query by backtest date range |
+| `search_reports_by_notes` | Full-text search in report notes |
+| `get_reports_by_set_file` | Find all reports using a specific .set file |
+| `get_comparable_reports` | Find comparable reports (same EA/symbol/timeframe) |
+| `tail_log` | Read last N lines of any log; `filter=errors` to see only failures |
+| `prune_reports` | Delete old report directories, keep last N (skips `_opt` dirs) |
+
+### History & baseline
+
+| Tool | Description |
+|------|-------------|
+| `archive_report` | Convert one report dir → compact JSON entry in `backtest_history.json`, optionally delete source |
+| `archive_all_reports` | Bulk-archive all report dirs then optionally delete them; keeps N newest safe |
+| `get_history` | Query history with filters (EA, symbol, verdict, profit, DD) and sort options |
+| `annotate_history` | Attach verdict / notes / tags to any history entry |
+| `promote_to_baseline` | Write a history entry or report to `baseline.json` for compare_baseline |
+
+### Cache management
+
+| Tool | Description |
+|------|-------------|
+| `cache_status` | MT5 tester cache size breakdown by symbol — check before cleaning |
+| `clean_cache` | Delete tester cache files; supports per-symbol and `dry_run` |
+
+### Pre-flight & Validation
+
+| Tool | Description |
+|------|-------------|
+| `get_active_account` | Get current MT5 account session (login, server, available symbols) |
+| `check_symbol_data_status` | Validate symbol has sufficient history data for date range |
+| `check_mt5_status` | Check if MT5 terminal is installed and ready |
+| `validate_ea_syntax` | Pre-compile syntax check without running full compilation |
+
+### Debugging & Diagnostics (New)
+
+| Tool | Description |
+|------|-------------|
+| `diagnose_wine` | Check Wine installation, version, and prefix health |
+| `get_mt5_logs` | Get MT5 terminal, tester, or MetaEditor logs with filtering |
+| `search_mt5_errors` | Search logs for error patterns (crash, exception, access violation) |
+| `check_mt5_process` | Check if MT5 processes are running, get PID, CPU, memory usage |
+| `kill_mt5_process` | Kill stuck MT5 processes (force=true for wineserver) |
+| `check_system_resources` | Check disk space, memory, CPU availability |
+| `validate_mt5_config` | Validate terminal.ini and tester configuration files |
+| `get_wine_prefix_info` | Get Wine prefix details: Windows version, installed programs, registry |
+| `get_backtest_crash_info` | Investigate backtest failures: incomplete markers, missing deals.csv, errors |
+
+### Project Management
+
+| Tool | Description |
+|------|-------------|
+| `init_project` | Scaffold new MQL5 project with templates (scalper/swing/grid/basic) |
+| `create_set_template` | Generate .set parameter file from EA input variables |
+| `export_report` | Export backtest report to CSV, JSON, or Markdown |
+
+### History & Comparison
+
+| Tool | Description |
+|------|-------------|
+| `get_backtest_history` | List all backtests for EA/symbol with summary metrics |
+| `compare_backtests` | Compare 2+ backtest results side-by-side with analysis |
+
+### .set file — read / write
+
+| Tool | Description |
+|------|-------------|
+| `list_set_files` | All .set files in tester profiles dir with sweep stats and combination counts |
+| `read_set_file` | Parse UTF-16LE `.set` file → structured JSON params |
+| `write_set_file` | Write full params dict → UTF-16LE `.set` with `chmod 444` |
+| `patch_set_file` | Update specific params in-place, return diff — replaces read→edit→write |
+| `clone_set_file` | Copy `.set` to new path with optional overrides in one call |
+
+### .set file — analysis & generation
+
+| Tool | Description |
+|------|-------------|
+| `describe_sweep` | Swept params, value counts, and total optimization combinations |
+| `diff_set_files` | Side-by-side diff of two `.set` files — only changed params returned |
+| `set_from_optimization` | Generate a clean backtest `.set` from `get_optimization_results` params; optionally narrow sweep |
+
+### Search & Discovery
+
+| Tool | Description |
+|------|-------------|
+| `search_experts` | Search EAs by name pattern across all directories |
+| `search_indicators` | Search indicators by name pattern |
+| `search_scripts` | Search scripts by name pattern |
+| `copy_indicator_to_project` | Copy indicator to project directory |
+| `copy_script_to_project` | Copy script to project directory |
+
+Full schema: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md)
+
+## Troubleshooting
+
+Run `verify_setup` from Claude first — it checks all paths and returns actionable hints.
+
+For crashes or unexplained failures during backtest/compile/optimization:
+- `diagnose_wine` — Check Wine installation and prefix health
+- `search_mt5_errors` — Find crash causes in logs
+- `check_mt5_process` + `kill_mt5_process` — Detect and kill stuck processes
+- `get_backtest_crash_info` — Investigate failed backtest reports
+
+**[Full Troubleshooting Guide →](docs/TROUBLESHOOTING.md)**
+
+---
+
+## License
+
+MIT
+
+---
@@ -0,0 +1,27 @@
+; MT5 optimization .set file — example
+; Format: param=current_value||start||step||stop||Y   (Y=sweep this param)
+;         param=current_value||N                      (N=fixed, no sweep)
+;
+; MT5-Quant handles encoding automatically:
+;   - Converts to UTF-16LE (MT5 strips ||Y flags from UTF-8 files)
+;   - Sets read-only flag after writing
+;   - Resets OptMode in terminal.ini before launch
+;
+; Copy to your project dir and point --set to it.
+
+; ── Entry parameters (sweep) ─────────────────────────────────────────────────
+Min_Entry_Confidence=0.610||0.580||0.010||0.650||Y
+Max_Entry_Spread=30||10||5||50||Y
+
+; ── Take-profit and stop-loss (sweep) ────────────────────────────────────────
+TP_Pips=400||300||50||600||Y
+SL_Pips=800||600||100||1200||Y
+
+; ── Grid / martingale settings (fixed) ───────────────────────────────────────
+MaxLayers=6||N
+LotMultiplier=1.5||N
+GridStep_Pips=150||N
+
+; ── Risk management (fixed) ──────────────────────────────────────────────────
+Max_DD_Percent=15.0||N
+CutLoss_Percent=25.0||N
@@ -0,0 +1,45 @@
+# mt5-quant configuration (flat key format — no YAML nesting)
+# Copy this file to config/mt5-quant.yaml and fill in your paths.
+
+# ── MT5 / Wine paths ──────────────────────────────────────────────────────────
+
+# macOS (CrossOver / MetaTrader 5.app)
+wine_executable: "/Applications/MetaTrader 5.app/Contents/SharedSupport/wine/bin/wine64"
+terminal_dir: "$HOME/Library/Application Support/net.metaquotes.wine.metatrader5/drive_c/Program Files/MetaTrader 5"
+experts_dir: "$HOME/Library/Application Support/net.metaquotes.wine.metatrader5/drive_c/Program Files/MetaTrader 5/MQL5/Experts"
+tester_profiles_dir: "$HOME/Library/Application Support/net.metaquotes.wine.metatrader5/drive_c/Program Files/MetaTrader 5/MQL5/Profiles/Tester"
+tester_cache_dir: "$HOME/Library/Application Support/net.metaquotes.wine.metatrader5/drive_c/Program Files/MetaTrader 5/Tester"
+
+# Linux (Wine)
+# wine_executable: "/usr/bin/wine64"
+# terminal_dir: "$HOME/.wine/drive_c/Program Files/MetaTrader 5"
+# experts_dir: "$HOME/.wine/drive_c/Program Files/MetaTrader 5/MQL5/Experts"
+# tester_profiles_dir: "$HOME/.wine/drive_c/Program Files/MetaTrader 5/MQL5/Profiles/Tester"
+# tester_cache_dir: "$HOME/.wine/drive_c/Program Files/MetaTrader 5/Tester"
+
+# ── Display ───────────────────────────────────────────────────────────────────
+# auto: GUI on macOS CrossOver, Xvfb on Linux without $DISPLAY
+# gui: always use display (requires active session)
+# headless: always use Xvfb (requires xvfb-run)
+display_mode: auto
+
+# ── Project ───────────────────────────────────────────────────────────────────
+# Root directory of your EA project (where .mq5 and .set files live)
+project_dir: "/path/to/your/ea/project"
+
+# ── Backtest defaults ─────────────────────────────────────────────────────────
+# These are fallbacks when not passed as MCP tool arguments
+backtest_symbol: "EURUSD"
+backtest_deposit: 10000
+backtest_currency: USD
+backtest_leverage: 100
+backtest_model: 0
+backtest_timeframe: H1
+backtest_timeout: 900
+
+# ── Optimization ──────────────────────────────────────────────────────────────
+opt_log_dir: /tmp
+opt_min_agents: 1
+
+# ── Reports output ────────────────────────────────────────────────────────────
+reports_dir: "/path/to/your/ea/project/reports"
@@ -0,0 +1,45 @@
+# mt5-quant configuration — generated by scripts/setup.sh
+# Re-run scripts/setup.sh to regenerate, or edit manually.
+
+mt5:
+  # Path to Wine / CrossOver wine64 binary
+  wine_executable: "/Applications/MetaTrader 5.app/Contents/SharedSupport/wine/bin/wine64"
+
+  # MT5 installation directory (inside the Wine prefix)
+  terminal_dir: "/Users/masdevid/Library/Application Support/net.metaquotes.wine.metatrader5/drive_c/Program Files/MetaTrader 5"
+
+  # Where MT5 looks for Expert Advisor binaries (.ex5)
+  experts_dir: "/Users/masdevid/Library/Application Support/net.metaquotes.wine.metatrader5/drive_c/Program Files/MetaTrader 5/MQL5/Experts"
+
+  # Where MT5 reads/writes .set files during backtests
+  tester_profiles_dir: "/Users/masdevid/Library/Application Support/net.metaquotes.wine.metatrader5/drive_c/Program Files/MetaTrader 5/MQL5/Profiles/Tester"
+
+  # MT5 tester cache directory (cleared before each run)
+  tester_cache_dir: "/Users/masdevid/Library/Application Support/net.metaquotes.wine.metatrader5/drive_c/Program Files/MetaTrader 5/Tester"
+
+display:
+  # headless: true  → Xvfb (Linux only)
+  # headless: false → GUI visible
+  # headless: auto  → macOS=GUI, Linux with $DISPLAY=GUI, Linux without=Xvfb
+  mode: auto
+
+  # Virtual display for Xvfb (Linux headless only)
+  xvfb_display: ":99"
+  xvfb_screen: "1024x768x16"
+
+backtest:
+  symbol: "XAUUSD"
+  deposit: 10000
+  currency: "USD"
+  leverage: 500
+  model: 0       # 0=every tick (required for martingale/grid EAs)
+  timeframe: "M5"
+  timeout: 900   # seconds per backtest run
+
+optimization:
+  log_dir: "/tmp"
+  min_agents: 1
+
+reports:
+  output_dir: "./reports"
+  keep_last: 20
@@ -0,0 +1,145 @@
+# Antigravity MCP Integration Setup
+
+## Quick Setup
+
+### Option 1: Download Prebuilt Binary (Recommended)
+
+```bash
+# macOS (Apple Silicon)
+curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-macos-arm64.tar.gz
+tar -xzf mt5-quant.tar.gz
+
+# Linux (x64)
+curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-linux-x64.tar.gz
+tar -xzf mt5-quant.tar.gz
+```
+
+### Option 2: Build from Source
+
+```bash
+cargo build --release
+```
+
+## Configure Antigravity
+
+### Step 1: Open MCP Manager
+
+1. Launch Antigravity
+2. Look at the **right-side Agent Panel**
+3. Click the **"..."** (More Options) menu at the top
+4. Select **MCP Servers**
+
+### Step 2: Access Configuration
+
+1. Click **Manage MCP Servers**
+2. Click **View raw config** or **Edit configuration**
+3. This opens `mcp_config.json`
+
+### Step 3: Add mt5-quant Configuration
+
+Add to `mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mt5-quant": {
+      "command": "/absolute/path/to/mt5-quant"
+    }
+  }
+}
+```
+
+### Step 4: Reload and Verify
+
+1. Save the file
+2. **Restart Antigravity** (or reload the window)
+3. Open the Agent chat and type: `What tools do you have access to?`
+4. The agent should list MT5 tools like `verify_setup`, `run_backtest`, etc.
+
+## Full Example Configuration
+
+```json
+{
+  "mcpServers": {
+    "mt5-quant": {
+      "command": "/Users/name/mt5-quant/target/release/mt5-quant"
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+Antigravity supports `${VAR_NAME}` syntax for environment variable substitution:
+
+```json
+{
+  "mcpServers": {
+    "mt5-quant": {
+      "command": "/Users/name/mt5-quant/target/release/mt5-quant",
+      "env": {
+        "CUSTOM_VAR": "${env:MY_VAR}"
+      }
+    }
+  }
+}
+```
+
+This keeps secrets out of the config file.
+
+## Verify Setup
+
+In Antigravity chat, type:
+
+```
+Run verify_setup
+```
+
+Expected output:
+```
+Wine:    /Applications/MetaTrader 5.app/.../wine64
+MT5 dir: ~/Library/Application Support/.../MetaTrader 5
+Display: gui
+Arch:    arch -x86_64
+```
+
+## Troubleshooting
+
+### "Connection Refused" or "Tool not found"
+
+1. Double-check the server path in `mcp_config.json`
+2. Ensure the binary has execute permissions: `chmod +x /path/to/mt5-quant`
+3. Try completely restarting Antigravity
+4. Check the server is listed in MCP manager
+
+### "Stdio Error" or JSON Parsing Error
+
+1. Verify the JSON syntax in `mcp_config.json`
+2. Use a JSON validator if needed
+3. Ensure no trailing commas
+
+### Agent Hallucinating Tool Parameters
+
+If the agent makes up incorrect parameters:
+1. Check the tool is actually available: "List your available tools"
+2. Restart the agent session
+3. Be explicit in your requests
+
+## Configuration Location
+
+| Platform | Path |
+|----------|------|
+| All | Via UI: Agent Panel → ... → MCP Servers → Manage → Edit configuration |
+
+## Resources
+
+- [Antigravity Documentation](https://docs.antigravity.dev/)
+- [MCP Server Reference](https://github.com/modelcontextprotocol/servers)
+- [MT5-Quant Tools Reference](./MCP_TOOLS.md)
@@ -0,0 +1,458 @@
+# Architecture Deep Dive
+
+## Design Philosophy
+
+**Deal-level over aggregate.** MT5's built-in HTML report gives you: profit, profit factor, max DD%, trade count. That's it. You cannot tell from those numbers whether a drawdown was caused by overleveraged locking, a bad entry during a news spike, or a grid that reached L8 in a trending market.
+
+MT5-Quant extracts every individual deal — entry price, exit price, P/L, comment string — and reconstructs what was happening when each loss event occurred. The `analysis.json` artifact is the result: AI-readable, stable schema, diffable between runs.
+
+**Pipeline idempotency.** MT5 caches aggressively. Cached `.ex5` binaries, cached `.set` files, stale `terminal.ini` flags. The pipeline exists specifically to invalidate all of these before every run. A backtest result that came from a cached EA binary is wrong in a way that's impossible to detect without the cache clear step.
+
+**Background isolation for optimization.** Genetic optimizations run 2-6 hours. Running them inside a parent process that can be killed (Claude task runner, SSH session, terminal) corrupts the MT5 optimization state. The only correct pattern is `nohup + disown` — fully detached from all parent process trees.
+
+---
+
+## Component Map
+
+```
+MT5-Quant/
+├── src/
+│   ├── main.rs                 # MCP server entry (stdio transport)
+│   ├── mcp_server.rs           # MCP protocol handling
+│   ├── models/                 # Data structures
+│   │   ├── config.rs           # Configuration
+│   │   ├── deals.rs            # Deal, PositionPair, DrawdownEvent, etc.
+│   │   ├── metrics.rs          # Metrics parsing from HTML/XML
+│   │   └── report.rs           # Report, PipelineMetadata, etc.
+│   ├── analytics/              # Report extraction & analysis (migrated from Python)
+│   │   ├── extract.rs          # HTML/XML report parser → metrics.json + deals.csv
+│   │   └── analyze.rs          # Deal-level analysis engine → analysis.json
+│   ├── compile/                # MQL5 compilation
+│   │   └── mql_compiler.rs   # MetaEditor wrapper (Wine/CrossOver)
+│   ├── pipeline/               # Backtest orchestration
+│   │   ├── backtest.rs         # 5-stage pipeline (COMPILE→CLEAN→BACKTEST→EXTRACT→ANALYZE)
+│   │   └── stages.rs           # Pipeline stage definitions
+│   └── tools/                  # MCP tool definitions
+│       ├── definitions/        # Tool schemas (9 domain modules, 43 tools)
+│       │   ├── mod.rs
+│       │   ├── analytics.rs      # 9 analysis tools
+│       │   ├── backtest.rs       # 4 backtest tools
+│       │   ├── baseline.rs       # 1 baseline tool
+│       │   ├── experts.rs        # 4 EA/indicator/script tools
+│       │   ├── optimization.rs   # 4 optimization tools
+│       │   ├── reports.rs        # 11 report management tools
+│       │   ├── setfiles.rs       # 8 .set file tools
+│       │   └── system.rs         # 3 system tools
+│       └── handlers/             # Tool dispatch (9 domain modules)
+│           ├── mod.rs
+│           ├── analysis.rs
+│           ├── backtest.rs
+│           ├── experts.rs
+│           ├── optimization.rs
+│           ├── reports.rs
+│           ├── setfiles.rs
+│           └── system.rs
+│
+├── scripts/
+│   ├── setup.sh                # Auto-detect Wine/MT5, write config, register MCP
+│   ├── platform_detect.sh      # Wine path + headless detection
+│   ├── build-rust.sh           # Rust build script
+│   └── optimize.sh             # Genetic optimization launcher (nohup + disown)
+│
+├── analytics/                    # Legacy Python (reference only)
+│   ├── extract.py
+│   ├── analyze.py
+│   └── optimize_parser.py
+│
+├── config/
+│   ├── mt5-quant.example.yaml  # Template config
+│   └── mt5-quant.yaml          # Live config (gitignored)
+│
+└── docs/
+    ├── ARCHITECTURE.md         # This file
+    ├── MCP_TOOLS.md            # Full tool spec
+    └── REMOTE_AGENTS.md        # Linux agent farm setup
+```
+
+---
+
+## Pipeline Stages
+
+### Stage 1: COMPILE
+
+```rust
+// src/compile/mql_compiler.rs
+let compiler = MqlCompiler::new(config);
+let result = compiler.compile("src/experts/MyEA.mq5")?;
+```
+
+Invokes MetaEditor via Wine with the MQL5 source file. Copies resulting `.ex5` to the MT5 Experts directory. Fails the pipeline on compile errors.
+
+**Why not skip this?** MT5 caches the `.ex5` binary by filename. If you edit your EA and re-run without recompiling, MT5 runs the old binary silently. Always compile.
+
+---
+
+### Stage 2: CLEAN
+
+```bash
+rm -f "${MT5_TESTER_DIR}/cache/*.tst"
+rm -f "${MT5_PROFILES_DIR}/Tester/${EXPERT}.set"
+```
+
+Clears:
+- Tester cache (`.tst` files): compiled test results MT5 reuses to skip re-running ticks
+- Cached `.set` file: MT5 writes the current parameter values here after each run; if stale, next run picks up wrong params
+
+**The `.set` encoding trap:** MT5 reads parameter files as UTF-16LE with BOM. It writes them back as UTF-16LE. If you provide a UTF-8 `.set` file for optimization, MT5 reads the parameters correctly (it tries multiple encodings) but when it writes the optimization variants, it uses UTF-16LE and **strips the `||Y` optimization flags**. Every subsequent pass uses the base value. Your 500-combination optimization runs 500 identical backtests.
+
+Solution: always write `.set` files as UTF-16LE with BOM, mark them read-only before MT5 starts.
+
+```python
+# Python: write UTF-16LE with BOM
+content = "\n".join(lines)
+with open(set_path, 'w', encoding='utf-16-le') as f:
+    f.write('\ufeff')  # BOM
+    f.write(content)
+os.chmod(set_path, 0o444)  # read-only
+```
+
+---
+
+### Stage 3: BACKTEST
+
+```bash
+arch -x86_64 "${WINE}" cmd.exe /c 'C:\_backtest.bat'
+```
+
+The batch file sets MT5 CLI flags and launches `terminal64.exe`:
+
+```bat
+"C:\Program Files\MetaTrader 5\terminal64.exe" /config:C:\backtest.ini
+```
+
+`backtest.ini` contains:
+```ini
+[Tester]
+Expert=MyEA
+Symbol=XAUUSD
+Period=M5
+Deposit=10000
+Currency=USD
+Leverage=500
+Model=0
+FromDate=2025.01.01
+ToDate=2025.06.30
+Report=C:\report
+Optimization=0
+```
+
+MT5 runs in headless mode, writes the report, and exits.
+
+**Process isolation note:** On macOS with CrossOver, `arch -x86_64` is required — CrossOver ships arm64 Wine wrappers that don't support the x86_64 MT5 binary correctly. Without it, MT5 appears to start but produces no output.
+
+---
+
+### Stage 4: EXTRACT
+
+Single HTML/XML parse pass that produces three artifacts:
+
+```rust
+// src/analytics/extract.rs
+let extractor = ReportExtractor::new();
+let result = extractor.extract(&report_path, &output_dir)?;
+// → metrics.json  (aggregate summary)
+// → deals.csv     (all deals, 13 columns)
+// → deals.json    (same data, JSON)
+```
+
+**Why single-pass?** MT5 HTML reports are large (1-5MB for 14-month tests). Each regex pass over the file takes ~200ms. The old pipeline ran 5 separate grep/regex passes. The Rust implementation uses a single-pass parser: 5× faster and no partial-read inconsistencies.
+
+**Format detection:**
+```rust
+// MT5 Build 48+ saves SpreadsheetML XML, not HTML
+let ext = Path::new(&path).extension()
+    .and_then(|e| e.to_str())
+    .unwrap_or("");
+
+if ext == "xml" || path.ends_with(".htm.xml") {
+    // Parse as SpreadsheetML XML
+    let doc = roxmltree::Document::parse(&text)?;
+} else {
+    // Parse as HTML with regex
+}
+```
+
+**Deal columns (13):**
+```
+Time | Type | Direction | Volume | Price | S/L | T/P | Profit | Balance | Comment | Order | Magic | Entry
+```
+
+The `Comment` column is the key to grid analytics. The EA writes `"Layer #3"`, `"Locking Total"`, `"Zombie Exit"` etc. Pattern matching on comments reconstructs which position was at which layer.
+
+---
+
+### Stage 5: ANALYZE
+
+```rust
+// src/analytics/analyze.rs
+let analyzer = DealAnalyzer::new();
+let result = analyzer.analyze(&deals, &metrics, strategy, deep)?;
+// → analysis.json
+```
+
+All functions operate on the parsed deal data — no MT5 or Wine required.
+
+**Strategy profiles** (defined in `analyze.rs`):
+- `grid` — Layer depth tracking, locking/cutloss/zombie keywords
+- `scalper` — TP/SL/manual/trailing exit classification
+- `trend` — TP/SL/trailing/breakeven/partial exits
+- `hedge` — TP/SL/net_close/partial, magic+direction grouping
+- `generic` — Simple profit-based TP/SL classification
+
+#### Strategy profiles
+
+The analysis engine is driven by a `PROFILES` dict. Each profile controls:
+
+| Field | Type | Controls |
+|-------|------|----------|
+| `depth_re` | regex or `None` | Whether/how to extract depth from comments |
+| `exit_keywords` | `{reason: [kw]}` | Comment patterns for exit classification |
+| `dd_cause_keywords` | `{cause: [kw]}` | Comment patterns for DD cause classification |
+| `cycle_group_by` | `'magic'` or `'magic+direction'` | How deals are grouped into cycles |
+| `cycle_gap_min` | int | Minutes between opens that mark a new cycle |
+
+Built-in profiles:
+
+| Profile | `depth_re` | `cycle_group_by` | `cycle_gap_min` | Exit keywords |
+|---------|-----------|-----------------|----------------|---------------|
+| `generic` | — | `magic` | 60 | profit-sign only (tp/sl) |
+| `grid` | `Layer #N` | `magic+direction` | 60 | locking, cutloss, zombie, timeout |
+| `scalper` | — | `magic` | 10 | tp, sl, manual, trailing |
+| `trend` | — | `magic` | 240 | breakeven, trailing, partial, tp, sl |
+| `hedge` | — | `magic+direction` | 120 | tp, sl, net_close, partial |
+
+#### Entry points (after `pip install -e .`)
+
+```bash
+mt5-analyze         deals.csv   # generic
+mt5-analyze-grid    deals.csv   # grid / martingale (default in pipeline)
+mt5-analyze-scalper deals.csv   # scalper
+mt5-analyze-trend   deals.csv   # trend following
+mt5-analyze-hedge   deals.csv   # hedging
+```
+
+#### Analytics functions
+
+**Core (always run, strategy-agnostic):**
+
+| Function | What it computes |
+|----------|-----------------|
+| `monthly_pnl` | P/L, trade count, green flag per calendar month |
+| `reconstruct_dd_events` | Balance curve → local minima; cause from profile keywords |
+| `top_losses` | Worst individual closing deals by P/L |
+| `loss_sequences` | Consecutive losing closed deals (runs of length ≥ 2) |
+| `position_pairs` | Match in/out by order ticket → hold time, depth at close |
+| `direction_bias` | Buy vs sell win rate, total P/L, average trade |
+| `streak_analysis` | Max consecutive win/loss streaks; current streak |
+| `session_breakdown` | Asian (00–08h) / London (08–13h) / London-NY (13–17h) / New York (17–22h) |
+| `weekday_pnl` | Mon–Sun P/L and win rate |
+| `concurrent_peak` | Peak simultaneous open positions |
+
+**Strategy-driven (output varies by profile):**
+
+| Function | Generic | Grid | Scalper/Trend/Hedge |
+|----------|---------|------|---------------------|
+| `depth_histogram` | `{}` (empty) | L1–L8+ counts | `{}` (no `depth_re`) |
+| `cycle_stats` | magic, 60-min gap | magic+direction, 60-min gap | per-profile config |
+| `exit_reason_breakdown` | tp / sl | locking / cutloss / zombie / timeout | profile-specific |
+
+**Deep analytics (`--deep` flag):**
+
+| Function | What it computes |
+|----------|-----------------|
+| `hourly_pnl` | Hour-by-hour (0–23) P/L and win rate |
+| `volume_profile` | P/L breakdown by lot size tier |
+
+**DD event reconstruction:**
+1. Walk deals chronologically, track running balance
+2. At each local minimum (DD > 1%), record timestamp, depth (%), recovery date
+3. Classify `cause` using `profile['dd_cause_keywords']`; returns `"unknown"` for generic/unmatched
+
+**Cycle statistics:**
+Deals are grouped by `cycle_group_by` key. A gap greater than `cycle_gap_min` between consecutive opens marks a new cycle boundary. Win rate is computed per cycle (not per deal), then broken down by max depth reached.
+
+**Exit reason classification:**
+Iterates `exit_keywords` in definition order — more specific patterns must appear before general ones to avoid substring false-positives (e.g. `"stop"` inside `"breakeven stop"`). Falls back to profit-sign if no keyword matches.
+
+**Loss sequence detection:**
+Consecutive closed deals where P/L < 0 (minimum length 2). Captures clusters of losses better than any single worst-trade metric.
+
+---
+
+## Optimization Pipeline
+
+### Why `nohup + disown` is mandatory
+
+```bash
+nohup ./scripts/optimize.sh ... > /tmp/opt.log 2>&1 & disown
+```
+
+MT5 optimization uses Unix signals to coordinate between `terminal64.exe` (master) and `metatester64.exe` instances (workers). When the parent process tree is killed:
+
+1. `SIGHUP` propagates to child processes
+2. `metatester64.exe` workers receive the signal and terminate
+3. The master `terminal64.exe` detects worker failure and aborts the optimization
+4. `terminal.ini` is left with `OptMode=-1`, requiring manual reset before next run
+
+`nohup` prevents `SIGHUP` propagation. `disown` removes the process from the shell's job table so it's not killed when the shell exits. Both are required.
+
+---
+
+### `OptMode` state machine
+
+`terminal.ini` contains an `OptMode` key that MT5 uses to track optimization state:
+
+| `OptMode` value | Meaning |
+|----------------|---------|
+| `0` | Normal backtest mode (ready) |
+| `1` | Optimization in progress |
+| `2` | Optimization complete — show results |
+| `-1` | Optimization aborted / crashed |
+
+After any optimization run (complete or aborted), MT5 writes `-1` or `2`. On next launch with `Optimization=2` in `backtest.ini`, MT5 reads `OptMode=-1` and exits immediately without running.
+
+**Fix:** Before every optimization launch, force `OptMode=0` in `terminal.ini`:
+
+```bash
+sed -i 's/OptMode=.*/OptMode=0/' "${MT5_DIR}/terminal.ini"
+# Also remove LastOptimization line if present
+sed -i '/LastOptimization=/d' "${MT5_DIR}/terminal.ini"
+```
+
+---
+
+## Remote Agent Architecture
+
+MT5's distributed testing works via a custom TCP protocol. The master `terminal64.exe` listens on a port. Remote agents (`metatester64.exe`) connect and receive test configurations.
+
+```
+Mac (master)                    Linux server (agents)
+terminal64.exe                  metatester64.exe × N
+    │                                   │
+    └──── TCP:3000 ─────────────────────┘
+```
+
+**Linux setup:**
+```bash
+# On Linux server (Wine required)
+wine metatester64.exe /server:MAC_IP:3000 /agents:8
+```
+
+MT5 shows remote agents in the agent manager as `Agent-0.0.0.0-PORT` entries when listening, and activates them when the remote `metatester64.exe` connects.
+
+**Throughput:** Linear scaling with agent count. 10 local + 16 remote = 26 agents. A 17,000-combination optimization that takes 3 hours locally completes in ~70 minutes.
+
+---
+
+## Headless Operation
+
+MT5-Quant uses MT5's CLI mode (`terminal64.exe /config:backtest.ini`) — no user interaction, no clicking in the Strategy Tester GUI. Whether this is truly "headless" depends on platform:
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| macOS + CrossOver | Near-headless | CrossOver manages the display internally. MT5 window may flash briefly or be suppressed entirely depending on bottle settings. No monitor required in practice. |
+| Linux + Wine | Requires Xvfb | Wine needs an X11 display connection. Without one, `wine64 terminal64.exe` fails with `cannot open display`. |
+| Linux + Wine + Xvfb | Full headless | Virtual framebuffer satisfies Wine's X11 requirement. Use on servers with no monitor. |
+
+**Linux headless setup (Xvfb):**
+
+```bash
+# Install Xvfb
+sudo apt install xvfb
+
+# Start virtual display on :99
+Xvfb :99 -screen 0 1024x768x16 &
+export DISPLAY=:99
+
+# Now Wine can launch MT5 without a physical display
+wine64 terminal64.exe /config:backtest.ini
+```
+
+**Persistent virtual display (systemd):**
+
+```ini
+# /etc/systemd/system/xvfb.service
+[Unit]
+Description=Virtual Display for MT5
+
+[Service]
+ExecStart=/usr/bin/Xvfb :99 -screen 0 1024x768x16
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl enable xvfb
+sudo systemctl start xvfb
+```
+
+Then set `DISPLAY=:99` in MT5-Quant's environment config.
+
+**Note:** `metatester64.exe` (the agent worker process) is fully headless — it runs tick simulation with no display requirement. Only the master `terminal64.exe` needs a display to orchestrate the session. On Mac with CrossOver this is handled transparently.
+
+---
+
+## Known Limitations
+
+**macOS-specific:**
+- Requires Wine. The native MT5.app from the Mac App Store (or MetaQuotes CDN) ships bundled Wine at `MetaTrader 5.app/Contents/SharedSupport/wine/`. CrossOver is an alternative.
+- `arch -x86_64` required on Apple Silicon.
+- File paths must go through Wine's virtual filesystem (`C:\` = inside the Wine prefix `drive_c/`).
+
+**Report format dependency:**
+- SpreadsheetML XML format (`.htm.xml`) has no documented schema from MetaQuotes. The parser is reverse-engineered from observed output. May break on future MT5 builds.
+
+**Comment-based analytics:**
+- Strategy-specific analytics (depth histogram, exit reason, DD cause) depend on EA comment strings. EAs that don't write structured comments will get `generic` profile results — summary metrics, session breakdown, streaks, and direction bias all still work; only keyword-classified fields fall back to `"unknown"` or profit-sign.
+- Custom comment patterns can be supported by adding a new entry to `PROFILES` in `analytics/analyze.py` — no other code changes needed.
+
+**Single MT5 instance:**
+- MT5 is single-instance per Windows drive. Two backtests cannot run simultaneously on the same Wine prefix. Parallelism requires multiple Wine prefixes (separate installations).
+
+---
+
+## Claude Code Integration
+
+`setup.sh --claude-code` generates two files that give Claude persistent context about the user's trading setup:
+
+### `config/CLAUDE.template.md`
+
+A project-level CLAUDE.md template the user copies to their EA project root. Encodes:
+- MT5-Quant tool names and when to use them
+- Baseline tracking policy (never call something an improvement without comparing to `baseline.json`)
+- Symbol name reminder (broker-specific suffix matters — `XAUUSD.cent` ≠ `XAUUSD`)
+- Backtest and optimization constraints (model 0, single instance, UTF-16LE .set files)
+
+### `.claude/hooks/user-prompt-submit.sh`
+
+A Claude Code hook that runs before every prompt submission. Reads `config/baseline.json` and outputs a JSON context block:
+
+```json
+{"context": "## Production Baseline (config/baseline.json)\n..."}
+```
+
+Claude Code injects this into the system context for every conversation turn. The result: Claude always knows the current production metrics without the user having to paste them.
+
+**Hook execution path:**
+```
+User types prompt
+    → user-prompt-submit.sh executes
+    → reads config/baseline.json
+    → outputs {"context": "..."} to stdout
+    → Claude Code prepends to system context
+    → Claude sees baseline in every prompt
+```
+
+**Graceful degradation:** If `baseline.json` doesn't exist or is malformed, the hook exits 0 silently — no prompt is blocked. The baseline section simply doesn't appear until the user creates the file.
@@ -0,0 +1,107 @@
+# Configuration Reference
+
+## Config File Location
+
+```
+config/mt5-quant.yaml          # Project directory (development)
+~/.config/mt5-quant/config/mt5-quant.yaml    # System-wide (production)
+```
+
+Environment variable to override:
+```bash
+export MT5_MCP_HOME=/path/to/config
+```
+
+## Full Config Example
+
+```yaml
+# Required: Wine executable path
+wine_executable: "/Applications/MetaTrader 5.app/Contents/SharedSupport/wine/bin/wine64"
+
+# Required: MT5 installation directory
+terminal_dir: "~/Library/Application Support/net.metaquotes.wine.metatrader5/drive_c/Program Files/MetaTrader 5"
+
+# Optional: Default backtest parameters
+defaults:
+  symbol: "XAUUSD.cent"
+  timeframe: "M5"
+  deposit: 10000
+  currency: "USD"
+  model: 0                    # 0=every tick, 1=1min OHLC, 2=open price
+  leverage: 500
+
+# Optional: Display settings
+display:
+  mode: auto                  # auto, gui, headless
+  xvfb_display: ":99"         # Linux headless only
+  xvfb_screen: "1024x768x16"  # Linux headless only
+
+# Optional: Directories (auto-detected from terminal_dir if not set)
+experts_dir: "~/.../MetaTrader 5/MQL5/Experts"
+indicators_dir: "~/.../MetaTrader 5/MQL5/Indicators"
+scripts_dir: "~/.../MetaTrader 5/MQL5/Scripts"
+
+# Optional: Reports directory
+reports_dir: "./reports"
+
+# Optional: Optimization settings
+optimization:
+  remote_agents:
+    enabled: false
+    check_agent_count: true
+    min_agents: 4
+```
+
+## Platform-Specific Examples
+
+### macOS with MetaTrader 5.app
+
+```yaml
+wine_executable: "/Applications/MetaTrader 5.app/Contents/SharedSupport/wine/bin/wine64"
+terminal_dir: "~/Library/Application Support/net.metaquotes.wine.metatrader5/drive_c/Program Files/MetaTrader 5"
+defaults:
+  symbol: "XAUUSDc"
+  timeframe: "M5"
+  deposit: 10000
+```
+
+### macOS with CrossOver
+
+```yaml
+wine_executable: "/Applications/CrossOver.app/Contents/SharedSupport/CrossOver/bin/wine64"
+terminal_dir: "~/Library/Application Support/MetaQuotes/Terminal/<hash>/drive_c/Program Files/MetaTrader 5"
+```
+
+### Linux
+
+```yaml
+wine_executable: "/usr/bin/wine64"
+terminal_dir: "~/.wine/drive_c/Program Files/MetaTrader 5"
+display:
+  mode: headless
+  xvfb_display: ":99"
+```
+
+## Headless Mode (Linux VPS)
+
+```yaml
+display:
+  mode: headless
+  xvfb_display: ":99"
+  xvfb_screen: "1024x768x16"
+```
+
+Requires:
+```bash
+sudo apt install xvfb
+```
+
+## Auto-Detection
+
+`setup.sh` automatically detects:
+- Wine executable (MetaTrader 5.app, CrossOver, or system Wine)
+- MT5 terminal directory
+- Architecture (Apple Silicon adds `arch -x86_64`)
+- Display mode (GUI vs headless)
+
+Run `setup.sh` whenever you move the installation.
@@ -0,0 +1,129 @@
+# Cursor MCP Integration Setup
+
+## Quick Setup
+
+### Option 1: Download Prebuilt Binary (Recommended)
+
+```bash
+# macOS (Apple Silicon)
+curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-macos-arm64.tar.gz
+tar -xzf mt5-quant.tar.gz
+
+# Linux (x64)
+curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-linux-x64.tar.gz
+tar -xzf mt5-quant.tar.gz
+```
+
+### Option 2: Build from Source
+
+```bash
+cargo build --release
+```
+
+## Configure Cursor
+
+### Method 1: Settings UI (Recommended)
+
+1. Open Cursor Settings (`Cmd/Ctrl + ,`)
+2. Navigate to **Features** → **MCP**
+3. Click **Add Custom MCP**
+4. Enter:
+   - **Name**: `mt5-quant`
+   - **Command**: Full path to binary (e.g., `/Users/name/mt5-quant/target/release/mt5-quant`)
+   - **Type**: `stdio`
+
+### Method 2: Edit mcp.json Directly
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "mt5-quant": {
+      "type": "stdio",
+      "command": "/absolute/path/to/mt5-quant"
+    }
+  }
+}
+```
+
+Create the file if it doesn't exist:
+
+```bash
+mkdir -p ~/.cursor
+cat > ~/.cursor/mcp.json << 'EOF'
+{
+  "mcpServers": {
+    "mt5-quant": {
+      "type": "stdio",
+      "command": "/path/to/mt5-quant"
+    }
+  }
+}
+EOF
+```
+
+## Verify Setup
+
+In Cursor chat, type:
+
+```
+Run verify_setup
+```
+
+Expected output:
+```
+Wine:    /Applications/MetaTrader 5.app/.../wine64
+MT5 dir: ~/Library/Application Support/.../MetaTrader 5
+Display: gui
+Arch:    arch -x86_64
+```
+
+## Configuration Locations
+
+| Scope | Path | Use Case |
+|-------|------|----------|
+| Global | `~/.cursor/mcp.json` | Available in all projects |
+| Project | `.cursor/mcp.json` | Project-specific tools |
+
+## Troubleshooting
+
+### MCP server not appearing
+
+1. Check MCP panel in Cursor Settings
+2. Verify the path is absolute (not relative)
+3. Test binary: `/path/to/mt5-quant --help`
+4. View MCP logs: Output panel → select "MCP" from dropdown
+
+### Config interpolation
+
+Cursor supports variable substitution in `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "mt5-quant": {
+      "command": "${userHome}/bin/mt5-quant",
+      "args": ["--config", "${workspaceFolder}/config.yaml"]
+    }
+  }
+}
+```
+
+Available variables:
+- `${userHome}` - Home directory
+- `${workspaceFolder}` - Project root
+- `${workspaceFolderBasename}` - Project folder name
+- `${env:VAR_NAME}` - Environment variable
+
+### Tool not found errors
+
+If the agent says "Tool not found":
+1. Check the server is enabled in MCP settings
+2. Try disabling and re-enabling the server
+3. Restart Cursor
+
+## Resources
+
+- [Cursor MCP Documentation](https://cursor.com/docs/context/mcp)
+- [MT5-Quant Tools Reference](./MCP_TOOLS.md)
@@ -0,0 +1,191 @@
+# Quickstart Guide
+
+## 1. Download or Build
+
+### Option A: Prebuilt Binary (Recommended)
+
+```bash
+# macOS (Apple Silicon)
+curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-macos-arm64.tar.gz
+tar -xzf mt5-quant.tar.gz
+
+# Linux (x64)
+curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-linux-x64.tar.gz
+tar -xzf mt5-quant.tar.gz
+```
+
+### Option B: Build from Source
+
+```bash
+git clone https://github.com/masdevid/mt5-mcp
+cd mt5-mcp
+bash scripts/build-rust.sh
+```
+
+## 2. Install MetaTrader 5
+
+### macOS - MetaTrader 5.app (Free)
+
+1. Download from [metatrader5.com](https://www.metatrader5.com/en/download)
+2. Install to `/Applications`
+3. **Launch once** to initialize Wine prefix (~30s), then quit
+
+Auto-detected paths:
+- Wine: `/Applications/MetaTrader 5.app/Contents/SharedSupport/wine/bin/wine64`
+- MT5: `~/Library/Application Support/net.metaquotes.wine.metatrader5/drive_c/Program Files/MetaTrader 5`
+
+### macOS - CrossOver (Paid, Better Compatibility)
+
+1. Install [CrossOver](https://www.codeweavers.com/)
+2. Create bottle `MetaTrader5`
+3. Install MT5 inside bottle
+
+Auto-detected paths:
+- Wine: `/Applications/CrossOver.app/Contents/SharedSupport/CrossOver/bin/wine64`
+- MT5: `~/Library/Application Support/MetaQuotes/<hash>/drive_c/Program Files/MetaTrader 5`
+
+### Linux
+
+```bash
+# Debian/Ubuntu
+sudo apt install wine64 xvfb
+
+# Fedora/RHEL
+sudo dnf install wine xorg-x11-server-Xvfb
+
+# Install MT5
+wine64 MetaTrader5Setup.exe
+```
+
+MT5 location: `~/.wine/drive_c/Program Files/MetaTrader 5`
+
+## 3. Configure
+
+Run the setup script to auto-detect paths:
+
+```bash
+bash scripts/setup.sh          # interactive
+bash scripts/setup.sh --yes    # non-interactive (CI)
+```
+
+This creates `config/mt5-quant.yaml` (gitignored).
+
+Minimum config:
+```yaml
+wine_executable: "/Applications/MetaTrader 5.app/Contents/SharedSupport/wine/bin/wine64"
+terminal_dir: "~/Library/Application Support/net.metaquotes.wine.metatrader5/drive_c/Program Files/MetaTrader 5"
+```
+
+## 4. Register MCP Server
+
+### Claude Code
+
+```bash
+claude mcp add MT5-Quant -- /path/to/mt5-quant/target/release/mt5-quant
+```
+
+Verify:
+```bash
+claude mcp list
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mt5-quant": {
+      "command": "/path/to/mt5-quant"
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "mt5-quant": {
+      "command": "/path/to/mt5-quant"
+    }
+  }
+}
+```
+
+Or use Settings → MCP → Add Custom MCP.
+
+### VS Code
+
+Add to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "mt5-quant": {
+      "command": "/path/to/mt5-quant"
+    }
+  }
+}
+```
+
+Or run `MCP: Add Server` from Command Palette.
+
+### Antigravity
+
+1. Open Agent panel → Click "..." menu → MCP Servers
+2. Click "Manage MCP Servers"
+3. Click "View raw config" or "Edit configuration"
+4. Add to `mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mt5-quant": {
+      "command": "/path/to/mt5-quant"
+    }
+  }
+}
+```
+5. Reload Antigravity to apply changes
+
+## 5. Verify Setup
+
+```bash
+bash scripts/platform_detect.sh
+```
+
+Or in Claude/Windsurf:
+```
+Run verify_setup
+```
+
+Expected output:
+```
+Wine:    /Applications/MetaTrader 5.app/.../wine64
+MT5 dir: ~/Library/Application Support/.../MetaTrader 5
+Display: gui
+Arch:    arch -x86_64
+```
+
+## 6. Run First Backtest
+
+```
+Run a backtest on MyEA from 2025.01.01 to 2025.03.31
+```
+
+The AI will:
+1. Verify setup
+2. Compile your EA
+3. Clean MT5 cache
+4. Run backtest
+5. Extract and analyze results
+6. Report key findings
+
+---
+
+**Next:** See [TOOLS.md](TOOLS.md) for all 43 available tools.
@@ -0,0 +1,187 @@
+# Remote Agent Setup (Linux Server)
+
+MT5's distributed testing lets you farm optimization work across multiple machines. A Linux server running `metatester64.exe` via Wine connects to a Mac master over a local network.
+
+**Throughput:** Each agent handles one pass at a time. 10 local + 16 remote = 26 agents. A 17,000-combination genetic optimization that takes 3 hours locally finishes in ~70 minutes.
+
+---
+
+## Requirements
+
+**Mac (master)**
+- MetaTrader 5 installed via CrossOver or Wine
+- MT5-Quant configured and working for local backtests
+- Port 3000 open in macOS firewall (or whichever port MT5 uses — check below)
+
+**Linux server (agents)**
+- Wine 7.0+ (or Wine Staging for better compatibility)
+- `metatester64.exe` from an MT5 installation
+- Access to the same MT5 data files (tick history) as the master — or let agents download on first run
+
+---
+
+## Step 1: Find the MT5 agent port on Mac
+
+After running a local optimization, check the MT5 agent directories:
+
+```bash
+ls ~/Library/Application\ Support/MetaQuotes/*/drive_c/Program\ Files/MetaTrader\ 5/
+```
+
+You'll see directories like:
+```
+Agent-127.0.0.1-3000/   ← local agents (loopback)
+Agent-127.0.0.1-3001/
+Agent-0.0.0.0-3000/     ← remote listener (if enabled)
+```
+
+If you don't see `Agent-0.0.0.0-*` directories, enable remote agents in MT5:
+**Tools → Options → Expert Advisors → Allow remote agents**
+
+Note the port number (default: 3000).
+
+---
+
+## Step 2: Open firewall on Mac
+
+```bash
+# Check current firewall rules
+sudo pfctl -s rules
+
+# Allow incoming on agent port (example: 3000)
+# Add to /etc/pf.conf or use macOS Firewall in System Settings
+```
+
+Or use macOS System Settings → Privacy & Security → Firewall → Firewall Options → Add MetaTrader 5.
+
+---
+
+## Step 3: Install Wine on Linux server
+
+```bash
+# Ubuntu/Debian
+sudo dpkg --add-architecture i386
+sudo apt update
+sudo apt install wine64 wine32
+
+# Verify
+wine64 --version
+```
+
+---
+
+## Step 4: Copy `metatester64.exe` to Linux
+
+From your Mac MT5 installation:
+```bash
+MAC_MT5="$HOME/Library/Application Support/MetaQuotes/Terminal/XXXXX/drive_c/Program Files/MetaTrader 5"
+
+scp "${MAC_MT5}/metatester64.exe" user@linux-server:~/mt5agents/
+scp "${MAC_MT5}/metaeditor64.exe" user@linux-server:~/mt5agents/  # not required for agents
+```
+
+Also copy the required DLLs (they're in the same directory):
+```bash
+scp "${MAC_MT5}"/*.dll user@linux-server:~/mt5agents/
+```
+
+---
+
+## Step 5: Launch agents on Linux
+
+```bash
+# On the Linux server
+cd ~/mt5agents/
+
+# Replace MAC_IP with your Mac's local IP address
+# Replace 8 with number of CPU cores - 1
+wine64 metatester64.exe /server:192.168.1.100:3000 /agents:8
+```
+
+**What this does:**
+- Connects to your Mac's MT5 master at `192.168.1.100:3000`
+- Registers 8 worker agents
+- MT5 on Mac will show 8 new agents in the agent manager
+
+**To run as a background service:**
+```bash
+nohup wine64 metatester64.exe /server:192.168.1.100:3000 /agents:8 \
+    > ~/mt5agents/agents.log 2>&1 &
+disown
+```
+
+---
+
+## Step 6: Verify agents appear in MT5
+
+On your Mac, open MT5:
+**View → Strategy Tester → Agents tab**
+
+You should see entries like:
+```
+Agent-192.168.1.200-3000  [Active]
+Agent-192.168.1.200-3001  [Active]
+...
+```
+
+If agents appear as `[Inactive]`, check:
+1. Mac firewall is allowing incoming connections on the agent port
+2. Linux server can reach Mac IP: `ping 192.168.1.100`
+3. Port is open: `nc -zv 192.168.1.100 3000`
+
+---
+
+## Step 7: Configure MT5-Quant for remote agents
+
+In `config/MT5-Quant.yaml`:
+```yaml
+optimization:
+  remote_agents:
+    enabled: true
+    check_agent_count: true   # Verify remote agents are connected before launching
+    min_agents: 4             # Require at least N agents before optimizing
+```
+
+MT5-Quant will log the agent count before launching optimization:
+```
+[optimize] Local agents: 9, Remote agents: 8, Total: 17
+[optimize] Estimated completion: ~105 minutes (17,640 passes at 17 agents)
+```
+
+---
+
+## Tick Data Sync
+
+Remote agents need tick history to replay trades. On first run, MT5 automatically downloads ticks from the broker for each symbol+period combination tested. This can take 10-30 minutes per symbol.
+
+**Speed up first run:** Pre-populate the tick cache on the Linux server by copying from Mac:
+
+```bash
+# On Mac — find tick data location
+find ~/Library/Application\ Support/MetaQuotes -name "*.bin" | grep "XAUUSD"
+
+# Typical path:
+# Terminal/XXXXX/drive_c/users/user/AppData/Roaming/MetaQuotes/Terminal/Common/Files/
+
+scp -r "${TICK_DIR}" user@linux-server:~/mt5agents/ticks/
+```
+
+---
+
+## Troubleshooting
+
+**Agents connect then immediately disconnect**
+- MT5 version mismatch between `metatester64.exe` (from Mac) and the master. Use the exact same build number.
+- Check `~/mt5agents/agents.log` for Wine errors.
+
+**Agents show as connected but don't receive work**
+- MT5 sometimes requires optimization to be started before assigning work to new agents.
+- Start an optimization from the MT5 GUI first to "activate" remote agents, then cancel it and use MT5-Quant.
+
+**Performance is slower with remote agents**
+- Network latency between Mac and Linux server. Results are sent over TCP after each pass.
+- Local gigabit network: negligible. WiFi or WAN: significant overhead. Use wired connection.
+
+**Linux server runs out of memory**
+- Each `metatester64.exe` instance uses ~200-400MB.
+- 8 agents = ~2-3GB RAM. Size agent count accordingly.
@@ -0,0 +1,105 @@
+# Troubleshooting
+
+Run `verify_setup` first — it checks all paths and returns actionable hints.
+
+## Wine Not Found
+
+### macOS
+
+Confirm `/Applications/MetaTrader 5.app` exists and has been launched at least once.
+
+Check detection:
+```bash
+bash scripts/platform_detect.sh
+```
+
+If using CrossOver, confirm bottle is named `MetaTrader5`.
+
+### Linux
+
+```bash
+sudo apt install wine64        # Debian/Ubuntu
+sudo dnf install wine          # Fedora/RHEL
+which wine64                   # confirm on PATH
+```
+
+## terminal64.exe Missing
+
+MT5 unpacks `terminal64.exe` only after first launch.
+
+1. Open MetaTrader 5.app
+2. Wait for initialization (~30s)
+3. Quit
+4. Re-run setup:
+```bash
+bash scripts/setup.sh --yes
+```
+
+## MCP Server Not Appearing
+
+### Claude Code
+
+```bash
+claude mcp list                # should show MT5-Quant
+claude mcp remove MT5-Quant    # remove stale entry
+claude mcp add MT5-Quant -- /absolute/path/to/mt5-quant
+```
+
+**Must use absolute path** — relative paths break when Claude starts from different directories.
+
+### Windsurf
+
+1. Check logs: `~/.windsurf/logs/`
+2. Verify executable path is absolute
+3. Test manually: `./mt5-quant --help`
+
+## Config Not Found
+
+Set `MT5_MCP_HOME` or ensure config exists at:
+- macOS: `~/.config/mt5-quant/config/mt5-quant.yaml`
+- Project: `config/mt5-quant.yaml`
+
+## Report Not Found After Backtest
+
+1. **Wrong symbol name** — brokers use custom names (`XAUUSDm`, `XAUUSD.cent`). Check `verify_setup` or look in `<terminal_dir>/history/`.
+
+2. **No history data** — open MT5, open symbol chart, wait for history download.
+
+3. **EA crash at startup** — check `<terminal_dir>/MQL5/Logs/` for `OnInit` errors.
+
+4. **Date range has no trades** — try wider range or confirm symbol was active.
+
+## MetaEditor Compile Errors
+
+Check `<terminal_dir>/MQL5/Logs/`:
+
+- **Missing `#include`** — copy dependencies into `Experts/` alongside `.mq5`
+- **Stale `.ex5`** — delete old binary and recompile
+
+## No Deals in Backtest Report
+
+- Use `model=0` (every tick) — models 1/2 skip intra-bar movement, producing zero deals for grid/martingale EAs
+- Check `.set` file values appropriate for symbol/broker
+- Confirm `OnInit()` returns `INIT_SUCCEEDED` (MT5 Journal tab)
+
+## Optimization Never Finishes
+
+```bash
+# From Claude:
+tail_log(job_id=X, filter=errors)
+get_optimization_status(job_id=X)
+```
+
+If MT5 crashed, edit `<terminal_dir>/terminal.ini` and remove line containing `OptMode=-1`, then retry.
+
+## Permission Denied
+
+```bash
+chmod +x /path/to/mt5-quant
+```
+
+## Still Stuck?
+
+1. Run `verify_setup` and share output
+2. Check `tail_log` for errors
+3. Review `<terminal_dir>/MQL5/Logs/` for EA errors
@@ -0,0 +1,147 @@
+# VS Code MCP Integration Setup
+
+## Quick Setup
+
+### Option 1: Download Prebuilt Binary (Recommended)
+
+```bash
+# macOS (Apple Silicon)
+curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-macos-arm64.tar.gz
+tar -xzf mt5-quant.tar.gz
+
+# Linux (x64)
+curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-linux-x64.tar.gz
+tar -xzf mt5-quant.tar.gz
+```
+
+### Option 2: Build from Source
+
+```bash
+cargo build --release
+```
+
+## Configure VS Code
+
+### Method 1: Command Palette (Recommended)
+
+1. Press `Cmd/Ctrl + Shift + P`
+2. Run `MCP: Add Server`
+3. Choose **Workspace** or **User** scope
+4. Enter server name: `mt5-quant`
+5. Enter command: Full path to binary (e.g., `/Users/name/mt5-quant/target/release/mt5-quant`)
+
+### Method 2: Edit mcp.json Directly
+
+Add to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "mt5-quant": {
+      "command": "/absolute/path/to/mt5-quant"
+    }
+  }
+}
+```
+
+Create the file:
+
+```bash
+mkdir -p .vscode
+cat > .vscode/mcp.json << 'EOF'
+{
+  "servers": {
+    "mt5-quant": {
+      "command": "/path/to/mt5-quant"
+    }
+  }
+}
+EOF
+```
+
+### Method 3: VS Code CLI
+
+```bash
+code --add-mcp '{"name":"mt5-quant","command":"/path/to/mt5-quant"}'
+```
+
+## Verify Setup
+
+In Copilot chat, type:
+
+```
+Run verify_setup
+```
+
+Expected output:
+```
+Wine:    /Applications/MetaTrader 5.app/.../wine64
+MT5 dir: ~/Library/Application Support/.../MetaTrader 5
+Display: gui
+Arch:    arch -x86_64
+```
+
+## Configuration Locations
+
+| Scope | Path | Use Case |
+|-------|------|----------|
+| Workspace | `.vscode/mcp.json` | Share with team via source control |
+| User | `~/.vscode/mcp.json` | Personal tools across all projects |
+| Dev Container | `devcontainer.json` → `customizations.vscode.mcp` | Containerized environments |
+
+## Troubleshooting
+
+### MCP server not appearing
+
+1. Open **Output** panel (`Cmd/Ctrl + Shift + U`)
+2. Select **MCP** from dropdown
+3. Check for connection errors
+4. Verify the path is absolute
+
+### Config not found
+
+The binary auto-detects its config, but you can also:
+1. Run `setup.sh` to create `config/mt5-quant.yaml`
+2. Or let the binary auto-discover on first run
+
+### Dev Container Setup
+
+Add to `.devcontainer/devcontainer.json`:
+
+```json
+{
+  "customizations": {
+    "vscode": {
+      "mcp": {
+        "servers": {
+          "mt5-quant": {
+            "command": "/path/to/mt5-quant"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Key Differences from Other IDEs
+
+VS Code uses `servers` (not `mcpServers`) in the JSON structure:
+
+```json
+{
+  "servers": {        // ← VS Code uses "servers"
+    "mt5-quant": {
+      "command": "..."
+    }
+  }
+}
+```
+
+Other platforms use `mcpServers`.
+
+## Resources
+
+- [VS Code MCP Documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
+- [MCP Configuration Reference](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration)
+- [MT5-Quant Tools Reference](./MCP_TOOLS.md)
@@ -0,0 +1,104 @@
+# Windsurf MCP Integration Setup
+
+## Quick Setup
+
+### Option 1: Download Prebuilt Binary (Recommended)
+
+```bash
+# macOS (Apple Silicon)
+curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-macos-arm64.tar.gz
+tar -xzf mt5-quant.tar.gz
+
+# Linux (x64)
+curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-mcp/releases/latest/download/mt5-quant-linux-x64.tar.gz
+tar -xzf mt5-quant.tar.gz
+```
+
+### Option 2: Build from Source
+
+```bash
+bash scripts/build-rust.sh
+```
+
+### 2. Configure Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mt5-quant": {
+      "command": "/Users/masdevid/jobs/mt5-quant/target/release/mt5-quant"
+    }
+  }
+}
+```
+
+Or use the automated setup:
+
+```bash
+bash scripts/setup.sh
+```
+
+### 3. Restart Windsurf
+Close and reopen Windsurf to load the MCP server.
+
+### 4. Verify
+In Windsurf chat, test with:
+```
+Run verify_setup
+```
+
+## Deployment to Multiple Machines
+
+### Build for Distribution
+```bash
+# Build release binary
+cargo build --release
+
+# Create tarball
+tar -czf mt5-quant-macos-arm64.tar.gz -C target/release mt5-quant
+
+# Deploy to remote server
+scp mt5-quant-macos-arm64.tar.gz user@server:~/
+ssh user@server "tar -xzf mt5-quant-macos-arm64.tar.gz -C /opt/"
+ssh user@server "ln -s /opt/mt5-quant /usr/local/bin/"
+
+# Copy config
+scp -r config/mt5-quant.yaml user@server:~/.config/mt5-quant/config/
+```
+
+### Target Machine Requirements
+- MetaTrader 5 installed (via Wine/CrossOver)
+- Config file at `~/.config/mt5-quant/config/mt5-quant.yaml`
+- **NO Python required!**
+
+### Windsurf Config on Target Machine
+
+```json
+{
+  "mcpServers": {
+    "mt5-quant": {
+      "command": "/usr/local/bin/mt5-quant"
+    }
+  }
+}
+```
+
+The binary auto-detects its config location. No environment variables needed.
+
+## Troubleshooting
+
+### MCP server not appearing
+1. Check Windsurf logs: `~/.windsurf/logs/`
+2. Verify executable path is absolute
+3. Test executable manually: `./target/release/mt5-quant --help`
+
+### Config not found
+Set `MT5_MCP_HOME` environment variable or ensure config is at default location:
+- macOS: `~/.config/mt5-quant/config/mt5-quant.yaml`
+
+### Permission denied
+```bash
+chmod +x /path/to/mt5-quant
+```
@@ -0,0 +1,30 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.masdevid/mt5-quant",
+  "title": "MT5-Quant",
+  "description": "MCP server for MT5 strategy development. 85 tools for backtesting, optimizing, and debugging MQL5 EAs on macOS/Linux.",
+  "repository": {
+    "url": "https://github.com/masdevid/mt5-quant",
+    "source": "github"
+  },
+  "version": "1.30.0",
+  "packages": [
+    {
+      "registryType": "mcpb",
+      "version": "1.30.0",
+      "identifier": "https://github.com/masdevid/mt5-quant/releases/download/v1.30.0/mcp-mt5-quant-macos-arm64.tar.gz",
+      "fileSha256": "PLACEHOLDER_SHA256",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "description": "Path to MT5-Quant config directory (default: ~/.config/mt5-quant)",
+          "isRequired": false,
+          "format": "string",
+          "name": "MT5_MCP_HOME"
+        }
+      ]
+    }
+  ]
+}
@@ -2,7 +2,7 @@
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.masdevid/mt5-quant",
  "title": "MT5-Quant",
-  "description": "MCP server for MT5 strategy development with 85 tools. Compile, backtest, analyze, optimize, and debug MQL5 EAs on macOS/Linux. Includes Wine/MT5 crash diagnostics.",
+  "description": "MCP server for MT5 strategy development. 85 tools for backtesting, optimizing, and debugging MQL5 EAs on macOS/Linux.",
  "repository": {
    "url": "https://github.com/masdevid/mt5-quant",
    "source": "github"
@@ -13,7 +13,7 @@
      "registryType": "mcpb",
      "version": "1.30.0",
      "identifier": "https://github.com/masdevid/mt5-quant/releases/download/v1.30.0/mcp-mt5-quant-macos-arm64.tar.gz",
-      "fileSha256": "PLACEHOLDER_SHA256",
+      "fileSha256": "6028b87c5be71db157c83e9804936190d9c3c546089e728b87496cbfc4168c0d",
      "transport": {
        "type": "stdio"
      },