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:**
This commit is contained in:
Devid HW
+107
@@ -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,138 @@
|
||||
# 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 `~/.windsurf/config.yaml`:
|
||||
```yaml
|
||||
mcpServers:
|
||||
mt5-quant:
|
||||
command: /path/to/mt5-quant
|
||||
env:
|
||||
MT5_MCP_HOME: /path/to/mt5-mcp
|
||||
```
|
||||
|
||||
## 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,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
|
||||
Reference in New Issue
Block a user