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
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
## Config File Location
## Config File
```
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
```
Override with env: `export MT5_MCP_HOME=/path/to/config`
## Full Config Example
## Full Example
```yaml
# Required: Wine executable path
@@ -52,53 +49,9 @@ optimization:
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:
`setup.sh` detects:
- Wine executable (MetaTrader 5.app, CrossOver, or system Wine)
- MT5 terminal directory
- 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
## 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
# 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
Ask your LLM platform to install MT5-Quant:
# 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
```
> "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."
### 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
git clone https://github.com/masdevid/mt5-quant
cd mt5-quant
bash scripts/build-rust.sh
```
## Minimal Config
## 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
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"
wine_executable: "/path/to/wine64"
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
```
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 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
The AI runs: compile → clean → backtest → extract → analyze.
---
**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)**
- 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)
- Port 3000 open in macOS firewall (or whichever port MT5 uses)
**Linux server (agents)**
- Wine 7.0+ (or Wine Staging for better compatibility)
- Wine 7.0+
- `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
@@ -31,7 +29,6 @@ ls ~/Library/Application\ Support/MetaQuotes/*/drive_c/Program\ Files/MetaTrader
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)
```
@@ -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).
---
## 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
## Step 2: 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"
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}/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
## Step 3: 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 \
@@ -110,9 +61,7 @@ nohup wine64 metatester64.exe /server:192.168.1.100:3000 /agents:8 \
disown
```
---
## Step 6: Verify agents appear in MT5
## Step 4: Verify agents appear in MT5
On your Mac, open MT5:
**View → Strategy Tester → Agents tab**
@@ -120,68 +69,38 @@ On your Mac, open MT5:
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 5: Configure MT5-Quant for remote agents
---
## Step 7: Configure MT5-Quant for remote agents
In `config/MT5-Quant.yaml`:
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
check_agent_count: true
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
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:
On first run, MT5 automatically downloads ticks from the broker. Pre-populate on Linux:
```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/
# Copy to Linux
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.
- Use wired connection. WiFi or WAN: significant overhead.
docs/TROUBLESHOOTING.md
+8 -3
View File
@@ -17,12 +17,17 @@ If using CrossOver, confirm bottle is named `MetaTrader5`.
### Linux
Install Wine 7.0+ and confirm on PATH:
```bash
sudo apt install wine64 # Debian/Ubuntu
sudo dnf install wine # Fedora/RHEL
which wine64 # confirm on PATH
# Debian/Ubuntu
sudo apt install wine64
# Fedora/RHEL
sudo dnf install wine
which wine64
```
Ask your LLM platform to install Wine if it's missing.
## terminal64.exe Missing
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
```