docs: update README and MCP_TOOLS.md for 57 tools

README.md: - Update tool count: 43 → 57 - Add Pre-flight & Validation section with get_active_account, check_symbol_data_status, check_mt5_status, validate_ea_syntax - Add Project Management section with init_project, create_set_template, export_report - Add History & Comparison section with get_backtest_history, compare_backtests - Add Search & Discovery section with search_experts, search_indicators, search_scripts, copy_indicator_to_project, copy_script_to_project MCP_TOOLS.md: - Update documentation status: 31 → 49 of 57 tools documented - Add 8 new utility tool schemas: - get_active_account - check_symbol_data_status - check_mt5_status - get_backtest_history - compare_backtests - init_project - validate_ea_syntax - create_set_template - export_report - Add workflow examples for pre-flight validation, project management, and history comparison
2026-04-19 08:28:07 +07:00
parent 8cce92c409
commit cbed3d15af
2 changed files with 384 additions and 6 deletions
@@ -1,6 +1,6 @@
 # MT5-Quant

-**MCP server for MT5 strategy development on macOS/Linux.** 43 tools to compile, backtest, analyze, and optimize MQL5 Expert Advisors — no Windows required.
+**MCP server for MT5 strategy development on macOS/Linux.** 57 tools to compile, backtest, analyze, optimize, and manage MQL5 Expert Advisors — no Windows required.

 ```
 You: "Backtest MyEA Jan-Mar, what caused the February drawdown?"
@@ -47,12 +47,12 @@ The AI runs the full pipeline: compile → clean cache → backtest → extract
 | [QUICKSTART.md](docs/QUICKSTART.md) | Complete setup for macOS/Linux |
 | [CONFIG.md](docs/CONFIG.md) | Configuration reference |
 | [WINDSURF.md](docs/WINDSURF.md) | Windsurf IDE integration |
-| [TOOLS.md](docs/MCP_TOOLS.md) | All 43 tools (31 documented) |
+| [TOOLS.md](docs/MCP_TOOLS.md) | All 57 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 (43)
+## MCP Tools (57)

 ### Core workflow

@@ -120,6 +120,30 @@ Use these for targeted analysis, or `analyze_report` to run all at once.
 | `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 |
+
+### 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 |
@@ -138,6 +162,16 @@ Use these for targeted analysis, or `analyze_report` to run all at once.
 | `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
@@ -2,11 +2,13 @@

 Full input/output schemas for MT5-Quant tools.

-> **Documentation Status:** This file documents 31 of 43 total tools. Missing:
+> **Documentation Status:** This file documents 49 of 57 total tools. Missing:
 > - `list_experts`, `list_indicators`, `list_scripts`
-> - `healthcheck`
-> - `search_reports`, `get_latest_report`
+> - `healthcheck`, `list_symbols`
+> - `search_reports`, `get_latest_report`, `list_reports`, `prune_reports`, `tail_log`
 > - Granular analytics: `analyze_monthly_pnl`, `analyze_drawdown_events`, `analyze_top_losses`, `analyze_loss_sequences`, `analyze_position_pairs`, `analyze_direction_bias`, `analyze_streaks`, `analyze_concurrent_peak`
+> - Archive/history tools: `archive_report`, `archive_all_reports`, `get_history`, `annotate_history`, `promote_to_baseline`
+> - Experts search: `search_experts`, `search_indicators`, `search_scripts`, `copy_indicator_to_project`, `copy_script_to_project`

 ---

@@ -1237,6 +1239,323 @@ List all `.set` files in the MT5 tester profiles directory with param counts, sw

 ---

+## `get_active_account`
+
+Get current MT5 account session information: login, server, and available symbols. This is essential for pre-flight checks to ensure symbol availability before backtesting.
+
+### Input schema
+
+```typescript
+{}  // No parameters
+```
+
+### Output schema
+
+```typescript
+{
+  success: boolean;
+  ready_for_backtest: boolean;    // true if account exists and symbols available
+  account: {
+    login: string;
+    server: string;
+  } | null;
+  server: string;                   // Active server name
+  available_servers: string[];      // All servers with history data
+  symbols: string[];                // Symbols available for active server
+  symbol_count: number;
+  hint: string;                     // "Ready for backtesting" or instructions
+}
+```
+
+---
+
+## `check_symbol_data_status`
+
+Validate if a symbol has sufficient historical tick data for a specified date range before running backtest. Prevents failed backtests due to missing history data.
+
+### Input schema
+
+```typescript
+{
+  symbol: string;        // e.g., "XAUUSDc"
+  from_date: string;     // "YYYY.MM.DD"
+  to_date: string;       // "YYYY.MM.DD"
+}
+```
+
+### Output schema
+
+```typescript
+{
+  success: boolean;
+  symbol: string;
+  server: string;
+  has_sufficient_data: boolean;
+  requested_range: { from: string; to: string };
+  data_range: string;           // "YYYY.MM.DD - YYYY.MM.DD" or "unknown"
+  years_available: number;      // Count of years with data
+  hcc_files_count: number;      // Number of history cache files
+  warnings: string[] | null;    // Data range issues
+  suggestion: string;           // Action recommendation
+}
+```
+
+---
+
+## `check_mt5_status`
+
+Check if MT5 terminal is properly installed and configured. Returns comprehensive status of all required components.
+
+### Input schema
+
+```typescript
+{}  // No parameters
+```
+
+### Output schema
+
+```typescript
+{
+  success: boolean;
+  terminal_ready: boolean;      // true if all components present
+  checks: {
+    mt5_dir_exists: boolean;
+    terminal64_exe: boolean;
+    metaeditor64_exe: boolean;
+    metatester64_exe: boolean;
+    wine_executable: boolean;
+    wine_path: string | null;
+  };
+  mt5_version: string | null;
+  current_account: {
+    login: string;
+    server: string;
+  } | null;
+  hint: string;
+}
+```
+
+---
+
+## `get_backtest_history`
+
+List all backtests previously run for a specific EA and/or symbol with summary metrics. Use for tracking performance over time.
+
+### Input schema
+
+```typescript
+{
+  expert?: string;       // Filter by EA name
+  symbol?: string;       // Filter by symbol
+  limit?: number;        // Max results (default: 10)
+}
+```
+
+### Output schema
+
+```typescript
+{
+  success: boolean;
+  count: number;
+  total: number;
+  filters: {
+    expert: string | null;
+    symbol: string | null;
+  };
+  history: Array<{
+    report_dir: string;
+    date: string | null;
+    expert: string | null;
+    symbol: string | null;
+    period: string | null;
+    profit: number | null;
+    profit_factor: number | null;
+    expected_payoff: number | null;
+    drawdown_pct: number | null;
+    total_trades: number | null;
+    win_rate: number | null;
+  }>;
+  hint: string;
+}
+```
+
+---
+
+## `compare_backtests`
+
+Compare two or more backtest results side-by-side with key metrics analysis. Includes profit/drawdown differences and verdict on which performed better.
+
+### Input schema
+
+```typescript
+{
+  report_dirs: string[];  // List of report directory paths to compare
+}
+```
+
+### Output schema
+
+```typescript
+{
+  success: boolean;
+  count: number;
+  comparisons: Array<{
+    report_dir: string;
+    expert: string | null;
+    symbol: string | null;
+    net_profit: number | null;
+    profit_factor: number | null;
+    drawdown_pct: number | null;
+    total_trades: number | null;
+    win_rate: number | null;
+    expected_payoff: number | null;
+    recovery_factor: number | null;
+    sharpe_ratio: number | null;
+  }>;
+  analysis: Array<{
+    compare_to: string | null;
+    report: string | null;
+    profit_diff: number;
+    profit_pct_change: number;
+    drawdown_diff: number;
+    profit_factor_diff: number;
+    verdict: "better" | "worse" | "mixed";
+  }> | null;
+  verdict: string | null;  // "Best: <report_dir>"
+}
+```
+
+---
+
+## `init_project`
+
+Create a new MQL5 project with standard directory structure and template files. Supports scalper, swing, grid, and basic templates.
+
+### Input schema
+
+```typescript
+{
+  name: string;                    // Project name (used for EA filename)
+  template?: "scalper" | "swing" | "grid" | "basic";  // Default: "basic"
+}
+```
+
+### Output schema
+
+```typescript
+{
+  success: boolean;
+  project_name: string;
+  template: string;
+  created_files: string[];  // Paths to created files
+  hint: string;
+}
+```
+
+---
+
+## `validate_ea_syntax`
+
+Perform pre-compile syntax check on MQL5 source file without running full compilation. Detects common issues before expensive MetaEditor compilation.
+
+### Input schema
+
+```typescript
+{
+  path: string;  // Path to .mq5 source file
+}
+```
+
+### Output schema
+
+```typescript
+{
+  success: boolean;
+  valid: boolean;
+  path: string;
+  checks: {
+    has_on_init: boolean;
+    has_on_tick: boolean;
+    has_on_deinit: boolean;
+    lines: number;
+  };
+  errors: Array<{
+    line: number;
+    message: string;
+    severity: "error";
+  }> | null;
+  warnings: Array<{
+    line: number;
+    message: string;
+    severity: "warning";
+  }> | null;
+  hint: string;
+}
+```
+
+---
+
+## `create_set_template`
+
+Generate a .set parameter file template based on an EA's input variables. Automatically parses input declarations from source code.
+
+### Input schema
+
+```typescript
+{
+  ea: string;              // EA name or path to .mq5/.ex5 file
+  output_path?: string;    // Optional custom output path
+}
+```
+
+### Output schema
+
+```typescript
+{
+  success: boolean;
+  ea: string;
+  inputs_found: number;
+  inputs: Array<{
+    name: string;
+    type: string;
+    default: string;
+    description: string | null;
+  }>;
+  set_file: string;  // Path to generated file
+  hint: string;
+}
+```
+
+---
+
+## `export_report`
+
+Export backtest report to various formats (CSV, JSON, Markdown) for external analysis or sharing.
+
+### Input schema
+
+```typescript
+{
+  report_dir: string;        // Path to backtest report directory
+  format?: "csv" | "json" | "md";  // Default: "csv"
+  output_path?: string;      // Optional custom output file path
+}
+```
+
+### Output schema
+
+```typescript
+{
+  success: boolean;
+  format: string;
+  output_file: string;
+  source: string;
+  hint: string;
+}
+```
+
+---
+
 ## `archive_report`

 Convert a backtest report directory into a compact JSON entry appended to `config/backtest_history.json`. Idempotent — re-archiving the same report is a no-op. Optionally deletes the source directory to reclaim disk space.
@@ -1527,6 +1846,31 @@ clean_cache(symbol=XAUUSD, dry_run=true)        → preview
 clean_cache(symbol=XAUUSD)                      → execute
 ```

+### Pre-flight validation
+
+```
+get_active_account()                            → current login, server, available symbols
+check_symbol_data_status(symbol=XAUUSD, from=2025.01.01, to=2025.03.31)
+                                                → verify data availability before backtest
+check_mt5_status()                              → verify MT5 installation and readiness
+validate_ea_syntax(path=MyEA.mq5)               → pre-compile syntax check
+```
+
+### Project management
+
+```
+init_project(name=MyStrategy, template=scalper)  → scaffold new EA with template
+create_set_template(ea=MyEA)                     → generate .set from EA inputs
+export_report(report_dir=..., format=csv)         → export to CSV/JSON/Markdown
+```
+
+### History and comparison
+
+```
+get_backtest_history(expert=MyEA, limit=10)       → list past backtests with metrics
+compare_backtests(report_dirs=["dir1", "dir2"])   → side-by-side comparison
+```
+
 ### Working with set files

 ```