phuicmt/mcp-mt5

1. What the repository is

- This is a Python MCP server that acts as an automation layer for MetaTrader 4/5 development and testing, not live trading.

- Its main job is to let an LLM-driven client drive the MetaTrader toolchain through MCP calls: compile source, deploy binaries, run Strategy Tester, read logs/reports, and refactor source trees.

2. Top-level architecture

- The system is centered on a server process in src/mcp_mt5/server.py.

- Around it are focused domain modules for path/environment discovery, parsing MetaTrader outputs, analysis/linting, formatting/refactoring, and tester/report handling.

- The server is effectively a coordinator that turns MCP tool calls into local filesystem operations and command-line invocations of MetaTrader binaries.

3. External runtime boundary

- The repo depends on an installed MetaTrader terminal on Windows.

- It talks to external executables such as MetaEditor and the terminal binary (metaeditor64.exe / terminal64.exe for MT5, analogous MT4 binaries when edition is switched).

- Inputs and outputs live in the MetaTrader data tree: MQL4/ or MQL5/, Experts/, Include/, Files/, Logs/, Strategy Tester reports, and tester.ini.

4. Configuration and terminal discovery

- src/mcp_mt5/paths.py is the boundary for discovering the correct MetaTrader install and data directory.

- The repo supports multiple resolution modes: explicit environment variables, scanning %APPDATA%\MetaQuotes\Terminal\*\origin.txt, or a portable-layout fallback.

- The server can also enumerate and switch between terminal instances, which matters when multiple MT installations or broker folders exist.

5. Server/tooling layer

- server.py exposes the MCP surface: tools and read-only resources.

- The README indicates three resource streams (mt5://livelog, mt5://journal, mt5://tester-log) and a broad tool set covering discovery, build/deploy, analysis, lint, formatting, refactoring, strategy testing, logs, and snapshots.

- This is the primary integration boundary for clients such as Claude Desktop or other MCP consumers.

6. Build, deploy, and smoke-test flow

- The build pipeline wraps MetaEditor to compile MQL sources and capture structured diagnostics.

- Deploy-related actions copy generated .ex4/.ex5 binaries into the terminal’s Experts/ directory, optionally renaming or installing includes into Include/.

- smoke.py represents the “compile + deploy + headless backtest + journal scan” path, which is the repo’s closest thing to an end-to-end validation loop.

7. Strategy Tester and report processing

- run_backtest launches the terminal with a tester.ini, then the server reads the resulting tester logs and HTML report.

- parsers.py and reports.py handle best-effort parsing of MetaTrader outputs into structured summaries like profit, drawdown, trade counts, and diagnostic excerpts.

- optimization.py and snapshot.py support the artifacts around testing and iterative strategy work, including optimization-pass handling and frozen source snapshots.

8. Source analysis and code intelligence

- analysis.py, parsers.py, and related modules implement MQL-specific inspection tasks: extracting input declarations, resolving #include graphs, finding symbols, computing code metrics, extracting MetaEditor doc blocks, and detecting magic-number collisions.

- lint.py adds structural validation such as missing lifecycle handlers, deprecated MT4-style APIs, unused inputs, and other source hygiene checks.

- These modules do not execute MQL; they statically analyze the source tree to help the LLM reason about strategy code.

9. Formatting and refactoring subsystem

- formatting.py wraps formatting behavior, relying on C++-style formatting conventions that are compatible enough for MQL source.

- refactor.py and ast_refactor.py provide rename/extract operations over MQL files, with the implementation favoring repository-wide textual and brace-aware transformations rather than a true language server.

- This is important architecturally because the repo treats the source tree as editable code, not just a build artifact.

10. Logs, snapshots, and reproducibility

- tail_log and related log helpers expose the live log streams as readable artifacts.

- snapshot.py freezes a copy of source files plus a manifest, which supports reproducible investigation across iterations.

- These features make the server useful as an iterative dev harness: the agent can inspect state, change code, run tests, and compare artifacts over time.

11. Testing and quality gates

- The tests/ directory contains a focused pytest suite that validates parsing, path resolution, server tools, lint behavior, and other logic without requiring a live MetaTrader installation.

- This implies a strong separation between pure-Python logic and external-terminal integration, which is a key architectural boundary.

- The CI workflow runs on Windows, matching the runtime dependency on MetaTrader binaries.

12. Packaging and delivery

- pyproject.toml defines the Python package and dev/test tooling.

- .github/workflows/ci.yml and release.yml handle validation and publishing, with release automation targeting PyPI.

- The repo is therefore a conventional Python distribution, but its functional architecture is dominated by the local MetaTrader toolchain and file-based orchestration rather than network services.