Files

T

Devid HW 1461d9cd37 docs: Reorganize documentation structure

**README.md** - Slimmed from 548 → 156 lines
- Removed duplicated content now in separate docs
- Links to new focused documentation files
- Quick install + quick start only

**New docs created:**
- docs/QUICKSTART.md - Complete setup guide (macOS/Linux)
- docs/CONFIG.md - Configuration reference with examples
- docs/TROUBLESHOOTING.md - Common issues and solutions

**Existing docs retained:**
- docs/MCP_TOOLS.md - Tool specifications (31/43 documented)
- docs/ARCHITECTURE.md - Design and internals
- docs/REMOTE_AGENTS.md - Linux optimization agents

**Documentation structure:**

2026-04-19 03:33:54 +07:00

2.6 KiB

Raw Permalink Blame History

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 scripts/platform_detect.sh

If using CrossOver, confirm bottle is named MetaTrader5.

Linux

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.

Open MetaTrader 5.app
Wait for initialization (~30s)
Quit
Re-run setup:

bash scripts/setup.sh --yes

MCP Server Not Appearing

Claude Code

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

Check logs: ~/.windsurf/logs/
Verify executable path is absolute
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

Wrong symbol name — brokers use custom names (XAUUSDm, XAUUSD.cent). Check verify_setup or look in <terminal_dir>/history/.
No history data — open MT5, open symbol chart, wait for history download.
EA crash at startup — check <terminal_dir>/MQL5/Logs/ for OnInit errors.
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

# 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

chmod +x /path/to/mt5-quant

Still Stuck?

Run verify_setup and share output
Check tail_log for errors
Review <terminal_dir>/MQL5/Logs/ for EA errors

2.6 KiB Raw Permalink Blame History