gavindiaz/mt5-quant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: simplify docs for LLM automation, remove platform-specific install steps

Browse Source 
- Rewrite README.md to focus on LLM-driven install setup
- Simplify QUICKSTART.md to minimal LLM instruction guide
- Rewrite CONFIG.md to remove platform-specific path examples
- Delete platform-specific IDE docs (CLAUDE.md, CURSOR.md, VSCODE.md, WINDSURF.md)
- Simplify REMOTE_AGENTS.md to remove Wine install details
- Clean up TROUBLESHOOTING.md to remove platform install sections
- Ignore .vscode/ and .codegraph/ directories
- Untrack server.json (should remain tracked - already restored)
This commit is contained in:
Devid HW
2026-06-25 14:49:30 +07:00
parent 50025968ff
commit e954883189
11 changed files with 78 additions and 927 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+6
View File
@@ -26,6 +26,12 @@ config/backtest_history.json
# Windsurf (local workflows, not for repo) # Windsurf (local workflows, not for repo)
.windsurf/ .windsurf/
# VS Code
.vscode/
# Codegraph
.codegraph/
# macOS # macOS
.DS_Store .DS_Store
.vscode/settings.json
Vendored
-8
View File
@@ -1,8 +0,0 @@
{
"json.schemas": [
{
"fileMatch": ["server.json"],
"url": "https://raw.githubusercontent.com/modelcontextprotocol/specification/main/schema/2024-11-05/schema.json"
}
]
}
README.md
+28 -78
View File
@@ -27,83 +27,33 @@ Claude: [compile → clean → backtest → analyze 1,847 deals]
**Others** typically run on Windows using the [MetaTrader5 Python package](https://pypi.org/project/MetaTrader5/), providing full terminal operations. MT5-Quant fills the gap: **organizing backtest reports, extracting deal-level insights, and managing optimization workflows** — none of which MT5 or its Python API expose natively. **Others** typically run on Windows using the [MetaTrader5 Python package](https://pypi.org/project/MetaTrader5/), providing full terminal operations. MT5-Quant fills the gap: **organizing backtest reports, extracting deal-level insights, and managing optimization workflows** — none of which MT5 or its Python API expose natively.
## Why Rust
**MT5-Quant is built entirely in Rust** — one static binary, zero dependencies, instant startup.
| | Rust | Python/Node |
|---|---|---|
| **Startup** | ~10ms | 200–500ms |
| **Deploy** | Single binary | venv + pip/npm |
| **Memory** | <50MB, no GC pauses | Unpredictable spikes |
| **Safety** | Compile-time guaranteed | Runtime exceptions |
**Why this matters for trading:**
- **No garbage collection** — Process 100k+ deal rows without GC pauses during live analysis
- **Async via Tokio** — Handle multiple tool calls concurrently (poll status while streaming logs)
- **Cross-platform** — Same source compiles to native macOS arm64 and Linux x86_64
- **Type-safe pipelines** — MQL5 compilation, Wine path handling, SQLite queries: all checked at compile time
## Quick Install
### Option 1: Pre-built Binary (Recommended)
```bash
curl -L -o mt5.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mcp-mt5-quant-macos-arm64.tar.gz
tar -xzf mt5.tar.gz
bash scripts/setup.sh
```
### Option 2: Cargo Install (if you have Rust)
```bash
cargo install mt5-quant
mt5-quant --help
```
Compiles from source. Takes 2–5 minutes. Requires Rust 1.70+.
### 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) |
| **Claude Desktop** | Agent Panel → ... → MCP Servers → Edit configuration | [CLAUDE.md →](docs/CLAUDE.md) |
> **Note:** Use absolute paths like `/Users/name/mt5-quant/mt5-quant` or `$(pwd)/mt5-quant`, not relative paths like `./mt5-quant`.
## Quick Start ## Quick Start
### Install MT5-Quant
Ask your LLM coding platform to install and configure MT5-Quant:
> "Please install mt5-quant. It's a Rust-based MCP server for MT5 backtesting at https://github.com/masdevid/mt5-quant. Run its `scripts/setup.sh` to auto-detect Wine and MT5 paths, register the MCP server, and configure everything."
The LLM will:
1. Download the pre-built binary (or `cargo build --release`)
2. Run `scripts/setup.sh` to auto-detect Wine/MT5 and write config
3. Register the MCP server with your coding platform
### First Backtest
``` ```
Run a backtest on MyEA from 2025.01.01 to 2025.03.31 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. 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 |
| [CLAUDE.md](docs/CLAUDE.md) | Claude Desktop setup |
| [CONFIG.md](docs/CONFIG.md) | Configuration reference |
| [TOOLS.md](docs/MCP_TOOLS.md) | All 89 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 (89) ## MCP Tools (89)
### Core workflow ### Core workflow
| Tool | Description | | Tool | Description |
|------|-------------| |------|-----|
| `run_backtest` | Full pipeline: compile → clean → backtest → extract → analyze | | `run_backtest` | Full pipeline: compile → clean → backtest → extract → analyze |
| `run_backtest_quick` | Quick backtest using pre-compiled EA (skip compile) | | `run_backtest_quick` | Quick backtest using pre-compiled EA (skip compile) |
| `run_backtest_only` | Backtest only - just extract raw trades, no analysis | | `run_backtest_only` | Backtest only - just extract raw trades, no analysis |
@@ -124,7 +74,7 @@ The AI runs the full pipeline: compile → clean cache → backtest → extract
### Granular Analytics (individual analysis) ### Granular Analytics (individual analysis)
| Tool | Description | | Tool | Description |
|------|-------------| |------|-----|
| `analyze_monthly_pnl` | Monthly P/L breakdown only | | `analyze_monthly_pnl` | Monthly P/L breakdown only |
| `analyze_drawdown_events` | Drawdown events and causes only | | `analyze_drawdown_events` | Drawdown events and causes only |
| `analyze_top_losses` | Worst losing deals only | | `analyze_top_losses` | Worst losing deals only |
@@ -139,7 +89,7 @@ Use these for targeted analysis, or `analyze_report` to run all at once.
### Deal-Level Analytics (New) ### Deal-Level Analytics (New)
| Tool | Description | | Tool | Description |
|------|-------------| |------|-----|
| `list_deals` | List individual deals with filters (type, profit range, volume, dates) | | `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_comment` | Full-text search in deal comments (e.g., "Layer #3") |
| `search_deals_by_magic` | Filter deals by EA magic number | | `search_deals_by_magic` | Filter deals by EA magic number |
@@ -154,7 +104,7 @@ Use these for targeted analysis, or `analyze_report` to run all at once.
### Monitoring ### Monitoring
| Tool | Description | | Tool | Description |
|------|-------------| |------|-----|
| `verify_setup` | Check Wine/MT5 paths, Wine version, and EA/set file counts | | `verify_setup` | Check Wine/MT5 paths, Wine version, and EA/set file counts |
| `get_optimization_status` | Check live state of a background optimization job | | `get_optimization_status` | Check live state of a background optimization job |
| `list_jobs` | All optimization jobs with compact status in one call | | `list_jobs` | All optimization jobs with compact status in one call |
@@ -162,7 +112,7 @@ Use these for targeted analysis, or `analyze_report` to run all at once.
### Reports & logs ### Reports & logs
| Tool | Description | | Tool | Description |
|------|-------------| |------|-----|
| `list_reports` | Compact table of all runs with key metrics — no full analysis needed | | `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 | | `get_latest_report` | Get most recent report with optional equity chart |
| `search_reports` | Find reports by EA, symbol, date range, or profit criteria | | `search_reports` | Find reports by EA, symbol, date range, or profit criteria |
@@ -181,7 +131,7 @@ Use these for targeted analysis, or `analyze_report` to run all at once.
### History & baseline ### History & baseline
| Tool | Description | | Tool | Description |
|------|-------------| |------|-----|
| `archive_report` | Convert one report dir → compact JSON entry in `backtest_history.json`, optionally delete source | | `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 | | `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 | | `get_history` | Query history with filters (EA, symbol, verdict, profit, DD) and sort options |
@@ -190,14 +140,14 @@ Use these for targeted analysis, or `analyze_report` to run all at once.
### Cache management ### Cache management
| Tool | Description | | Tool | Description |
|------|-------------| |------|-----|
| `cache_status` | MT5 tester cache size breakdown by symbol — check before cleaning | | `cache_status` | MT5 tester cache size breakdown by symbol — check before cleaning |
| `clean_cache` | Delete tester cache files; supports per-symbol and `dry_run` | | `clean_cache` | Delete tester cache files; supports per-symbol and `dry_run` |
### Pre-flight & Validation ### Pre-flight & Validation
| Tool | Description | | Tool | Description |
|------|-------------| |------|-----|
| `get_active_account` | Get current MT5 account session (login, server, available symbols) | | `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_symbol_data_status` | Validate symbol has sufficient history data for date range |
| `check_mt5_status` | Check if MT5 terminal is installed and ready | | `check_mt5_status` | Check if MT5 terminal is installed and ready |
@@ -206,7 +156,7 @@ Use these for targeted analysis, or `analyze_report` to run all at once.
### Debugging & Diagnostics (New) ### Debugging & Diagnostics (New)
| Tool | Description | | Tool | Description |
|------|-------------| |------|-----|
| `diagnose_wine` | Check Wine installation, version, and prefix health | | `diagnose_wine` | Check Wine installation, version, and prefix health |
| `get_mt5_logs` | Get MT5 terminal, tester, or MetaEditor logs with filtering | | `get_mt5_logs` | Get MT5 terminal, tester, or MetaEditor logs with filtering |
| `search_mt5_errors` | Search logs for error patterns (crash, exception, access violation) | | `search_mt5_errors` | Search logs for error patterns (crash, exception, access violation) |
@@ -222,7 +172,7 @@ Use these for targeted analysis, or `analyze_report` to run all at once.
### Project Management ### Project Management
| Tool | Description | | Tool | Description |
|------|-------------| |------|-----|
| `init_project` | Scaffold new MQL5 project with templates (scalper/swing/grid/basic) | | `init_project` | Scaffold new MQL5 project with templates (scalper/swing/grid/basic) |
| `create_set_template` | Generate .set parameter file from EA input variables | | `create_set_template` | Generate .set parameter file from EA input variables |
| `export_report` | Export backtest report to CSV, JSON, or Markdown | | `export_report` | Export backtest report to CSV, JSON, or Markdown |
@@ -230,14 +180,14 @@ Use these for targeted analysis, or `analyze_report` to run all at once.
### History & Comparison ### History & Comparison
| Tool | Description | | Tool | Description |
|------|-------------| |------|-----|
| `get_backtest_history` | List all backtests for EA/symbol with summary metrics | | `get_backtest_history` | List all backtests for EA/symbol with summary metrics |
| `compare_backtests` | Compare 2+ backtest results side-by-side with analysis | | `compare_backtests` | Compare 2+ backtest results side-by-side with analysis |
### .set file — read / write ### .set file — read / write
| Tool | Description | | Tool | Description |
|------|-------------| |------|-----|
| `list_set_files` | All .set files in tester profiles dir with sweep stats and combination counts | | `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 | | `read_set_file` | Parse UTF-16LE `.set` file → structured JSON params |
| `write_set_file` | Write full params dict → UTF-16LE `.set` with `chmod 444` | | `write_set_file` | Write full params dict → UTF-16LE `.set` with `chmod 444` |
@@ -247,7 +197,7 @@ Use these for targeted analysis, or `analyze_report` to run all at once.
### .set file — analysis & generation ### .set file — analysis & generation
| Tool | Description | | Tool | Description |
|------|-------------| |------|-----|
| `describe_sweep` | Swept params, value counts, and total optimization combinations | | `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 | | `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 | | `set_from_optimization` | Generate a clean backtest `.set` from `get_optimization_results` params; optionally narrow sweep |
@@ -255,7 +205,7 @@ Use these for targeted analysis, or `analyze_report` to run all at once.
### Search & Discovery ### Search & Discovery
| Tool | Description | | Tool | Description |
|------|-------------| |------|-----|
| `search_experts` | Search EAs by name pattern across all directories | | `search_experts` | Search EAs by name pattern across all directories |
| `search_indicators` | Search indicators by name pattern | | `search_indicators` | Search indicators by name pattern |
| `search_scripts` | Search scripts by name pattern | | `search_scripts` | Search scripts by name pattern |
@@ -266,7 +216,7 @@ Full schema: [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md)
## Troubleshooting ## Troubleshooting
Run `verify_setup` from Claude first — it checks all paths and returns actionable hints. Run `verify_setup` from your LLM first — it checks all paths and returns actionable hints.
For crashes or unexplained failures during backtest/compile/optimization: For crashes or unexplained failures during backtest/compile/optimization:
- `diagnose_wine` — Check Wine installation and prefix health - `diagnose_wine` — Check Wine installation and prefix health
docs/CLAUDE.md
-142
View File
@@ -1,142 +0,0 @@
# Claude Desktop MCP Integration Setup
## Quick Setup
### Option 1: Install via MCP Registry (Recommended)
Search for `mt5-quant` in Claude Desktop's MCP manager, or add directly to your config.
### Option 2: Download Prebuilt Binary
```bash
# macOS (Apple Silicon)
curl -L -o mt5-quant.tar.gz https://github.com/masdevid/mt5-quant/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-quant/releases/latest/download/mt5-quant-linux-x64.tar.gz
tar -xzf mt5-quant.tar.gz
```
### Option 3: Build from Source
```bash
git clone https://github.com/masdevid/mt5-quant
cd mt5-quant
cargo build --release
```
## Configure Claude Desktop
### Step 1: Open MCP Configuration
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
### Step 2: Add mt5-quant
```json
{
"mcpServers": {
"mt5-quant": {
"command": "/absolute/path/to/mt5-quant"
}
}
}
```
### Step 3: Reload and Verify
1. Save the file
2. **Restart Claude Desktop**
3. In a new conversation, 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/mcp-server/bin/mt5-quant"
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}"
}
}
}
}
```
**Path notes:**
- Prebuilt binary: `/Users/name/mt5-quant/mcp-server/bin/mt5-quant` (extracted from release tarball)
- Dev build: `/Users/name/mt5-quant/target/release/mt5-quant` (after `cargo build --release`)
## Environment Variables
Claude Desktop supports `${env:VAR_NAME}` syntax for environment variable substitution:
```json
{
"mcpServers": {
"mt5-quant": {
"command": "/Users/name/mt5-quant/mcp-server/bin/mt5-quant",
"env": {
"MT5_MCP_HOME": "${env:HOME}/.config/mt5-quant"
}
}
}
}
```
## Verify Setup
In a Claude Desktop conversation, 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
### "Tool not found" or server not appearing
1. Double-check the absolute path in `claude_desktop_config.json`
2. Ensure the binary has execute permissions: `chmod +x /path/to/mt5-quant`
3. Restart Claude Desktop completely
4. Check Claude Desktop logs: `~/Library/Logs/Claude/` (macOS)
### JSON syntax errors
1. Validate the JSON at [jsonlint.com](https://jsonlint.com)
2. Ensure no trailing commas
3. Use absolute paths (not `~` or relative paths)
### Agent hallucinating tool parameters
1. Verify the tool is available: "List your available MCP tools"
2. Start a new conversation
3. Be explicit: "Use the `run_backtest` tool with expert=MyEA"
## Configuration Location
| Platform | Path |
|----------|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
## Resources
- [Claude Desktop MCP Documentation](https://docs.anthropic.com/en/docs/claude-code/mcp)
- [MCP Server Reference](https://github.com/modelcontextprotocol/servers)
- [MT5-Quant Tools Reference](./MCP_TOOLS.md)
docs/CONFIG.md
+4 -51
View File
@@ -1,18 +1,15 @@
# Configuration Reference # Configuration Reference
## Config File Location ## Config File
``` ```
config/mt5-quant.yaml # Project directory (development) config/mt5-quant.yaml # Project directory (development)
~/.config/mt5-quant/config/mt5-quant.yaml # System-wide (production) ~/.config/mt5-quant/config/mt5-quant.yaml # System-wide (production)
``` ```
Environment variable to override: Override with env: `export MT5_MCP_HOME=/path/to/config`
```bash
export MT5_MCP_HOME=/path/to/config
```
## Full Config Example ## Full Example
```yaml ```yaml
# Required: Wine executable path # Required: Wine executable path
@@ -52,53 +49,9 @@ optimization:
min_agents: 4 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 ## Auto-Detection
`setup.sh` automatically detects: `setup.sh` detects:
- Wine executable (MetaTrader 5.app, CrossOver, or system Wine) - Wine executable (MetaTrader 5.app, CrossOver, or system Wine)
- MT5 terminal directory - MT5 terminal directory
- Architecture (Apple Silicon adds `arch -x86_64`) - Architecture (Apple Silicon adds `arch -x86_64`)
docs/CURSOR.md
-129
View File
@@ -1,129 +0,0 @@
# Cursor MCP Integration Setup
## Quick Setup
### Option 1: Download Prebuilt Binary (Recommended)
```bash
# macOS (Apple Silicon)
curl -L -o mt5.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mcp-mt5-quant-macos-arm64.tar.gz
tar -xzf mt5.tar.gz
# Linux (x64)
curl -L -o mt5.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mcp-mt5-quant-linux-x64.tar.gz
tar -xzf mt5.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**: `/path/to/mt5-quant/mcp-server/bin/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": "/path/to/mt5-quant/mcp-server/bin/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/mcp-server/bin/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/mcp-server/bin/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}/mt5-quant/mcp-server/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)
docs/QUICKSTART.md
+18 -166
View File
@@ -1,192 +1,44 @@
# Quickstart Guide # Quickstart Guide
## 1. Download or Build For end-users wanting full platform-specific steps, see the [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).
### Option A: Prebuilt Binary (Recommended) ## Install
```bash Ask your LLM platform to install MT5-Quant:
# macOS (Apple Silicon)
curl -L -o mt5.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mcp-mt5-quant-macos-arm64.tar.gz
tar -xzf mt5.tar.gz
# Linux (x64) > "Please install mt5-quant from https://github.com/masdevid/mt5-quant. Download the pre-built binary, run `scripts/setup.sh` to auto-detect Wine/MT5 paths, and register the MCP server."
curl -L -o mt5.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mcp-mt5-quant-linux-x64.tar.gz
tar -xzf mt5.tar.gz
```
### Option B: Build from Source The LLM will handle:
1. Download binary or `cargo build --release`
2. Run setup script to auto-detect Wine and MT5 paths
3. Write `config/mt5-quant.yaml` (gitignored)
4. Register MCP server with your platform
```bash ## Minimal Config
git clone https://github.com/masdevid/mt5-quant
cd mt5-quant
bash scripts/build-rust.sh
```
## 2. Install MetaTrader 5 If manual config is needed, `config/mt5-quant.yaml` requires only:
### 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 ```yaml
wine_executable: "/Applications/MetaTrader 5.app/Contents/SharedSupport/wine/bin/wine64" wine_executable: "/path/to/wine64"
terminal_dir: "~/Library/Application Support/net.metaquotes.wine.metatrader5/drive_c/Program Files/MetaTrader 5" terminal_dir: "/path/to/MetaTrader 5"
``` ```
## 4. Register MCP Server `setup.sh` auto-detects both.
### Claude Code ## Verify
```bash
claude mcp add io.github.masdevid/mt5-quant -- ~/.local/bin/mt5-quant
# Or: claude mcp add mt5-quant -- $(pwd)/mcp-server/bin/mt5-quant
```
Verify:
```bash
claude mcp list
```
### Windsurf
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"mt5-quant": {
"command": "/path/to/mt5-quant/mcp-server/bin/mt5-quant"
}
}
}
```
### Cursor
Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):
```json
{
"mcpServers": {
"mt5-quant": {
"command": "/path/to/mt5-quant/mcp-server/bin/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/mcp-server/bin/mt5-quant"
}
}
}
```
Or run `MCP: Add Server` from Command Palette.
### Claude Desktop
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. Restart Claude Desktop to apply changes
## 5. Verify Setup
```bash
bash scripts/platform_detect.sh
```
Or in Claude/Windsurf:
``` ```
Run verify_setup Run verify_setup
``` ```
Expected output: ## Run Backtest
```
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 Run a backtest on MyEA from 2025.01.01 to 2025.03.31
``` ```
The AI will: The AI runs: compile → clean → backtest → extract → analyze.
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 89 available tools. **Next:** See [TOOLS.md](docs/MCP_TOOLS.md) for all 89 tools.
docs/REMOTE_AGENTS.md
+14 -95
View File
@@ -11,14 +11,12 @@ MT5's distributed testing lets you farm optimization work across multiple machin
**Mac (master)** **Mac (master)**
- MetaTrader 5 installed via CrossOver or Wine - MetaTrader 5 installed via CrossOver or Wine
- MT5-Quant configured and working for local backtests - MT5-Quant configured and working for local backtests
- Port 3000 open in macOS firewall (or whichever port MT5 uses — check below) - Port 3000 open in macOS firewall (or whichever port MT5 uses)
**Linux server (agents)** **Linux server (agents)**
- Wine 7.0+ (or Wine Staging for better compatibility) - Wine 7.0+
- `metatester64.exe` from an MT5 installation - `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 - Access to the same MT5 data files (tick history) as the master
---
## Step 1: Find the MT5 agent port on Mac ## Step 1: Find the MT5 agent port on Mac
@@ -31,7 +29,6 @@ ls ~/Library/Application\ Support/MetaQuotes/*/drive_c/Program\ Files/MetaTrader
You'll see directories like: You'll see directories like:
``` ```
Agent-127.0.0.1-3000/ ← local agents (loopback) 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) Agent-0.0.0.0-3000/ ← remote listener (if enabled)
``` ```
@@ -40,69 +37,23 @@ If you don't see `Agent-0.0.0.0-*` directories, enable remote agents in MT5:
Note the port number (default: 3000). Note the port number (default: 3000).
--- ## Step 2: Copy `metatester64.exe` to Linux
## 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: From your Mac MT5 installation:
```bash ```bash
MAC_MT5="$HOME/Library/Application Support/MetaQuotes/Terminal/XXXXX/drive_c/Program Files/MetaTrader 5" MAC_MT5="$HOME/Library/Application Support/MetaQuotes/Terminal/XXX/ drive_c/Program Files/MetaTrader 5"
scp "${MAC_MT5}/metatester64.exe" user@linux-server:~/mt5agents/ 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/ scp "${MAC_MT5}"/*.dll user@linux-server:~/mt5agents/
``` ```
--- ## Step 3: Launch agents on Linux
## Step 5: Launch agents on Linux
```bash ```bash
# On the Linux server
cd ~/mt5agents/ 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 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:** **To run as a background service:**
```bash ```bash
nohup wine64 metatester64.exe /server:192.168.1.100:3000 /agents:8 \ nohup wine64 metatester64.exe /server:192.168.1.100:3000 /agents:8 \
@@ -110,9 +61,7 @@ nohup wine64 metatester64.exe /server:192.168.1.100:3000 /agents:8 \
disown disown
``` ```
--- ## Step 4: Verify agents appear in MT5
## Step 6: Verify agents appear in MT5
On your Mac, open MT5: On your Mac, open MT5:
**View → Strategy Tester → Agents tab** **View → Strategy Tester → Agents tab**
@@ -120,68 +69,38 @@ On your Mac, open MT5:
You should see entries like: You should see entries like:
``` ```
Agent-192.168.1.200-3000 [Active] Agent-192.168.1.200-3000 [Active]
Agent-192.168.1.200-3001 [Active]
...
``` ```
If agents appear as `[Inactive]`, check: ## Step 5: Configure MT5-Quant for remote agents
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`
--- In `config/mt5-quant.yaml`:
## Step 7: Configure MT5-Quant for remote agents
In `config/MT5-Quant.yaml`:
```yaml ```yaml
optimization: optimization:
remote_agents: remote_agents:
enabled: true enabled: true
check_agent_count: true # Verify remote agents are connected before launching check_agent_count: true
min_agents: 4 # Require at least N agents before optimizing min_agents: 4
``` ```
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 ## 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. On first run, MT5 automatically downloads ticks from the broker. Pre-populate on Linux:
**Speed up first run:** Pre-populate the tick cache on the Linux server by copying from Mac:
```bash ```bash
# On Mac — find tick data location # On Mac — find tick data location
find ~/Library/Application\ Support/MetaQuotes -name "*.bin" | grep "XAUUSD" find ~/Library/Application\ Support/MetaQuotes -name "*.bin" | grep "XAUUSD"
# Typical path: # Copy to Linux
# Terminal/XXXXX/drive_c/users/user/AppData/Roaming/MetaQuotes/Terminal/Common/Files/
scp -r "${TICK_DIR}" user@linux-server:~/mt5agents/ticks/ scp -r "${TICK_DIR}" user@linux-server:~/mt5agents/ticks/
``` ```
---
## Troubleshooting ## Troubleshooting
**Agents connect then immediately disconnect** **Agents connect then immediately disconnect**
- MT5 version mismatch between `metatester64.exe` (from Mac) and the master. Use the exact same build number. - 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** **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. - 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** **Performance is slower with remote agents**
- Network latency between Mac and Linux server. Results are sent over TCP after each pass. - Use wired connection. WiFi or WAN: significant overhead.
- 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.
docs/TROUBLESHOOTING.md
+8 -3
View File
@@ -17,12 +17,17 @@ If using CrossOver, confirm bottle is named `MetaTrader5`.
### Linux ### Linux
Install Wine 7.0+ and confirm on PATH:
```bash ```bash
sudo apt install wine64 # Debian/Ubuntu # Debian/Ubuntu
sudo dnf install wine # Fedora/RHEL sudo apt install wine64
which wine64 # confirm on PATH # Fedora/RHEL
sudo dnf install wine
which wine64
``` ```
Ask your LLM platform to install Wine if it's missing.
## terminal64.exe Missing ## terminal64.exe Missing
MT5 unpacks `terminal64.exe` only after first launch. MT5 unpacks `terminal64.exe` only after first launch.
docs/VSCODE.md
-147
View File
@@ -1,147 +0,0 @@
# VS Code MCP Integration Setup
## Quick Setup
### Option 1: Download Prebuilt Binary (Recommended)
```bash
# macOS (Apple Silicon)
curl -L -o mt5.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mcp-mt5-quant-macos-arm64.tar.gz
tar -xzf mt5.tar.gz
# Linux (x64)
curl -L -o mt5.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mcp-mt5-quant-linux-x64.tar.gz
tar -xzf mt5.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: `/path/to/mt5-quant/mcp-server/bin/mt5-quant`
### Method 2: Edit mcp.json Directly
Add to `.vscode/mcp.json` in your workspace:
```json
{
"servers": {
"mt5-quant": {
"command": "/path/to/mt5-quant/mcp-server/bin/mt5-quant"
}
}
}
```
Create the file:
```bash
mkdir -p .vscode
cat > .vscode/mcp.json << 'EOF'
{
"servers": {
"mt5-quant": {
"command": "/path/to/mt5-quant/mcp-server/bin/mt5-quant"
}
}
}
EOF
```
### Method 3: VS Code CLI
```bash
code --add-mcp '{"name":"mt5-quant","command":"/path/to/mt5-quant/mcp-server/bin/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/mcp-server/bin/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)
docs/WINDSURF.md
-108
View File
@@ -1,108 +0,0 @@
# Windsurf MCP Integration Setup
## Quick Setup
### Option 1: Download Prebuilt Binary (Recommended)
```bash
# macOS (Apple Silicon)
curl -L -o mt5.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mcp-mt5-quant-macos-arm64.tar.gz
tar -xzf mt5.tar.gz
# Linux (x64)
curl -L -o mt5.tar.gz https://github.com/masdevid/mt5-quant/releases/latest/download/mcp-mt5-quant-linux-x64.tar.gz
tar -xzf mt5.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": "/path/to/mt5-quant/mcp-server/bin/mt5-quant"
}
}
}
```
Or use the automated setup:
```bash
# Install binary to standard location
cp mcp-server/bin/mt5-quant ~/.local/bin/
# Then configure
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: `./mcp-server/bin/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
```