MQL5 EA MCP Server

MCP server tra cứu tài liệu MQL5 cục bộ. Server lập chỉ mục từ MQL5_HELP, MQL5_Algo_Book và Neural_Networks_Book, sau đó cung cấp các công cụ tìm kiếm, truy vấn nhanh, đọc tài liệu, duyệt danh mục và chẩn đoán lỗi biên dịch.

Tất cả dữ liệu chạy cục bộ. Không cần dịch vụ mạng, không gửi tài liệu hay lỗi biên dịch ra ngoài.

Tính năng chính

• Tìm kiếm tài liệu MQL5 bằng SQLite FTS5.
• Hỗ trợ ba nguồn tài liệu: Reference, Algo Book và Neural Networks Book.
• smart_query trả lời gọn theo hàm, class, khái niệm hoặc lỗi thường gặp.
• diagnose_error phân tích log compile từ MetaEditor/terminal và gợi ý API liên quan.
• Error DB cục bộ giúp lưu lại lỗi và cách sửa để dùng lại về sau.
• browse sinh danh mục từ index thật, không dùng danh sách hard-code.
• Output của smart_query và get được giới hạn độ dài để tiết kiệm token.

Cài đặt nhanh

Yêu cầu:

• Node.js 18 trở lên.
• Claude Desktop, Cursor, Codex hoặc MCP client tương thích.

Ví dụ cấu hình MCP:

{
  "mcpServers": {
    "mql5-ea": {
      "command": "npx",
      "args": ["-y", "mql5-ea-mcp@1.4.1"]
    }
  }
}

Khi phát triển local:

npm install
npm run build
npm run build:index
node build/index.js

Dữ liệu cục bộ

• Docs index: ~/.mql5-ea-mcp/indexes/docs-v<schema>-<corpus-hash>.sqlite
• Error DB: ~/.mql5-ea-mcp/mql5_errors.db

Khi publish, package npm chứa sẵn SQLite index. Lần chạy đầu chỉ copy index này vào cache người dùng; các truy vấn sau không scan hay parse tài liệu HTML. Khi nâng phiên bản corpus, server tự tạo cache mới theo manifest; cache cũ có thể xóa an toàn khi không còn cần.

Biến môi trường dành cho development/test:

• MQL5_EA_DATA_DIR: thay thư mục chứa docs_index.sqlite và manifest đã build.
• MQL5_EA_CACHE_DIR: thay thư mục cache index cục bộ.

Danh sách tool

1. smart_query Truy vấn thông minh. Dùng cho hàm, class, lỗi compile, câu hỏi "cách làm" và khái niệm.

2. search Tìm tài liệu theo title, filename, alias, category, summary và nội dung.

3. get Đọc tài liệu chi tiết theo docId, đường dẫn, title hoặc alias.

4. browse Duyệt danh mục sinh từ docs index.

5. diagnose_error Parse log biên dịch MQL5, chỉ ra file/dòng/cột/mã lỗi, thêm migration hints và tài liệu liên quan.

6. log_error Ghi lỗi đã gặp vào error DB cục bộ.

7. list_common_errors Xem lỗi thường gặp theo tần suất.

8. manage_error_db Export/import/thống kê error DB.

Ví dụ sử dụng

Tra cứu nhanh:

smart_query(query="OrderSend MqlTradeRequest", mode="quick")

Tra cứu chi tiết:

smart_query(query="CopyBuffer indicator handle", mode="detailed")

Tìm chương trong sách:

search(query="datetime session filters", limit=5)
search(query="GPT transformer self attention", limit=5)

Tìm ONNX trong MQL5 Reference:

search(query="ONNX model inference", limit=5)

Chẩn đoán log compile:

diagnose_error(
  log="ma_cross_ea.mq5(155,39) : error 256: undeclared identifier 'ResultCode'",
  limit=5
)

Gợi ý dùng tool

Với đa số tình huống, hãy bắt đầu bằng smart_query. Nếu cần xem nhiều kết quả, dùng search. Nếu đã biết chính xác tài liệu cần đọc, dùng get. Khi có cả đoạn log compile, dùng diagnose_error thay vì hỏi từng lỗi rời rạc.

ONNX thuộc MQL5_HELP, không thuộc Neural_Networks_Book. Với Neural book, dùng các query như GPT transformer self attention, perceptron, attention, OpenCL neural network.

Hướng dẫn bổ sung

• QUICK_START_SMART_QUERY.md: hướng dẫn bắt đầu nhanh.
• SMART_QUERY_GUIDE.md: hướng dẫn chi tiết về smart_query.
• AI_USAGE_GUIDE.md: cách dùng với trợ lý lập trình khi sửa lỗi compile.
• ERROR_COLLECTION_GUIDE.md: cách dùng error DB cục bộ.

Kiểm thử và build

npm run build
npm run build:index
npm test

Kết quả mong đợi:

• TypeScript build thành công.
• Vitest pass toàn bộ test.
• build/ được refresh sau khi sửa TypeScript.
• data/docs_index.sqlite và data/docs_index.manifest.json được tạo trước khi đóng gói/phát hành.

Ghi chú phát triển

• Project dùng better-sqlite3, SQLite FTS5, Cheerio và Vitest.
• package-lock.json hiện không được commit vì .gitignore đang ignore lockfile.
• Error DB là dữ liệu người dùng, không lưu trong repo.
• Tài liệu HTML chỉ là input cho release build. Chạy npm pack --dry-run để kiểm tra tarball chỉ chứa build/, data/, README và LICENSE.