# 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:

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

Khi phát triển local:

```powershell
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:

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

Tra cứu chi tiết:

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

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

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

Tìm ONNX trong MQL5 Reference:

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

Chẩn đoán log compile:

```text
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

```powershell
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.