mcp-mt5 0.3.0__tar.gz

mcp_mt5-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: windows-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src tests
+
+      - name: Test
+        run: pytest -v --cov=mcp_mt5 --cov-report=term-missing

mcp_mt5-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,96 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.meta.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel + sdist
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Capture version
+        id: meta
+        run: echo "version=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Generate release notes
+        id: notes
+        run: |
+          version="${GITHUB_REF#refs/tags/v}"
+          notes_file=$(mktemp)
+          if [ -f CHANGELOG.md ]; then
+            awk -v ver="$version" '
+              /^## / {
+                if (capture) exit
+                if ($0 ~ ver) { capture = 1; next }
+              }
+              capture { print }
+            ' CHANGELOG.md > "$notes_file"
+          fi
+          if [ ! -s "$notes_file" ]; then
+            echo "Release $version" > "$notes_file"
+          fi
+          {
+            echo 'body<<EOF'
+            cat "$notes_file"
+            echo 'EOF'
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: ${{ needs.build.outputs.version }}
+          body: ${{ steps.notes.outputs.body }}
+          files: dist/*
+          generate_release_notes: true
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    continue-on-error: true
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mcp_mt5-0.3.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+.env
+.idea/
+.vscode/
+*.log
+*.ex5
+*.ex4

mcp_mt5-0.3.0/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## 0.3.0 — 2026-05-04
+
+Full dev-loop expansion: 18 new tools across 7 modules.
+
+### Source analysis
+- `extract_inputs` — parse `input <type> <name> = <default>;` declarations into JSON
+- `gen_tester_inputs` — auto-build a `[TesterInputs]` block from EA source (translates `PERIOD_*` enums to numeric codes)
+- `resolve_includes` — recursive `#include` resolution, reports missing files
+- `find_symbol` — grep MQL files skipping comments and string literals
+- `code_metrics` — LOC, function count, max nesting per file or aggregated across a tree
+- `extract_doc` — pull MetaEditor `//+--+ //| ... +--+` doc blocks into markdown
+- `find_magic_collision` — detect duplicate magic-number assignments
+
+### Lint / validation
+- `syntax_check` — MetaEditor `/s` syntax-only mode for fast feedback
+- `lint_basic` — structural rules (missing `OnInit`/`OnDeinit`, unused inputs, hardcoded magic, hardcoded symbol)
+- `check_deprecated` — flag MT4-style API calls (`OrderSend`, `Ask`, `AccountBalance`, …) with CTrade-style replacements
+- `validate_tester_ini` — required keys, date format, numeric sanity, cross-check inputs vs EA source
+
+### Formatting
+- `format_mql` / `format_check` — clang-format wrap (treats MQL as C++ with an MQL-friendly default style)
+
+### Refactor
+- `rename_symbol` — whole-word rename across the project, with `dry_run` preview
+
+### Optimization
+- `parse_optimization` — best-effort `.opt` binary reader
+- `top_passes` — sort optimization passes by criterion
+
+### Reports
+- `compare_reports` — diff two tester reports key-by-key with absolute and percent deltas
+- `regression_check` — guard thresholds (e.g. "net_profit may not drop more than 5%") with violation reporting
+
+### Snapshots
+- `snapshot_sources` — freeze a copy of source files into a timestamped manifest folder
+- `list_snapshots` — enumerate previously captured snapshots
+
+### Internal
+- New modules: `analysis.py`, `lint.py`, `formatting.py`, `refactor.py`, `optimization.py`, `reports.py`, `snapshot.py`
+- Test suite expanded from 18 → 38 cases
+
+## 0.2.0 — 2026-05-04
+
+- Refactor into `paths.py` (layout detection) + `parsers.py` (compile log + tester report) + `server.py` (MCP tools)
+- Auto-detect terminal data folder via `origin.txt` scan
+- MT4 support (`MT5_EDITION=mt4`, `metaeditor.exe`, `MQL4/` tree)
+- Structured tester report parser (summary key/values + trade row detection)
+- New tools: `list_terminals`, `kill_terminal`, `compile_and_deploy`, `patch_tester_ini`, `install_include`
+- Pytest test suite (18 tests covering parsers, paths, server tools)
+- GitHub Actions CI + PyPI release workflow
+
+## 0.1.0
+
+- Initial release: `compile`, `run_backtest`, `tail_log`, `deploy_ea`, `list_experts`, `read_tester_report`, `env_info`

mcp_mt5-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PHUICMT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_mt5-0.3.0/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: mcp-mt5
+Version: 0.3.0
+Summary: MCP server for MetaTrader 4/5 build pipeline — compile, deploy, backtest, parse reports
+Project-URL: Homepage, https://github.com/PHUICMT/mcp-mt5
+Project-URL: Issues, https://github.com/PHUICMT/mcp-mt5/issues
+Author-email: PHUICMT <icmtchannel@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: mcp,metatrader,model-context-protocol,mql4,mql5,mt4,mt5,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.2.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcp-mt5
+
+> **Model Context Protocol server for the MetaTrader 4/5 build pipeline.**
+> Compile MQL sources, deploy compiled EAs, run Strategy Tester, parse reports, tail logs — all driven by an LLM agent without touching the MetaTrader UI.
+
+[![CI](https://github.com/PHUICMT/mcp-mt5/actions/workflows/ci.yml/badge.svg)](https://github.com/PHUICMT/mcp-mt5/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-Windows-lightgrey)](https://www.metaquotes.net/)
+
+---
+
+## What this is — and what it isn't
+
+| ✅ This server | ❌ Not this server |
+|----------------|--------------------|
+| MetaTrader **dev harness** — compile, deploy, backtest, parse | Live trading (orders, positions, quotes) |
+| Wraps `MetaEditor64.exe` / `terminal64.exe` CLI directly | Wraps the `MetaTrader5` Python package |
+| Runs entirely offline against installed terminal | Connects to a broker server |
+| Iterates strategies *before* they go live | Executes strategies in production |
+
+> **Use case:** an LLM agent edits `.mq5` source → compiles → deploys → runs Strategy Tester → reads report → adjusts → repeats. No broker login, no human in the loop, no risk of real-money execution.
+
+For runtime trading, pair this with a live-trading MCP — they target different layers and compose well.
+
+---
+
+## Tools
+
+The server exposes 29 tools across eight categories.
+
+### 🔍 Discovery
+
+| Tool | Description |
+|------|-------------|
+| `env_info` | Dump resolved paths, terminal hash, edition, and missing-component issues |
+| `list_terminals` | Enumerate every MT4/5 terminal data folder under `%APPDATA%\MetaQuotes\Terminal` along with each `origin.txt` install path |
+
+### 🔨 Build & deploy
+
+| Tool | Description |
+|------|-------------|
+| `compile` | Invoke MetaEditor CLI on a `.mq4`/`.mq5`/`.mqh` source. Returns structured `errors[]`/`warnings[]` (file, line, column, error code, message) plus log excerpt |
+| `compile_and_deploy` | Compile, then copy the resulting `.ex4`/`.ex5` into the terminal's `Experts/` folder in one call |
+| `syntax_check` | Same as `compile` but uses MetaEditor's `/s` syntax-only mode for faster feedback |
+| `deploy_ea` | Copy a compiled binary into `Experts/` (with optional rename) |
+| `install_include` | Copy a `.mqh` header into the terminal `Include/` folder — handy for libraries like `LiveLog.mqh` |
+| `list_experts` | Enumerate `Experts/` recursively with size and modification time |
+
+### 🔎 Source analysis
+
+| Tool | Description |
+|------|-------------|
+| `extract_inputs` | Parse `input <type> <name> = <default>;` declarations into structured records |
+| `gen_tester_inputs` | Auto-build a `[TesterInputs]` block from EA source (translates `PERIOD_*` enums to numeric codes), optionally write into an existing `tester.ini` |
+| `resolve_includes` | Recursive `#include` resolution that reports missing files and circular references |
+| `find_symbol` | Grep a symbol across MQL files, skipping comments and string literals |
+| `code_metrics` | LOC, function count, max nesting per file — or aggregated across an entire tree |
+| `extract_doc` | Pull MetaEditor `//+--+ //\| ... +--+` doc blocks out as markdown |
+| `find_magic_collision` | Detect duplicate magic-number assignments across the project |
+
+### ⚠️ Lint & validation
+
+| Tool | Description |
+|------|-------------|
+| `lint_basic` | Structural rules: missing `OnInit`/`OnDeinit`, unused `input`s, hardcoded magic numbers, hardcoded symbol literals |
+| `check_deprecated` | Flag MT4-style API calls (`OrderSend`, `Ask`, `AccountBalance`, …) with `CTrade`/MT5-API replacement suggestions |
+| `validate_tester_ini` | Sanity-check a `tester.ini` (required keys, date format, numeric ranges) and cross-check `[TesterInputs]` against the EA source declarations |
+
+### 🎨 Format
+
+| Tool | Description |
+|------|-------------|
+| `format_mql` | Format a source file via `clang-format` (treats MQL as C++ with an MQL-friendly default style) |
+| `format_check` | Same as above but reports whether changes are needed without writing the file |
+
+### ✏️ Refactor
+
+| Tool | Description |
+|------|-------------|
+| `rename_symbol` | Whole-word rename across all MQL files in a tree, with `dry_run` preview |
+
+### 📊 Strategy Tester
+
+| Tool | Description |
+|------|-------------|
+| `patch_tester_ini` | Programmatically update keys in a `tester.ini` (e.g. `Tester.Symbol`, `Tester.FromDate`, `TesterInputs.RiskPct`) before running |
+| `run_backtest` | Launch `terminal64.exe /config:tester.ini`, optionally headless (when `ShutdownTerminal=1`), and return the latest tester log path |
+| `parse_optimization` | Best-effort parser for the latest `.opt` (optimization passes) binary file |
+| `top_passes` | Sort optimization passes by a chosen criterion and return the top *N* |
+| `read_tester_report` | Locate and parse the latest tester HTML report into a structured `summary` (net profit, profit factor, drawdown, trade counts, etc.) plus a sample of trade rows |
+| `compare_reports` | Diff two tester reports key-by-key with absolute and percent deltas |
+| `regression_check` | Verify a candidate report stays within guard thresholds vs a baseline (e.g. "net_profit may not drop more than 5%") |
+| `kill_terminal` | `taskkill` if the terminal hangs |
+
+### 📝 Logs & snapshots
+
+| Tool | Description |
+|------|-------------|
+| `tail_log` | Tail the last *N* lines of either `Files/LiveLog.txt`, the daily `Logs/YYYYMMDD.log`, or the most recent tester log. Optional structured parse into `{ts, source, message}` records |
+| `snapshot_sources` | Freeze a copy of source files into a timestamped folder with a `manifest.json` |
+| `list_snapshots` | Enumerate previously captured snapshots |
+
+---
+
+## Quick start
+
+### Install
+
+```bash
+pip install mcp-mt5
+```
+
+> Requires Windows + an installed MetaTrader 4 or 5 terminal.
+
+### Register with an MCP client
+
+Most MCP clients accept a JSON entry under `mcpServers`. The server inherits its configuration from environment variables:
+
+```json
+{
+  "mcpServers": {
+    "mt5": {
+      "command": "mcp-mt5",
+      "env": {
+        "MT5_INSTALL": "C:\\Program Files\\MetaTrader 5"
+      }
+    }
+  }
+}
+```
+
+Refer to your client's documentation for the exact config file location.
+
+### Verify the install
+
+Once registered, ask your agent to call `env_info`:
+
+```json
+{
+  "edition": "mt5",
+  "install": "C:\\Program Files\\MetaTrader 5",
+  "terminal_hash": "D0E8209F77C8CF37AD8BF550E51FF075",
+  "metaeditor": "C:\\Program Files\\MetaTrader 5\\MetaEditor64.exe",
+  "experts_dir": "C:\\Users\\...\\MQL5\\Experts",
+  "issues": []
+}
+```
+
+An empty `issues` array means everything is wired up correctly.
+
+---
+
+## Configuration
+
+Resolution priority for the MetaTrader install + data folder:
+
+1. **Explicit env vars** (below)
+2. **Auto-scan** of `%APPDATA%\MetaQuotes\Terminal\*\origin.txt` for a folder whose origin matches `MT5_INSTALL`
+3. **Portable mode** fallback (data colocated with install dir)
+
+| Env var | Default | Notes |
+|---------|---------|-------|
+| `MT5_INSTALL` | `C:\Program Files\MetaTrader 5` | Install dir containing `terminal64.exe` |
+| `MT5_DATA` | _(auto-detected)_ | `%APPDATA%\MetaQuotes\Terminal\<hash>` |
+| `MT5_TERMINAL_HASH` | _(auto-detected)_ | 32-char folder name |
+| `MT5_EDITION` | `mt5` | Set to `mt4` for MetaTrader 4 |
+
+### MT4 support
+
+Set `MT5_EDITION=mt4` and point `MT5_INSTALL` at your MT4 install. The server switches to `metaeditor.exe` (32-bit), `terminal.exe`, and the `MQL4/` data tree automatically.
+
+---
+
+## Example workflow
+
+A typical LLM-driven iteration loop:
+
+```
+1. env_info                                          → verify paths
+2. compile_and_deploy source="MyEA.mq5"              → 0 errors, .ex5 deployed ✅
+3. patch_tester_ini config="tester.ini" updates={
+     "Tester.Symbol": "EURUSD",
+     "Tester.FromDate": "2025.01.01",
+     "TesterInputs.RiskPct": "1.5"
+   }
+4. run_backtest config="tester.ini" wait=true
+5. read_tester_report                                → summary.net_profit = 1234.56
+                                                       summary.profit_factor = 1.45
+6. tail_log mode="tester" lines=200 structured=true  → diagnose journal warnings
+7. <edit Signal.mqh based on findings>
+8. → loop back to step 2
+```
+
+---
+
+## A sample `tester.ini`
+
+```ini
+; Launch: terminal64.exe /config:tester.ini
+; Period codes: M1=1, M5=5, M15=15, H1=16385, H4=16388, D1=16408
+; Model: 0=Every tick, 1=1 min OHLC, 4=Real ticks
+
+[Tester]
+Expert=MyEA
+Symbol=EURUSD
+Period=M15
+Model=1
+FromDate=2024.01.01
+ToDate=2024.12.31
+Deposit=10000
+Currency=USD
+Leverage=500
+Visual=0
+ShutdownTerminal=1     ; required so run_backtest can wait for the run to finish
+Report=tester_report
+
+[TesterInputs]
+; ParamName=value||start||step||stop||(N=fixed|Y=optimize)
+; RiskPct=1.0||0.1||0.1||3.0||N
+```
+
+A more complete sample lives at [`examples/tester.ini`](examples/tester.ini).
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/PHUICMT/mcp-mt5
+cd mcp-mt5
+pip install -e ".[dev]"
+pytest                    # runs the 18-test suite
+ruff check src tests      # lints
+```
+
+CI runs on Windows for Python 3.10, 3.11, and 3.12 against every push to `main`. Tagging a release (e.g. `v0.2.0`) triggers an OIDC publish to PyPI.
+
+### Project layout
+
+```
+mcp-mt5/
+├── src/mcp_mt5/
+│   ├── server.py        # FastMCP tool definitions
+│   ├── paths.py         # Layout detection + origin.txt scan
+│   └── parsers.py       # Compile log + tester HTML report parsers
+├── tests/               # 18 pytest tests, no live MT5 required
+├── examples/            # Sample tester.ini + client config
+└── .github/workflows/   # CI + PyPI release
+```
+
+---
+
+## Limitations
+
+- **Windows-only.** MetaTrader CLI binaries don't ship for Linux/macOS. Wine ports may work but are untested.
+- **No live broker access.** This server intentionally never authenticates to a broker. Use a separate MCP server for runtime trading.
+- **Tester report parsing is best-effort.** MetaTrader's HTML output isn't a stable schema; the raw HTML is also returned alongside the parsed structure so you can fall back to text inspection when needed.
+- **Optimization runs are not parsed yet.** Single-pass backtests are fully supported; `.opt` results are on the roadmap.
+
+---
+
+## Roadmap
+
+- Cross-broker terminal selection helper (`select_terminal` by origin path or hash)
+- Long-running log subscription via MCP resources
+- Smoke-test runner that boots a 1-day Strategy Tester pass and asserts no runtime errors
+- AST-based `extract_function` refactor (currently regex-based rename only)
+
+---
+
+## License
+
+[MIT](LICENSE) © 2026 PHUICMT