# MCP Server

> 27 công cụ dữ liệu chứng khoán Việt Nam cho Claude, Cursor, VS Code qua Model Context Protocol.

MCP (Model Context Protocol) cho phép trợ lý AI gọi công cụ thật. vnstock-js kèm sẵn một MCP server chạy local qua stdio: không cần khóa API, không cần deploy server.

## Cài đặt

### Claude Code

```bash
claude mcp add --scope user vnstock npx -y vnstock-js mcp
claude mcp list   # kiểm tra "vnstock: ... ✓ Connected"
```

### Claude Desktop

Thêm vào `claude_desktop_config.json` rồi khởi động lại Claude Desktop:

```json
{
  "mcpServers": {
    "vnstock": { "command": "npx", "args": ["-y", "vnstock-js", "mcp"] }
  }
}
```

### Cursor, VS Code

Thêm cùng cấu hình `{ "command": "npx", "args": ["-y", "vnstock-js", "mcp"] }` vào phần MCP server trong cài đặt của editor.

Cần Node 18 trở lên. Để chạy một bản cài sẵn thay vì tải qua `npx`, dùng `{ "command": "node", "args": ["/đường/dẫn/node_modules/vnstock-js/dist/cli.js", "mcp"] }`.

## Đơn vị

Phần dữ liệu (JSON) của mọi tool tính tiền bằng **đồng**: giá `57500` là 57.500 đồng. Phần tóm tắt in dạng dễ đọc như `57.5k`, `19.2 nghìn tỷ`. Nếu prompt hay file của bạn ghi giá theo nghìn đồng, nhắc AI chia giá của tool cho 1000 trước khi so sánh.

## Danh sách công cụ

| Tool | Tác dụng | Tham số chính |
|---|---|---|
| `get_quote` | Giá hiện tại của một mã | `symbol` |
| `get_history` | Lịch sử giá OHLCV | `symbol`, `from`, `to`, `limit` |
| `search_symbols` | Tìm mã theo tên hoặc ký hiệu | `query`, `limit` |
| `list_symbols` | Liệt kê mã theo sàn | `exchange`, `limit` |
| `top_movers` | Mã tăng, giảm mạnh hôm nay | `limit` |
| `is_trade_day` | Có phải ngày giao dịch | `date` |
| `get_trading_calendar` | Ngày nghỉ lễ trong năm | `year` |
| `get_company_info` | Tên, sàn, ngành của công ty | `symbol` |
| `get_dividends` | Lịch sử và lịch chia cổ tức | `symbol` |
| `get_corporate_events` | Sự kiện doanh nghiệp | `symbol` |
| `get_ai_context` | Bối cảnh kỹ thuật dạng JSON | `symbol`, `lookback`, `as_of` |
| `to_ai_prompt` | Bối cảnh kỹ thuật dạng văn bản | `symbol`, `lang`, `as_of` |
| `compare_symbols` | So sánh 2 tới 10 mã | `symbols` |
| `get_market_breadth` | Độ rộng một sàn | `exchange` |
| `get_foreign_flow` | Khối ngoại phiên hiện tại | `symbol`, `exchange`, `top` |
| `get_foreign_history` | Lịch sử khối ngoại theo phiên | `symbol`, `exchange`, `range` |
| `get_market_context` | Bối cảnh thị trường cho AI | `exchange`, `index`, `as_of` |
| `get_news` | Tin tài chính theo ngày | `date`, `source`, `keyword`, `limit` |
| `get_financials` | Báo cáo tài chính | `symbol`, `report`, `period` |
| `screen_stocks` | Sàng lọc theo chỉ số tài chính | `group`, `exchange`, `where`, `sort`, `limit` |
| `find_patterns` | Hỗ trợ/kháng cự, mẫu nến, Turtle, breakout | `symbol`, `recent` |
| `portfolio_summary` | Định giá danh mục; không truyền `positions` thì đọc danh mục đã lưu | `positions`, `cash`, `save` |
| `backtest_signal` | Backtest preset `breakout`, `oversold_bounce`, `ema_cross` | `symbols`, `preset`, `tp`, `sl`, `hold`, `range` |
| `find_similar_setups` | Phiên quá khứ có trạng thái giống (thử nghiệm) | `symbol`, `top` |
| `get_gold_price` | Giá vàng trong nước, đồng/lượng | `source` |
| `get_exchange_rate` | Tỷ giá Vietcombank | `currency`, `date` |
| `watchlist` | Quản lý danh sách theo dõi | `action`, `name`, `symbols` |

Tên 22 tool cũ được giữ nguyên từ bản 1.x. `screen_stocks` vẫn hiểu `filters`, `sort_by`, `order` kiểu cũ.

## Ví dụ hỏi

- "Giá FPT hôm nay thế nào, so với 3 tháng trước?"
- "Khối ngoại mua bán ròng VCB trong tháng này ra sao?"
- "Lọc VN30 các mã có P/E dưới 15 và ROE trên 15%."
- "Backtest tín hiệu breakout trên FPT, VCB, HPG với chốt lời 7%, cắt lỗ 4%, giữ 10 phiên."
- "Danh mục của tôi đang lãi lỗ bao nhiêu?" (dùng danh mục lưu ở `~/.vnstock-js/portfolio.json`)

## Dữ liệu lưu local

`watchlist` và `portfolio_summary` đọc, ghi file trong `~/.vnstock-js`, dùng chung với CLI `vnstock watchlist`, `vnstock portfolio`.

> **Lưu ý:** Dữ liệu chỉ phục vụ tham khảo. AI có thể diễn giải sai; kiểm tra lại số liệu quan trọng trước khi ra quyết định.