mql5-help-mcp
by caoshuo594
README.md
# MQL5 Help MCP Server
[](https://npmjs.org/package/mql5-help-mcp)
`mql5-help-mcp` 让你的 AI 编程助手（Claude Code、Cursor、Copilot、Gemini CLI 等）直接访问本地的 MQL5 文档与学习资料库。基于 Model Context Protocol (MCP)，为 AI 助手提供 4500+ 官方文档与两本补充电子书（HTML）的快速检索能力，助你更高效地完成 EA/指标/脚本开发与调试。
## 有哪些资料被内置？
- 官方 MQL5 文档：`MQL5_HELP/`（4500+ .htm）
- MQL5 算法交易手册（HTML）：`MQL5_Algo_Book/`
- 神经网络与机器学习手册（HTML）：`Neural_Networks_Book/`
> 说明：两本电子书版权归原作者所有，仅作为学习参考随仓库分发；当前版本主要对 `MQL5_HELP/` 做了完整索引，电子书的统一索引与搜索将在后续版本补充（Roadmap 已列出）。
## 面向问题的能力（结合用户建议重构）
当前可用 + 规划中功能一览：
- 搜索文档（已提供）
- 通过函数名、类名或关键词快速定位官方文档
- 覆盖交易函数、指标、标准库、ONNX 等常用主题
- 智能匹配（已提供基础能力）
- 支持精确/模糊匹配，兼容常见类名变体（如 CTrade/Trade）
- 常见错误解决方案库（进行中）
- 错误 256/undeclared identifier 等典型问题的成因与对照表
- MQL4→MQL5 迁移差异：Symbol()→_Symbol，Period()→_Period，ResultCode()→ResultRetcode()
- 智能错误匹配（规划中）
- 直接用“编译器错误文本”搜索：如 `error 256: undeclared identifier ResultCode`
- 上下文感知搜索（规划中）
- 术语映射与别名：如 MQL4 的 `iMA` → MQL5 的 `IndicatorCreate`
- 代码分析与诊断（规划中）
- `analyze_code`：指出 API 更名与常见误用
- `diagnose_error`：基于编译错误日志给出定位与替代建议
- 交互式帮助（规划中）
- 支持“针对某一行代码/某一错误”的追问式问答
- 学习路径推荐（规划中）
- 从“语法差异 → 标准库 → 指标/交易 → 性能优化”的循序内容
- 多维标签与版本标注（规划中）
- 难度/用途/版本/主题等维度过滤；明确 MQL4 兼容信息
> 优先级：
>
> - 高：智能错误匹配、错误解决方案库、代码示例
> - 中：上下文感知搜索、交互式帮助、学习路径
> - 低：代码分析、标签系统、版本标注（细化）
## 快速开始
### 前提条件
- Node.js 18.0 或更高版本
- npm 或 npx
### 🚀 Claude Code 用户快速安装（最简单）
如果你使用 Claude Code，可以直接在命令行运行：
```bash
claude mcp add mql5-help npx -- -y github:caoshuo594/mql5-help-mcp
```
安装后验证：
```bash
claude mcp list
```
你应该看到 `mql5-help` 显示为 `✓ Connected`。
> **首次安装注意**：第一次运行时，npx 需要从 GitHub 下载源代码、安装依赖并编译 TypeScript，可能需要 10-30 秒。如果首次显示连接失败，请稍等片刻后再次运行 `claude mcp list` 检查状态。
---
### 方便管理 ：直接从 cc-switch 安装（手动配置）
**MCP 标题 (唯一)** 建议填写：`mql5-help` 或 `mql5-docs` *(这是给系统内部用的 ID，只要不和别的重复即可)*
**显示名称** 建议填写：`MQL5 Documentation Server` *(这是显示给你看的名称，方便你识别)*
**完整的 JSON 配置** 请将编辑器中原有的内容清空，并复制粘贴以下代码。
由于这是一个 Node.js 项目，官方推荐使用 `npx` 直接运行：
JSON
```
{
"type": "stdio",
"command": "npx",
"args": [
"-y",
"github:caoshuo594/mql5-help-mcp"
]
}
```
### 注意事项（重要）
1. **必须安装 Node.js**：
因为配置中使用了 `npx` 命令，你的电脑上必须已经安装了 Node.js 环境。如果没有安装，这个 MCP 服务将无法启动。
2. **首次运行较慢**：
第一次添加并启用时，`npx` 需要从 GitHub 下载该包，可能会有一定的延迟，请耐心等待连接变绿（状态正常）。
3. **Windows 用户**：
通常直接写 `"command": "npx"` 是可以的。如果报错找不到命令，你可能需要填写 `npx` 的完整路径（例如：`C:\\Program Files\\nodejs\\npx.cmd`），但大多数情况下直接写 `npx` 即可。
### 测试你的配置
配置完成后，在 Claude Code 或其他 AI 助手中测试以下命令：
#### 示例 1：搜索函数文档
```
搜索 MQL5 的 OrderSend 函数用法
```
AI 助手会调用 `search` 工具，返回相关文档列表。
#### 示例 2：获取详细文档
```
获取 CTrade 类的完整文档
```
AI 助手会调用 `get` 工具，返回 CTrade 类的详细说明。
#### 示例 3：浏览分类
```
浏览 MQL5 的交易相关文档有哪些？
```
AI 助手会调用 `browse` 工具，显示 trading 分类下的所有文档。
#### 示例 4：错误诊断（Smart Query - 推荐）
```
我的代码报错：error 256: undeclared identifier ResultCode，怎么解决？
```
AI 助手会自动调用 `smart_query`，直接返回解决方案：
- 诊断: ResultCode → ResultRetcode (MQL5迁移)
- 语法: ulong CTrade::ResultRetcode() const
- 示例代码
- 只消耗 ~500 tokens (vs 传统方式 4000+)
#### 验证 MCP 工具可用性
你也可以直接要求 AI 列出可用的 MQL5 工具：
```
列出你可以使用的 MQL5 文档工具
```
AI 应该会显示七个工具：`smart_query`、`search`、`get`、`browse`、`log_error`、`list_common_errors`、`manage_error_db`。
## 工具列表
本 MCP 服务器当前提供 7 个工具：
### 核心查询工具
1) **`smart_query`** - 🎯 智能查询（推荐）
- 参数：
- `query`（必填）：查询内容（错误信息、函数名、类名或问题）
- `mode`（可选）：`quick`（精简，~500 tokens，默认）或 `detailed`（详细，~1500 tokens）
- 特点：
- **优先从错误数据库查询历史解决方案**
- 自动识别查询类型（错误/函数/类/概念）
- 节省 80%+ token 消耗
- 完全本地化，零 API 成本
- 示例：
- "error E512: undeclared identifier ResultCode"（优先从数据库查询）
- "OrderSend 函数用法"
- "如何使用 CTrade 类下单"
2) `search` - 搜索文档
- 参数：`query`（必填，关键词），`limit`（可选，默认 10）
- 示例：
- “搜索与订单发送相关的函数”
- “查找 ONNX 模型相关的文档”
2) `get` - 获取文档详情
- 参数：`filename`（必填，如 `ordersend.htm` 或 `ordersend`）
- 示例：
- “获取 OrderSend 的完整文档”
- “查看 CTrade 类的详细说明”
4) `browse` - 浏览分类目录
- 参数：`category`（可选，如 `trading`, `indicators`, `math` 等）
- 常见分类：`trading`, `indicators`, `math`, `array`, `string`, `datetime`, `files`, `chart`, `objects`, `onnx`
### 错误收集与管理工具（新增 v1.3.0）
5) **`log_error`** - 📝 记录编译错误
- 参数：
- `error_code`（必填）：错误代码（如 `E512`、`E308`）
- `error_message`（必填）：完整错误消息
- `file_path`（可选）：发生错误的文件路径
- `solution`（可选）：解决方案描述
- `related_docs`（可选）：相关文档列表（JSON 数组格式）
- 功能：记录错误到本地 SQLite 数据库（存储在 `~/.mql5-help-mcp/mql5_errors.db`）
- 自动去重：相同错误会增加计数而不是重复记录
- 示例：
```
记录错误：E512，消息是"undeclared identifier ResultCode"，解决方案是"改用 ResultRetcode()"
```
6) **`list_common_errors`** - 📊 查看高频错误
- 参数：`limit`（可选，默认 10）：返回错误数量
- 功能：列出最常见的编译错误（按出现频率排序）
- 显示每个错误的出现次数、最后遇到时间、解决方案摘要
- 示例：
```
显示最常见的 10 个 MQL5 编译错误
```
7) **`manage_error_db`** - 🔧 管理错误数据库
- 参数：
- `action`（必填）：操作类型
- `export`：导出错误数据库为 JSON
- `import`：从 JSON 导入错误记录
- `stats`：查看数据库统计信息
- `data`（导入时必需）：JSON 格式的错误数据
- `anonymize`（可选，默认 false）：导出时是否移除文件路径（保护隐私）
- 功能：支持错误库的导出/导入，方便团队共享错误解决方案
- 智能合并：导入时自动合并，保留更高的出现次数
- 示例：
```
导出错误数据库（匿名模式）
查看错误数据库统计信息
从JSON文件导入团队共享的错误库
```
> **错误数据库位置**：`~/.mql5-help-mcp/mql5_errors.db`（用户主目录，跨项目共享）
>
> **工作流程**：
>
> 1. 遇到编译错误 → 使用 `smart_query` 查询（自动从数据库搜索）
> 2. 解决后 → 使用 `log_error` 记录解决方案
> 3. 定期查看 → 使用 `list_common_errors` 了解常见问题
> 4. 团队协作 → 使用 `manage_error_db` 导出/导入错误库
> 关于两本电子书：当前版本优先索引 `MQL5_HELP/`；对 `MQL5_Algo_Book/` 与 `Neural_Networks_Book/` 的"统一搜索与浏览分类"将随 Roadmap 开启，届时可通过 `browse` 与 `search` 在一个入口里检索。
## 示例与最佳实践
### 1. MQL4 → MQL5 迁移常见差异
- 预定义变量：`Symbol()` → `_Symbol`，`Period()` → `_Period`
- CTrade 结果：`ResultCode()` → `ResultRetcode()`
- 指标创建：`iMA(...)`（MQL4 习惯）→ `IndicatorCreate(...)`（MQL5 推荐）
示例（买入操作）：
```mql5
CTrade trade;
trade.SetExpertMagicNumber(12345);
if (trade.Buy(0.1, _Symbol)) {
Print("买入成功，retcode=", trade.ResultRetcode());
}
```
### 2. 以错误文本驱动的搜索（规划中）
输入：
```
error 256: undeclared identifier ResultCode
```
期望返回：
- 解释“ResultCode 已改名为 ResultRetcode（MQL5）”
- 指向 CTrade 类文档与迁移指南
### 3. 交互式诊断（规划中）
```
mcp__mql5-help__diagnose_error(`
ma_cross_ea.mq5(155,39) : error 256: undeclared identifier 'ResultCode'
`)
```
期望：定位第 155 行问题并给出替代 API。
## 项目结构（含电子书）
```
mql5-help-mcp/
├── src/ # TypeScript 源码
│ └── index.ts # MCP 服务器实现
├── build/ # 编译输出
├── MQL5_HELP/ # 官方 MQL5 文档（4500+ .htm）
├── MQL5_Algo_Book/ # 算法交易手册（HTML 电子书）
├── Neural_Networks_Book/ # 神经网络/机器学习手册（HTML 电子书）
├── scripts/
├── package.json
├── tsconfig.json
└── README.md
```
## 工作原理与架构
### 整体架构
```
┌─────────────────────────────────────────────────────────────┐
│ MQL5 Help MCP Server │
├─────────────────────────────────────────────────────────────┤
│ 工具层 (index.ts) │
│ ├── smart_query → 智能查询，精简返回 │
│ ├── search → 搜索文档，返回列表 │
│ ├── get → 获取完整文档内容 │
│ ├── browse → 浏览分类目录 │
│ ├── log_error → 记录错误到本地数据库 │
│ └── manage_error_db → 管理错误数据库 │
├─────────────────────────────────────────────────────────────┤
│ 查询引擎层 (smart-query.ts) │
│ ├── QueryAnalyzer → 分析查询类型（错误/函数/类/问题） │
│ ├── InfoExtractor → 从HTML提取关键信息 │
│ └── ResponseFormatter → 格式化精简/详细答案 │
├─────────────────────────────────────────────────────────────┤
│ 数据层 │
│ ├── 文档索引 (内存Map) → 4500+ htm/html/md 文件索引 │
│ └── 错误数据库 (SQLite) → 本地存储用户遇到的错误记录 │
├─────────────────────────────────────────────────────────────┤
│ 资料库 (本地文件，约60MB) │
│ ├── MQL5_HELP/ → 官方文档 4500+ 文件 │
│ ├── MQL5_Algo_Book/ → 算法交易电子书 │
│ └── Neural_Networks_Book/ → 神经网络电子书 │
└─────────────────────────────────────────────────────────────┘
```
### 查询流程
```
用户查询 "OrderSend"
│
▼
┌─────────────────────┐
│ 1. 查询分析 │ ← QueryAnalyzer 判断类型(函数查询)
└─────────────────────┘
│
▼
┌─────────────────────┐
│ 2. 内部搜索 │ ← 在内存 Map 中匹配 key
│ (不调用API) │ docIndex.get("ordersend")
└─────────────────────┘
│
▼
┌─────────────────────┐
│ 3. 读取本地文件 │ ← fs.readFile("MQL5_HELP/ordersend.htm")
│ (纯IO操作) │
└─────────────────────┘
│
▼
┌─────────────────────┐
│ 4. 信息提取 │ ← InfoExtractor 用正则提取:
│ (正则匹配) │ 语法/参数/返回值/示例
└─────────────────────┘
│
▼
┌─────────────────────┐
│ 5. 格式化输出 │ ← ResponseFormatter
│ quick: ~500 tokens│
│ detailed: ~1500 tokens
└─────────────────────┘
```
---
## 💰 Token 消耗分析
### 核心结论：查询本身不消耗 Token，返回给 AI 的内容才消耗 Token
| 操作 | Token 消耗 | 说明 |
| -------- | -------- | ------------------- |
| **文档存储** | ❌ 0 | 电子书存在本地，不计入 Token |
| **索引构建** | ❌ 0 | 启动时本地构建 Map，纯内存操作 |
| **搜索匹配** | ❌ 0 | 本地 Map 查找，O(1) 复杂度 |
| **文件读取** | ❌ 0 | `fs.readFile` 本地 IO |
| **信息提取** | ❌ 0 | 正则表达式匹配，本地计算 |
### 消耗 Token 的环节：MCP 工具返回的内容
| 工具 | 返回内容 | 估计 Token | 推荐场景 |
| ------------------------ | ------- | --------------- | ---------- |
| `smart_query` (quick) | 提取的精华信息 | **~500** | ✅ 日常查询（推荐） |
| `smart_query` (detailed) | 完整提取信息 | ~1500 | 需要详细说明 |
| `search` | 文件列表 | ~200-500 | 浏览/确认文件 |
| `get` | 完整文档内容 | **~3000-10000** | ❌ 高消耗，谨慎使用 |
### 传统方式 vs 本服务器
```
传统方式：
AI → "查 OrderSend" → 调用外部API → 返回完整文档 → 消耗大量 Token
(~5000 tokens)
本服务器：
AI → smart_query("OrderSend")
→ 本地搜索 + 本地读取 + 本地提取 (0 Token)
→ 返回精华内容 (~500 tokens)
节省: 5000 - 500 = 4500 tokens (节省 90%)
```
### 总结
| 问题 | 答案 |
| ------------- | ----------------------------------------------------------- |
| 电子书存储在哪？ | 本地 `MQL5_HELP/`, `MQL5_Algo_Book/`, `Neural_Networks_Book/` |
| 内置资料占用空间？ | ~60MB (纯本地存储) |
| 查询过程是否调用 API？ | ❌ 不调用，纯本地操作 |
| 返回结果消耗 Token？ | ✅ 是，但已优化到 ~500 tokens |
| 如何最省 Token？ | 用 `smart_query` 的 `quick` 模式 |
| 最耗 Token 的操作？ | `get` 工具（返回完整文档，~3000-10000 tokens） |
> **一句话总结**：电子书和索引存储在本地，搜索和提取完全在本地进行（零 API 调用）。唯一消耗 Token 的是 MCP 工具**返回给 AI 的内容**，而 `smart_query` 工具通过提取精华信息，将消耗从 ~5000 tokens 压缩到 ~500 tokens，**节省约 90% 的 Token**。
---
## 故障排除
### 1. 首次安装显示 "Failed to connect"
**症状**：运行 `claude mcp list` 显示 `mql5-help - ✗ Failed to connect`
**原因**：首次从 GitHub 安装时，npx 需要下载、安装依赖并编译 TypeScript，这个过程需要时间。
**解决方法**：
1. 等待 10-30 秒
2. 再次运行 `claude mcp list` 检查状态
3. 如果仍然失败，手动测试服务器：
```bash
npx -y github:caoshuo594/mql5-help-mcp
```
你应该看到：
```
🚀 MQL5 Help MCP Server 启动中...
📂 文档目录: MQL5_HELP:... | MQL5_Algo_Book:... | Neural_Networks_Book:...
✅ 服务器就绪，等待连接...
```
### 2. Claude Code 命令行工具相关
**使用 Claude Code CLI 管理 MCP**：
```bash
# 查看所有 MCP 服务器
claude mcp list
# 查看特定 MCP 详情
claude mcp get mql5-help
# 删除 MCP 服务器
claude mcp remove mql5-help
```
### 3. 手动配置 MCP（不使用 CLI）
如果你想手动编辑配置文件，配置文件位置：
- **Windows**: `%USERPROFILE%\.claude\claude_desktop_config.json`（Claude Desktop）或 `%USERPROFILE%\.claude.json`（Claude Code）
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/claude/claude_desktop_config.json`
添加如下配置：
```json
{
"mcpServers": {
"mql5-help": {
"command": "npx",
"args": ["-y", "github:caoshuo594/mql5-help-mcp"]
}
}
}
```
### 4. 本地开发模式问题
**模块未找到/未编译**：
```bash
cd /path/to/mql5-help-mcp
npm install
npm run build
```
确保 `build/index.js` 存在。
### 5. 搜索不到文档
- 优先使用英文函数名（如 `OrderSend`、`CopyBuffer`、`OnTick`）
- 确认拼写正确，或试试更短的关键词
- 类名支持变体：`CTrade` 和 `Trade` 都可以搜索到
### 6. Windows 路径问题
在 JSON 配置文件中，路径需要正确转义：
```json
// ✅ 正确 - 使用正斜杠
"args": ["D:/my-program/mql5-help-mcp/build/index.js"]
// ✅ 正确 - 使用双反斜杠
"args": ["D:\\my-program\\mql5-help-mcp\\build\\index.js"]
// ❌ 错误 - 单反斜杠会被解析为转义字符
"args": ["D:\my-program\mql5-help-mcp\build\index.js"]
```
## 版本历史
### v1.3.0 (2024-11-25) - 错误收集系统
**🎉 新功能:**
- 🗄️ 本地错误数据库（SQLite）- 无需网络服务器
- 📝 `log_error` 工具 - 记录编译错误及解决方案
- 📊 `list_common_errors` 工具 - 查看高频错误 TOP N
- 🔧 `manage_error_db` 工具 - 导出/导入/统计错误库
- 🔍 `smart_query` 增强 - 优先从错误数据库查询历史解决方案
**💡 核心特性:**
- 完全本地化存储（`~/.mql5-help-mcp/mql5_errors.db`）
- 智能去重：相同错误自动合并并计数
- 隐私保护：导出时可选移除文件路径
- 团队协作：支持导出/导入 JSON 格式错误库
- 相似度搜索：模糊匹配历史错误关键词
**🎯 使用场景:**
1. 遇到错误 → `smart_query` 自动查询数据库
2. 解决后 → `log_error` 记录方案供下次使用
3. 学习 → `list_common_errors` 了解常见问题
4. 协作 → `manage_error_db` 分享团队知识库
**📊 性能优化:**
- 数据库索引优化：错误代码、出现次数、时间戳
- WAL 模式提升并发性能
- 增量更新减少重复写入
### v1.2.0 (2024-11-24) - Smart Query重大更新
**🎉 新功能:**
- ✨ 新增 `smart_query` 智能查询工具
- 🎯 支持错误诊断、函数查询、类查询、概念查询
- 📉 节省80%+ token消耗 (4000 → 500 tokens)
- ⚡ 响应速度提升60%
- 🆓 完全本地化，零API成本，无需外部服务
**💡 核心特性:**
- 智能识别5种查询类型 (error/function/class/howto/concept)
- 基于正则表达式精准提取关键信息 (语法/参数/示例/注意事项)
- 两种模式: quick(~500 tokens) 和 detailed(~1500 tokens)
- 内置MQL4→MQL5迁移提示
**📚 新增文档:**
- `QUICK_START_SMART_QUERY.md` - 3分钟快速上手
- `SMART_QUERY_GUIDE.md` - 完整使用指南
- `AI_USAGE_GUIDE.md` - 针对编译错误修复场景
### v1.0.0 (2024-11-01) - 首次发布
- 基础搜索、获取、浏览功能
- 支持4500+ MQL5官方文档
- 包含2本电子书资源
---
## 路线图（Roadmap）
- ✅ [高] 智能错误匹配 - **v1.2.0已实现**
- ✅ [高] 常见错误解决方案库 - **v1.2.0已实现**
- ✅ [高] 错误收集与持久化 - **v1.3.0已实现**
- ✅ [高] 团队错误库共享 - **v1.3.0已实现**
- [ ] [高] 代码示例库扩展：更多EA模板与策略示例
- [ ] [高] 错误自动诊断：分析编译输出并提供解决方案
- [ ] [中] 上下文感知搜索增强：更多术语映射
- [ ] [中] 交互式帮助：多轮对话支持
- [ ] [中] 学习路径推荐：结构化教程
- [ ] [中] 错误预测：基于代码模式预警潜在问题
- [ ] [低] 统一索引两本电子书
- [ ] [低] 标签系统与版本标注
---
## 许可证与鸣谢
- 许可证：MIT（详见 [LICENSE](LICENSE)）
- MQL5文档版权归 MetaQuotes Ltd. 所有，本工具仅供开发辅助使用
- 文档版权：MQL5 官方文档归 MetaQuotes Ltd. 所有；两本电子书版权归原作者所有
- 致谢：Model Context Protocol、MQL5 社区与贡献者
---
专为量化开发者打造的“问题驱动”MQL5 知识助手：不仅能查文档，更帮你定位与解决真实问题。
This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo issues