Metadata-Version: 2.4
Name: mql-mcp
Version: 1.0.1
Summary: MQL4/MQL5 MCP server - 6 tools for docs lookup, code validation, and code generation
Author: TheFractalyst
License: MIT License
        
        Copyright (c) 2025 TheFractalyst
        
        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.
        
Project-URL: Homepage, https://github.com/TheFractalyst/mql-mcp
Project-URL: Repository, https://github.com/TheFractalyst/mql-mcp
Project-URL: Issues, https://github.com/TheFractalyst/mql-mcp/issues
Keywords: mcp,mql,mql4,mql5,metatrader,expert-advisor,trading
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp<4.0.0,>=3.4.0
Requires-Dist: chromadb<0.6.0,>=0.5.0
Requires-Dist: sentence-transformers<4.0.0,>=3.0.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.0
Requires-Dist: loguru<1.0.0,>=0.7.0
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: rapidfuzz<4.0.0,>=3.0.0
Requires-Dist: xxhash<4.0.0,>=3.0.0
Requires-Dist: starlette<1.0.0,>=0.36.0
Provides-Extra: pipeline
Requires-Dist: playwright>=1.40.0; extra == "pipeline"
Requires-Dist: beautifulsoup4>=4.12.0; extra == "pipeline"
Requires-Dist: lxml>=5.0.0; extra == "pipeline"
Requires-Dist: fake-useragent>=1.5.0; extra == "pipeline"
Requires-Dist: tqdm>=4.66.0; extra == "pipeline"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Dynamic: license-file

[![MQL MCP](/TheFractalyst/mql-mcp/raw/main/assets/banner.svg)](https://github.com/TheFractalyst/mql-mcp)

[![PyPI](https://img.shields.io/pypi/v/mql-mcp?color=blue)](https://pypi.org/project/mql-mcp/)
[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white)](https://python.org/)
[![ChromaDB](https://img.shields.io/badge/ChromaDB-FF6F00)](https://trychroma.com/)
[![MCP](https://img.shields.io/badge/MCP-Protocol-blue)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests](https://github.com/TheFractalyst/mql-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/TheFractalyst/mql-mcp/actions/workflows/ci.yml)

Complete MQL4/MQL5 reference documentation MCP server with 4853 entries
covering 100% of the official MetaTrader 4/5 documentation sitemaps.

[Quick Start](#quick-start) |
[Tools](#tools) |
[Configuration](#configuration) |
[Database](#database) |
[Development](#development)

---

## One Command. Two Minutes. Fully Functional.

```
pip install mql-mcp
mqlmcp
```

That's it. On first run, the server auto-builds the ChromaDB vector store from
shipped JSON data (takes 30-60 seconds for embedding model download + indexing).
Subsequent runs start instantly.

**What you get:**

* 6 MCP tools for MQL4/MQL5 docs lookup, code validation, and code generation
* 4853 entries indexed in a local ChromaDB vector store (100% offline)
* Sub-millisecond hot cache for priority lookups
* MetaEditor compiler integration (local, Wine, or SSH) for `mql_compile`
* MQL4-to-MQL5 automatic migration via `mql_repair`
* Works with Claude Desktop, Cursor, Windsurf, OpenCode, and any MCP client

**What you need:**

* Python 3.10+
* Any MCP-compatible AI client

---

## Why MQL MCP?

AI coding assistants hallucinate MQL syntax. MQL5 introduced significant changes
from MQL4 (handle-based indicators, CTrade class, CopyBuffer pattern, event model)
that models trained on older code get wrong.

MQL MCP gives AI assistants **authoritative, real-time access** to the complete
MetaTrader 4/5 reference:

* **100% coverage**: 4136/4136 MQL5 + 657/657 MQL4 sitemap URLs
* **MQL4 + MQL5 unified**: Single database with version tagging and filtering
* **Semantic search**: Vector embeddings find relevant docs by meaning, not keywords
* **Real compilation**: `mql_compile` validates code via the actual MetaEditor compiler
* **MQL4 to MQL5 migration**: `mql_repair(mode="migrate")` applies all known replacements
* **Code generation**: `mql_scaffold` generates validated EA, indicator, or script templates
* **100% local**: No network calls at runtime (except optional compiler validation)

---

## Tools

```
+----------------------+---------------------------------------------+
| Tool                 | Description                                 |
+----------------------+---------------------------------------------+
| mql_lookup           | Get complete docs for a symbol by exact name|
| mql_search           | Semantic search across all MQL4/MQL5 docs   |
| mql_browse           | Enumerate all members of a namespace        |
| mql_compile          | Compile MQL code via MetaEditor or syntax   |
| mql_repair           | Fix compiler errors or migrate MQL4 to MQL5 |
| mql_scaffold         | Generate EA, indicator, or script template  |
+----------------------+---------------------------------------------+
```

### Tool Details

**`mql_lookup(name, kind?, version?)`**
Get complete documentation for an MQL symbol by exact name. Auto-detects function,
variable, type, constant, keyword, or operator. Returns syntax, parameters, returns,
remarks, and code examples. Filter by `version="mql4"` or `version="mql5"`.

**`mql_search(query, category?, namespace?, n_results?, version?)`**
Semantic search across the entire MQL4/MQL5 reference. Supports category filtering,
namespace filtering, and version filtering.

**`mql_browse(namespace, category?, style?, version?)`**
Enumerate every member of a namespace (e.g., `trade`, `indicator`, `array`).
`style="cheatsheet"` produces a compact, box-drawn signature summary.

**`mql_compile(code?, file_path?, explain?, version?)`**
Compile MQL code via the real MetaEditor compiler. Supports inline code, file paths,
and `explain=True` for error-specific fix hints. Compilation methods (tried in order):
local MetaEditor, remote SSH MetaEditor, syntax-only validation fallback.

**`mql_repair(code, context, mode?, version?)`**
Fix compiler errors (`mode="targeted"`) or migrate MQL4 code to MQL5
(`mode="migrate"`). Applies all known MQL4->MQL5 breaking change replacements,
then recompiles to verify.

**`mql_scaffold(kind, name, description?, version?, lots?, take_profit?, stop_loss?, magic_number?)`**
Generate a validated MQL EA, indicator, or script template. Pre-wired with standard
inputs, risk parameters, and trade logic. Result is compiled before return.

## MCP Client Configuration

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "mql-mcp": {
      "command": "mqlmcp",
      "transport": "stdio"
    }
  }
}
```

### Cursor / Windsurf / OpenCode

Add to your project's `.mcp.json` or global MCP config:

```json
{
  "mcpServers": {
    "mql-mcp": {
      "command": "mqlmcp",
      "transport": "stdio"
    }
  }
}
```

### SSE (HTTP)

```
mqlmcp serve --transport sse --port 8080
```

Or via environment variable:

```
TRANSPORT=sse PORT=8080 mqlmcp
```

Connect to `http://localhost:8080`.

## Configuration

```
+------------------------+---------------------+----------------------------------+
| Env Var                | Default             | Description                      |
+------------------------+---------------------+----------------------------------+
| TRANSPORT              | stdio               | Transport: stdio or sse          |
| PORT                   | 8080                | Port for SSE transport           |
| MQL_DB_PATH            | ./mql_db            | ChromaDB path                    |
| MQL_COLLECTION         | mql_reference       | ChromaDB collection name         |
| MQL_EMBED_MODEL        | all-MiniLM-L6-v2    | Sentence transformer model       |
| METAEDITOR_PATH        | (empty)             | Path to metaeditor64.exe         |
| METAEDITOR_SSH_HOST    | (empty)             | SSH host for remote compilation  |
| METAEDITOR_REMOTE_PATH | metaeditor64.exe    | Remote MetaEditor executable     |
| MQL_COMPILE_TIMEOUT    | 60                  | Compilation timeout in seconds   |
| LOG_LEVEL              | INFO                | Logging level                    |
| LAZY_MODEL             | 0                   | Set to 1 to defer model loading  |
+------------------------+---------------------+----------------------------------+
```

## Database

* 4853 entries (MQL4 + MQL5 unified)
* MQL5: 4136/4136 sitemap URLs (100%)
* MQL4: 657/657 sitemap URLs (100%)
* 37 documentation sections + 33 MetaTrader5 Python API pages
* Hot cache for sub-millisecond priority lookups
* Auto-built on first run from shipped JSON data (7.5MB)

To rebuild the database:

```
mqlmcp build
```

## Development

```
git clone https://github.com/TheFractalyst/mql-mcp.git
cd mql-mcp
pip install -e ".[dev]"
pytest tests/ -v
```

### Re-scrape from MQL Docs

```
pip install -e ".[pipeline]"
python -m playwright install chromium
python pipeline/scrape_mql5.py
python pipeline/scrape_mql4.py
python pipeline/merge_and_index.py --reset --output-json data/mql_merged_entries.json
```

## Docker

```bash
docker build -t mql-mcp .
docker run -p 8080:8080 -e TRANSPORT=sse mql-mcp
```

## Tech Stack

* **FastMCP 3.4** - MCP server framework with FileSystemProvider auto-discovery
* **ChromaDB** - Local vector database for semantic search (cosine, 384-dim)
* **SentenceTransformers** - `all-MiniLM-L6-v2` embedding model
* **RapidFuzz** - Fuzzy string matching for name lookups
* **Loguru** - Structured logging with daily rotation (SSE mode)

## Links

* [fractalyst.dev](https://fractalyst.dev/) - Portfolio
* [MQL5 Documentation](https://www.mql5.com/docs) - Official MQL5 reference
* [MetaTrader 5](https://www.metatrader5.com/) - Trading platform
* [@TheFractalyst](https://x.com/TheFractalyst) - X / Twitter

## License

MIT - see [LICENSE](LICENSE)
