# phuicmt/mcp-mt5 architecture

> Architecture diagram of the GitHub repository phuicmt/mcp-mt5, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phuicmt/mcp-mt5
- Repository: https://github.com/phuicmt/mcp-mt5

## Overview

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.

Main entry points: [`src/mcp_mt5/server.py`](https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/server.py) (Server), [`tests`](https://github.com/phuicmt/mcp-mt5/tree/main/tests) (Tests), [`src/mcp_mt5/parsers.py`](https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/parsers.py) (Parsers), [`src/mcp_mt5/analysis.py`](https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/analysis.py) (Analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_core["Core runtime"]
  node_n_server["Server<br/>mcp coordinator<br/>[server.py]"]
  node_n_paths["Paths<br/>env discovery<br/>[paths.py]"]
  node_n_analysis["Analysis<br/>static mql<br/>[analysis.py]"]
  node_n_parsers["Parsers<br/>output parser<br/>[parsers.py]"]
  node_n_reports["Reports<br/>tester summary<br/>[reports.py]"]
  node_n_lint["Lint<br/>source checks<br/>[lint.py]"]
  node_n_formatting["Formatting<br/>code format<br/>[formatting.py]"]
  node_n_refactor["Refactor<br/>text transform<br/>[refactor.py]"]
  node_n_astrefactor["AST refactor<br/>brace-aware edit<br/>[ast_refactor.py]"]
  node_n_optimization["Optimization<br/>tester passes<br/>[optimization.py]"]
  node_n_snapshot["Snapshot<br/>reproducibility<br/>[snapshot.py]"]
  node_n_smoke["Smoke<br/>e2e check<br/>[smoke.py]"]
end

subgraph group_grp_quality["Quality gate"]
  node_n_tests["Tests<br/>pytest suite"]
end

subgraph group_grp_delivery["Packaging"]
  node_n_examples["Examples<br/>config samples"]
  node_n_pyproject["Pyproject<br/>package config<br/>[pyproject.toml]"]
  node_n_ci["CI<br/>workflow<br/>[ci.yml]"]
  node_n_release["Release<br/>publish workflow<br/>[release.yml]"]
end

node_n_terminal[("MetaTrader<br/>external runtime")]

node_n_server -->|"discovers"| node_n_paths
node_n_server -->|"inspects"| node_n_analysis
node_n_server -->|"parses"| node_n_parsers
node_n_server -->|"summarizes"| node_n_reports
node_n_server -->|"checks"| node_n_lint
node_n_server -->|"formats"| node_n_formatting
node_n_server -->|"edits"| node_n_refactor
node_n_server -->|"structural edit"| node_n_astrefactor
node_n_server -->|"tracks"| node_n_optimization
node_n_server -->|"freezes"| node_n_snapshot
node_n_server -->|"validates"| node_n_smoke
node_n_server -->|"invokes"| node_n_terminal
node_n_parsers -->|"feeds"| node_n_reports
node_n_analysis -->|"depends on"| node_n_parsers
node_n_lint -->|"builds on"| node_n_analysis
node_n_refactor -->|"uses"| node_n_astrefactor
node_n_smoke -->|"executes"| node_n_terminal
node_n_examples -->|"configures"| node_n_server
node_n_pyproject -->|"packages"| node_n_tests
node_n_ci -->|"runs"| node_n_tests
node_n_release -->|"publishes"| node_n_pyproject
node_n_tests -->|"covers"| node_n_paths
node_n_tests -->|"covers"| node_n_parsers
node_n_tests -->|"covers"| node_n_server

click node_n_server "https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/server.py"
click node_n_paths "https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/paths.py"
click node_n_analysis "https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/analysis.py"
click node_n_parsers "https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/parsers.py"
click node_n_reports "https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/reports.py"
click node_n_lint "https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/lint.py"
click node_n_formatting "https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/formatting.py"
click node_n_refactor "https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/refactor.py"
click node_n_astrefactor "https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/ast_refactor.py"
click node_n_optimization "https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/optimization.py"
click node_n_snapshot "https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/snapshot.py"
click node_n_smoke "https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/smoke.py"
click node_n_examples "https://github.com/phuicmt/mcp-mt5/tree/main/examples"
click node_n_pyproject "https://github.com/phuicmt/mcp-mt5/blob/main/pyproject.toml"
click node_n_ci "https://github.com/phuicmt/mcp-mt5/blob/main/.github/workflows/ci.yml"
click node_n_release "https://github.com/phuicmt/mcp-mt5/blob/main/.github/workflows/release.yml"
click node_n_tests "https://github.com/phuicmt/mcp-mt5/tree/main/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_server,node_n_paths,node_n_analysis,node_n_parsers,node_n_reports,node_n_lint,node_n_formatting,node_n_refactor,node_n_astrefactor,node_n_optimization,node_n_snapshot,node_n_smoke toneBlue
class node_n_tests toneAmber
class node_n_examples,node_n_pyproject,node_n_ci,node_n_release toneMint
class node_n_terminal toneNeutral
```

## Components

### Core runtime

MCP server, MetaTrader integration, and source-manipulation modules.

- [Server](https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/server.py): mcp coordinator · Exposes MCP tools and resources, and orchestrates MetaTrader-facing operations. · `src/mcp_mt5/server.py`
- [Paths](https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/paths.py): env discovery · Finds terminal installs, data folders, and selectable MetaTrader instances. · `src/mcp_mt5/paths.py`
- [Analysis](https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/analysis.py): static mql · Extracts symbols, inputs, includes, metrics, and source structure for reasoning. · `src/mcp_mt5/analysis.py`
- [Parsers](https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/parsers.py): output parser · Parses MetaTrader logs, diagnostics, and other emitted text artifacts. · `src/mcp_mt5/parsers.py`
- [Reports](https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/reports.py): tester summary · Converts Strategy Tester outputs into structured result summaries. · `src/mcp_mt5/reports.py`
- [Lint](https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/lint.py): source checks · Validates MQL structure, lifecycle handlers, API usage, and hygiene issues. · `src/mcp_mt5/lint.py`
- [Formatting](https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/formatting.py): code format · Applies repository-level formatting conventions compatible with MQL source. · `src/mcp_mt5/formatting.py`
- [Refactor](https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/refactor.py): text transform · Performs rename and extract-style source edits across MQL files. · `src/mcp_mt5/refactor.py`
- [AST refactor](https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/ast_refactor.py): brace-aware edit · Supports structured refactoring operations beyond simple textual replacement. · `src/mcp_mt5/ast_refactor.py`
- [Optimization](https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/optimization.py): tester passes · Handles optimization-oriented testing artifacts and pass iteration. · `src/mcp_mt5/optimization.py`
- [Snapshot](https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/snapshot.py): reproducibility · Freezes source trees and manifests for later comparison and investigation. · `src/mcp_mt5/snapshot.py`
- [Smoke](https://github.com/phuicmt/mcp-mt5/blob/main/src/mcp_mt5/smoke.py): e2e check · Runs compile, deploy, headless backtest, and journal scanning as a validation loop. · `src/mcp_mt5/smoke.py`

### Quality gate

Pure-Python tests that validate parsing, paths, tools, and analysis logic.

- [Tests](https://github.com/phuicmt/mcp-mt5/tree/main/tests): pytest suite · Validates parsing, path discovery, server tools, linting, and other pure-Python logic. · `tests`

### Packaging

Build, release, and example artifacts for local setup and publishing.

- [Examples](https://github.com/phuicmt/mcp-mt5/tree/main/examples): config samples · Provides sample MCP client configuration and Strategy Tester input files. · `examples`
- [Pyproject](https://github.com/phuicmt/mcp-mt5/blob/main/pyproject.toml): package config · Defines the Python package metadata and tooling configuration. · `pyproject.toml`
- [CI](https://github.com/phuicmt/mcp-mt5/blob/main/.github/workflows/ci.yml): workflow · Runs Windows-based validation aligned with the MetaTrader runtime dependency. · `.github/workflows/ci.yml`
- [Release](https://github.com/phuicmt/mcp-mt5/blob/main/.github/workflows/release.yml): publish workflow · Automates release and distribution publishing. · `.github/workflows/release.yml`

### Other components

- **MetaTrader**: external runtime · Installed Windows terminal and MetaEditor binaries used for compile and backtest execution.

## Connections

- Server → Paths: discovers · Resolves installed terminals and data directories.
- Server → Analysis: inspects · Uses source analysis to answer MCP requests.
- Server → Parsers: parses · Turns terminal output into structured diagnostics.
- Server → Reports: summarizes · Reads tester artifacts into run summaries.
- Server → Lint: checks · Runs source hygiene and compatibility checks.
- Server → Formatting: formats · Applies code formatting to source files.
- Server → Refactor: edits · Performs repository-wide refactor operations.
- Server → AST refactor: structural edit · Uses brace-aware transformations for safer refactors.
- Server → Optimization: tracks · Handles optimization pass artifacts and flow.
- Server → Snapshot: freezes · Creates reproducible source snapshots.
- Server → Smoke: validates · Runs the end-to-end compile/deploy/test loop.
- Server → MetaTrader: invokes · Calls MetaEditor and terminal binaries on Windows.
- Parsers → Reports: feeds · Parsed logs and HTML artifacts inform summaries.
- Analysis → Parsers: depends on · Reuses parsing helpers for source inspection.
- Lint → Analysis: builds on · Lint rules operate over static source facts.
- Refactor → AST refactor: uses · Refactoring helpers rely on structured edit support.
- Smoke → MetaTrader: executes · Launches compile and backtest runs through the installed runtime.
- Examples → Server: configures · Sample client and tester files support server usage.
- Pyproject → Tests: packages · Defines test and packaging setup for the Python distribution.
- CI → Tests: runs · Validates the repository in automation.
- Release → Pyproject: publishes · Uses package metadata and release automation.
- Tests → Paths: covers · Exercises path discovery without needing a live terminal.
- Tests → Parsers: covers · Validates parsing behavior with fixtures.
- Tests → Server: covers · Checks exposed tools and server behavior.