Vnstock Logo

Nâng cấp từ bản 0.5 lên 1.0

Cộng đồngvnstock_mcp v1.0.0

Mục lục

Từ ngày 10/11/2026, các phiên bản thế hệ 5 (vnstock 5.x, vnstock_quant 0.x, vnstock-mcp 0.x) đã ngừng xác thực. Để tiếp tục dùng máy chủ MCP với trợ lý AI, bạn cần nâng lên vnstock-mcp 1.0 chạy cùng vnstock 6 và vnstock_quant 1.0 bản Cộng đồng.

Cách làm việc giữ nguyên: trợ lý gọi đúng hàm của thư viện, nối các bước bằng call_id, ghi mỗi bước thành câu lệnh Python và xuất thành kịch bản chạy độc lập. Điểm đổi lớn nhất là cách lấy dữ liệu: thế hệ 6 gọi thẳng Open API của nguồn bằng khóa bạn tự đăng ký, và bạn chọn nguồn cho từng lời gọi.

1. Các bước nâng cấp

  1. Cài hoặc nâng môi trường ảo lên vnstock-mcp 1.0 cùng vnstock 6 và vnstock-oapi.
  2. Chạy vnstock-mcp --setup <ứng_dụng> --write để ứng dụng AI trỏ đúng tới bản 1.0, rồi khởi động lại ứng dụng.
  3. Chạy vnstock-mcp doctor, rồi gọi quant_entitlement() và research_sources() trong ứng dụng AI để xem công cụ đang mở.
  4. Khi cần dữ liệu thị trường: đăng ký khóa ở nguồn, lưu bằng vnstock keys set <nguồn>, đặt nguồn ưu tiên bằng vnstock-mcp sources use <nguồn_chính> <nguồn_dự_phòng>.

Không có khóa nguồn nào, bạn vẫn dùng được ngay nhóm research_* và năm công cụ quant_* trên tệp có sẵn trên máy.

2. Lệnh cài đặt

Shell
python -m venv ~/.venv && source ~/.venv/bin/activate
pip install -U --extra-index-url https://vnstocks.com/api/packages \
  "vnstock-mcp[quant]==1.0.0" "vnstock==6.0.1" "vnstock-oapi==0.1.2"
vnstock-mcp --version

Nếu trước đây bạn đăng ký vnstock-mcp từ một môi trường ảo khác, chạy lại vnstock-mcp --setup <ứng_dụng> --write trong môi trường mới để tệp cấu hình của ứng dụng AI cập nhật đường dẫn.

3. Những gì giữ nguyên và thay đổi

Hạng mụcBản 0.5 (thế hệ 5)Bản 1.0 (thế hệ 6)
Thư viện dữ liệu nềnvnstock thế hệ 5, cài rời.vnstock 6 và vnstock-oapi là phụ thuộc bắt buộc; đầu ra theo compat="v6".
Cách lấy dữ liệuTheo cấp tài khoản Vnstock.Gọi thẳng Open API của nguồn bằng khóa của bạn; công cụ dữ liệu mở theo khóa có trên máy.
Chọn nguồn (source)Thư viện tự gán một nguồn mặc định.Bạn chọn qua source ở mọi công cụ dữ liệu hoặc lưu quy tắc bằng vnstock-mcp sources use.
Công cụ định lượngCài riêng vnstock_quant 0.x.Cài gọn qua [quant]; bản Cộng đồng mở 5 công cụ quant_* với lượt dùng thử trong ngày.
Dòng lệnhCác cờ --doctor, --setup, --profile…Thêm lệnh con onboard, status, doctor, setup, sources, tools, call, workspace, serve và giao diện tương tác trong Terminal; cờ cũ vẫn dùng được.
Kết quả JSONcall_id, code, provenance và các dòng dữ liệu.Giữ nguyên, thêm warnings. code dài được rút gọn trên khung trò chuyện nhưng giữ đủ trong nhật ký phiên.
Phép tính quá thời gian chờBáo hết giờ; gọi lại thì gửi thêm yêu cầu trùng.Trả StillRunning; gọi lại với cùng tham số sẽ chờ đúng phép tính đang chạy.
Thư mục nghiên cứu và hồ sơ~/vnstock_research; hồ sơ minimal, research, data, full.Giữ nguyên; thêm biến VNSTOCK_MCP_IMPORT_MB.
Thời hạn bản phát hành—30 ngày với bản rc, 365 ngày với bản chính thức.

4. Công cụ mới dùng được ở bản Cộng đồng

Công cụCông dụng
research_importNạp tệp CSV, Excel, Parquet, JSON có sẵn trên máy vào phiên để tính tiếp.
research_pdf, research_bctc, research_vasĐọc, bóc bảng và chuẩn hóa BCTC từ tệp PDF theo từ điển VAS (bản Cộng đồng: chỉ tiêu cấp 1).
research_sourcesXem nguồn dùng được trên máy và tuyến dữ liệu mỗi nguồn hỗ trợ.
quant_backtestChạy thử chiến lược một mã theo luật thị trường Việt Nam với 10 chỉ báo trong bảng quy tắc dsl.
market_global_indexChuỗi lịch sử chỉ số chứng khoán quốc tế, hiện khi máy có khóa của nguồn hỗ trợ.

quant_ta và quant_fa nhận thêm source; quant_fa thêm price_source và estimate_shares; quant_backtest nhận refs để lấy đầu ra của bước trước.

5. Công cụ đã bỏ hoặc tạm ẩn

Ở bản 0.5Ở bản 1.0Thay bằng
research_normalize, research_benchmarkĐã bỏChuẩn hóa nay nằm sẵn trong vnstock 6 (compat="v6"). Bảng lấy từ nơi khác thì nạp bằng research_import kèm columns.
research_universeĐã thayresearch_vas để tra từ điển chỉ tiêu VAS.
macro_economy, macro_currency, macro_globalMở theo khóa nguồnChỉ hiện khi máy có khóa của nguồn hỗ trợ dữ liệu vĩ mô.
insights_flow, insights_sentimentTạm ẩnKhối ngoại và tự doanh: market_equity với method="foreign_flow" hoặc "proprietary_flow" (market_index cho chỉ số), khi nguồn đã có khóa hỗ trợ.
retail_exchange_rateTạm ẩnChưa có nguồn Open API cho tỷ giá bán lẻ ngân hàng; tỷ giá quốc tế dùng market_forex.

6. Đổi giá trị method trên một số công cụ dữ liệu

Công cụmethod đã bỏmethod mới hoặc giữ lại
fundamental_equityratio, note, financial_healthChỉ số tài chính nay tính kèm công thức qua quant_fa.
reference_companyofficers, subsidiaries, affiliate, capital_historyGiữ info, shareholders, ownership, insider_trading, events.
reference_equity—Thêm price_limits, status.
reference_market(gọi không kèm method)Thêm status, sessions, trading_days.
reference_fundfee_structure, reportsGiữ list, profile.
market_equityodd_lotThêm active_flow, expected_price, summary.
market_index—Thêm foreign_flow, proprietary_flow.
market_etf—Thêm summary.
market_boardodd_lotThêm foreign_room.
market_fundholdings, asset_allocation, industry_allocation, dividendsGiữ history, performance.

Công cụ dữ liệu chỉ hiện các method mà nguồn bạn đã lưu khóa hỗ trợ.

7. Mẫu quy trình và dữ liệu đã lưu

MCP Prompts: bản 1.0 thêm mẫu bctc_deep_dive (đọc và kiểm tra chuyên sâu BCTC PDF trên máy), dùng được ngay ở bản Cộng đồng. Mẫu nào cần công cụ chưa mở trên máy thì tự ẩn: market_overview và macro_dashboard hiện khi nguồn bạn đã lưu khóa hỗ trợ đủ các công cụ mà mẫu cần; study_stock và reproducible_study dùng công cụ của bản Mở rộng.

Dữ liệu và kịch bản cũ:

  • Bảng đã lưu trong ~/vnstock_research/data/ từ bản 0.5 vẫn đọc lại được ở bản 1.0 theo tên (data="ten_bang"). research_datasets nhắc bạn thêm source nếu muốn chạy lại câu lệnh tạo bảng trên vnstock 6.
  • Kịch bản .py xuất từ bản 0.5 cần sửa cú pháp và thêm source theo Chuyển đổi lên vnstock 6, vì vnstock thế hệ 5 đã ngừng xác thực. Kịch bản xuất từ bản 1.0 luôn ghi sẵn vnstock.compat.use("v6") và source ở từng lời gọi.
  • Nhật ký phiên của cả hai bản cùng nằm trong ~/vnstock_research/journal/, mỗi phiên một tệp, không xung đột.