Vnstock Logo

Chọn nguồn và truy xuất dữ liệu thị trường

Cộng đồngvnstock_mcp v1.0.0

Mục lục

Các công cụ dữ liệu của vnstock-mcp 1.0 ứng với các nhóm hàm của vnstock 6: Market().equity("FPT").ohlcv() trong Python tương ứng với market_equity(symbol="FPT", method="ohlcv") khi trợ lý AI gọi. Dữ liệu được tải thẳng từ Open API của nguồn bằng khóa bạn đăng ký và lưu trên máy; Vnstock không cung cấp dữ liệu.

1. Công cụ dữ liệu nào dùng được ở bản Cộng đồng

Tình trạng trên máyCông cụ dữ liệu hiện ra
Chưa lưu khóa nguồn nàoreference_index(method="groups") (bảng nhóm chỉ số có sẵn trong thư viện, không gọi mạng) và market_crypto (tài sản mã hóa qua cổng công khai không cần khóa; chỉ hiện ở hồ sơ full hoặc data).
Đã lưu khóa của một hoặc vài nguồnThêm đúng những công cụ và lựa chọn method mà các nguồn đó hỗ trợ: tra cứu danh mục (reference_*), giá và giao dịch (market_*), báo cáo tài chính (fundamental_equity).

Mỗi nguồn chỉ hỗ trợ một phần các nhóm dữ liệu, nên lưu khóa một nguồn sẽ mở một phần tương ứng. Xem trên máy mình đang mở gì:

Shell
vnstock-mcp sources                            # Nguồn dùng được trên máy và quy tắc ưu tiên
vnstock-mcp sources which market.equity.ohlcv  # Nguồn nào hỗ trợ một tuyến dữ liệu
vnstock-mcp tools market_equity                # Các method đang mở của một công cụ

Khi máy chưa đăng nhập bằng khoá có gói quyền sử dụng, fundamental_equity trả các chỉ tiêu VAS cấp 1 rút gọn của ba báo cáo chính. Bảng từng công cụ và điều kiện hiện ra nằm ở Danh mục công cụ.

2. Nguyên tắc chọn nguồn (source)

Thế hệ 6 không có nguồn mặc định cố định, vì mỗi nguồn là một tài khoản riêng bạn đăng ký và theo điều khoản của nguồn đó. Mọi công cụ dữ liệu đều nhận tham số source:

  • Trợ lý truyền source rõ ràng: máy chủ dùng đúng nguồn đó cho lời gọi.
  • Trợ lý để trống source: máy chủ dùng quy tắc ưu tiên bạn đã lưu, hoặc tự chọn khi trên máy chỉ có một nguồn đọc được tuyến đó. Có nhiều nguồn mà chưa lưu quy tắc thì lời gọi trả về danh sách nguồn đọc được để trợ lý hỏi bạn.

Khi chưa biết chọn nguồn nào, trợ lý gọi research_sources (chạy cục bộ, không gọi mạng, không bao giờ trả khóa), hỏi bạn khi có nhiều lựa chọn tương đương, rồi truyền source tường minh.

Lưu quy tắc ưu tiên một lần cho mọi phiên:

Shell
vnstock-mcp sources use <nguồn_chính> <nguồn_dự_phòng>
vnstock-mcp sources use <nguồn_bctc> --route "fundamental.equity.*"
vnstock-mcp sources clear

Đoạn mã Python tương đương (code) luôn ghi rõ source đã dùng, kể cả khi lấy từ quy tắc lưu sẵn, để kịch bản kết xuất chạy lại được trên máy khác có khóa của cùng nguồn. Chi tiết thêm ở Chọn nguồn trong vnstock 6.

3. Quy ước đơn vị (compat="v6")

vnstock-mcp bật vnstock.compat.use("v6") cho cả phiên để đơn vị và thứ tự dữ liệu giống nhau giữa các nguồn:

Nhóm dữ liệuQuy ước
Giá cổ phiếu, ETF, chứng quyềnNghìn VND (95.4 là 95.400 đồng/cổ phiếu).
Điểm chỉ số và hợp đồng tương laiĐiểm chỉ số gốc của sở giao dịch.
Cột phần trăm (*_percent)Điểm phần trăm (2.5 là 2.5%).
Thứ tự thời gianTăng dần: dòng cũ nhất ở đầu, mới nhất ở cuối.

quant_backtest tự nhận đơn vị của bảng giá đầu vào (price_unit="auto"), nên bảng lấy từ market_equity hay nạp từ tệp đều chạy được.

4. Cấu trúc kết quả và thông báo lỗi

Mỗi lời gọi thành công trả về:

TrườngÝ nghĩa
call_idMã tham chiếu kết quả trong phiên (c1, c2…), để bước sau dùng trọn bảng mà không chép lại số liệu.
codeCâu lệnh Python tương đương (rút gọn nếu dài; bản đầy đủ nằm trong research_journal).
provenanceNguồn (source), tuyến dữ liệu (route), chuẩn đầu ra (compat: "v6"), thời điểm lấy, phiên bản thư viện. Bảng có sẵn trong thư viện như reference_index(method="groups") ghi là builtin.
columns, dataCác dòng gần nhất hiển thị cho trợ lý (mặc định 60 dòng); bảng đầy đủ vẫn nằm trong call_id.
rows, returned, truncated, noteTổng số dòng, số dòng đang hiển thị, cờ rút gọn và cách lấy trọn bảng.
warningsCảnh báo nguyên văn từ thư viện nền.

Lời gọi không thành công trả về {error, error_code, message, hint}:

  • MCP_INVALID_ARGUMENT: sai tên tham số; thông báo liệt kê tham số hợp lệ.
  • MCP_CHOICE_NOT_OPEN: gọi một method đang ẩn; thông báo nói tuyến đó cần nguồn nào, tách nguồn đã có khóa với nguồn chưa có, để bạn không nhầm với giới hạn của bản Cộng đồng.

Bước tiếp theo