Phân quyền và Cấp tài trợ
Mở rộngBản Mở rộngvnstock_mcp v0.4.0Cập nhật
Mục lục
Nguyên tắc phân quyền
Cơ chế phân quyền của vnstock-mcp được quản lý tập trung tại lõi Rust, đồng bộ với chính sách phân quyền của hệ sinh thái Vnstock thế hệ 5 (vnstock-auth), đảm bảo tính nhất quán trên toàn bộ môi trường thực thi.
Tổng quan
vnstock-mcp phục vụ cả cộng đồng người dùng (miễn phí cho cá nhân, học tập và nghiên cứu) lẫn các nhà tài trợ dự án. Hệ thống áp dụng danh mục công cụ khả dụng tương ứng với 5 cấp độ tài khoản: Guest, Free, Bronze, Silver và Golden/Diamond.
Ma trận công cụ theo cấp tài khoản
Dưới đây là bảng tổng hợp phạm vi công cụ theo từng cấp tài khoản:
| Cấp tài khoản | Số lượng công cụ | Quyền truy cập Dữ liệu & Nghiên cứu | Quyền tính toán Định lượng (Quant) |
|---|---|---|---|
| Guest (Khách) | 7 công cụ | Tra cứu danh sách mã, rổ chỉ số (VN30), cây phân ngành ICB, lịch nghỉ lễ, giờ giao dịch, bảng giá cơ bản, quản lý bảng nghiên cứu cục bộ. | Tra cứu danh mục chỉ báo và phương pháp luận (quant_catalog). |
| Free (Cộng đồng) | 26 công cụ | Hồ sơ doanh nghiệp niêm yết, Báo cáo tài chính (CĐKT, KQKD, LCTT), chỉ số tài chính, lịch sử cổ tức, xếp hạng thị trường, chỉ số vĩ mô, tâm lý thị trường, thống kê tài khoản mở mới, lưu/nạp bảng từ nguồn ngoài, đối chiếu 2 nguồn dữ liệu, sinh mã Python tái lập. | Dùng thử 30 lượt/ngày cho tính toán chỉ báo kỹ thuật cơ bản (quant_ta_basic) và chỉ số tài chính (quant_fa_basic), tính trên dữ liệu ngoài (quant_compute). |
| Bronze (Tài trợ Đồng) | 33 công cụ | Toàn bộ lịch sử nến OHLCV, sổ lệnh độ sâu, dòng tiền khối ngoại và tự doanh theo phiên, đo lường rủi ro danh mục (VaR, CVaR, Max Drawdown, Beta). | Sử dụng các chỉ báo TA/FA cơ bản và mô hình rủi ro theo hạn mức của cấp tài trợ. |
| Silver (Tài trợ Bạc) | 36 công cụ | Toàn bộ quyền của Bronze, mở rộng đầy đủ bộ chỉ báo kỹ thuật chuyên sâu (Ichimoku, SuperTrend, Keltner, VWAP, CMF, Parabolic SAR, Aroon, Donchian...). | Bộ chỉ báo kỹ thuật nâng cao của vnstock_quant. |
| Golden & Diamond | 37 công cụ | Mở rộng tối ưu hóa danh mục đầu tư (Markowitz Efficient Frontier, Risk Parity, Black-Litterman) và Pipeline tự động hóa xuất dữ liệu cho AmiBroker / Excel. | Sử dụng đầy đủ các thuật toán định lượng theo quyền lợi của cấp tài trợ. |
Cơ chế lọc danh mục công cụ theo cấp tài khoản
Khi Trợ lý AI giao tiếp qua giao thức MCP, nếu toàn bộ công cụ thuộc các gói tài trợ cao hơn đều hiển thị, AI có thể tự tiện gọi nhầm và nhận lại thông báo lỗi quyền truy cập.
vnstock-mcp áp dụng cơ chế Lọc danh mục công cụ (Tool Filtering) ngay tại tầng Rust:
┌────────────────────────────────┐
│ Cấp tài khoản người dùng: FREE │
└───────────────┬────────────────┘
│
_native.get_enabled_tools()
│
▼
┌────────────────────────────────────────────────────────┐
│ Rust Core: Duyệt danh mục công cụ │
│ • Tool có minimum_tier <= Free --> Hiển thị │
│ • Tool có minimum_tier > Free --> Không đưa vào list│
└───────────────────────────┬────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────┐
│ FastMCP server: Chỉ xuất 26 công cụ vào tools/list │
└───────────────────────────┬────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────┐
│ Trợ lý AI chỉ thấy và gọi các công cụ khả dụng │
│ ==> Giảm thiểu lỗi gọi nhầm công cụ vượt quyền │
└────────────────────────────────────────────────────────┘
Trợ lý AI chỉ nhận được danh sách những công cụ mà tài khoản của bạn được phép sử dụng, giúp phiên làm việc diễn ra liền mạch và ổn định.
Chính sách dùng thử Quant cho cấp Cộng đồng
Nhằm hỗ trợ người dùng làm quen với phương pháp phân tích định lượng, vnstock-mcp cung cấp quyền dùng thử định mức hàng ngày:
- Lượt dùng thử: 30 lượt tính toán / ngày cho hai công cụ:
quant_ta_basic: Tính các chỉ báo kỹ thuật phổ thông (SMA, EMA, RSI, MACD, Bollinger Bands, ATR, Stochastic, OBV...).quant_fa_basic: Tính các chỉ số tài chính cơ bản trên Báo cáo tài chính.
- Nguồn dữ liệu linh hoạt: Bạn có thể dùng định mức này để tính trên dữ liệu nến Vnstock hoặc tính trên dữ liệu tự cung cấp, tệp CSV/JSON, hay dữ liệu từ nguồn khác bạn có quyền sử dụng.
- Làm mới tự động: Bộ đếm lượt dùng thử tự động làm mới vào đầu ngày mới theo giờ hệ thống.
- Gói tài trợ: Từ gói Bronze trở lên, quant không bị đếm lượt dùng thử; phép tính tính vào hạn mức chung của tài khoản (chia theo giờ, ngày, tháng, dùng chung cho mọi thư viện Vnstock).
Tra cứu phân quyền từ dòng lệnh
Bạn có thể kiểm tra cấp tài khoản và danh sách công cụ khả dụng trên máy của mình từ giao diện dòng lệnh:
1. Kiểm tra cấp tài khoản hiện tại
Shell
vnstock-mcp --status
# Đầu ra mẫu: Cấp tài khoản hiện tại: GOLDEN [Tài trợ: Có (Sponsor)]2. Xem danh sách công cụ mở cho cấp Free
Shell
vnstock-mcp --tools --tier freeXem danh sách 26 công cụ dành cho cấp Free
Text
Danh sách công cụ đang mở cho cấp tài khoản 'FREE' (26 công cụ):
-----------------------------------------------------------------
• reference_equity [Tối thiểu: GUEST ] : Tra cứu danh sách mã cổ phiếu theo sàn, rổ chỉ số hoặc ngành.
• reference_index [Tối thiểu: GUEST ] : Tra cứu danh sách chỉ số thị trường và rổ cổ phiếu thành phần.
• reference_industry [Tối thiểu: GUEST ] : Cây phân ngành chuẩn ICB và ánh xạ ngành theo mã cổ phiếu.
• reference_holiday [Tối thiểu: GUEST ] : Lịch nghỉ lễ và đóng cửa giao dịch của chứng khoán Việt Nam.
• reference_company [Tối thiểu: FREE ] : Hồ sơ doanh nghiệp niêm yết: cổ đông lớn, ban lãnh đạo, công ty con.
• reference_instrument [Tối thiểu: FREE ] : Tra cứu chứng chỉ quỹ (ETF), chứng quyền có bảo đảm (CW), trái phiếu.
• market_trading_hours [Tối thiểu: GUEST ] : Kiểm tra giờ giao dịch và phiên hiện tại (ATO, Khớp lệnh liên tục, ATC).
• market_board [Tối thiểu: GUEST ] : Bảng giá trực tuyến tổng hợp: giá khớp, biến động, khối lượng.
• market_lookback [Tối thiểu: GUEST ] : Tính toán khoảng nhìn lại (lookback: 3M, 1Y, 100 nến) ra ngày chuẩn.
• market_equity [Tối thiểu: FREE ] : Dữ liệu giao dịch cổ phiếu: nến OHLCV, sổ lệnh độ sâu, dòng tiền ngoại.
• fundamental_financial [Tối thiểu: FREE ] : BCTC theo quý/năm: Bảng cân đối kế toán, KQKD và Lưu chuyển tiền tệ.
• fundamental_ratio [Tối thiểu: FREE ] : Bộ chỉ số tài chính cơ bản: P/E, P/B, ROE, ROA, biên lợi nhuận, nợ.
• fundamental_dividend [Tối thiểu: FREE ] : Lịch sử trả cổ tức bằng tiền mặt hoặc cổ phiếu, ngày giao dịch không hưởng quyền.
• analytics_ranking [Tối thiểu: FREE ] : Xếp hạng thị trường theo vốn hóa, thanh khoản, biến động giá và RS.
• macro_indicator [Tối thiểu: FREE ] : Chỉ báo kinh tế vĩ mô Việt Nam: CPI, GDP, tín dụng, M2, tỷ giá USD/VND.
• insights_sentiment [Tối thiểu: FREE ] : Đo lường tâm lý thị trường, độ rộng thị trường và phân bổ dòng tiền.
• retail_account [Tối thiểu: FREE ] : Thống kê số lượng tài khoản chứng khoán mở mới của cá nhân và tổ chức.
• quant_catalog [Tối thiểu: GUEST ] : Danh mục các chỉ báo kỹ thuật, công thức tài chính và tài liệu.
• quant_ta_basic [Tối thiểu: FREE ] : 10 chỉ báo kỹ thuật phổ thông (Bản Cộng đồng: 30 lượt tính/ngày).
• quant_fa_basic [Tối thiểu: FREE ] : 10 chỉ số tài chính cơ bản tính trên BCTC (Bản Cộng đồng: 30 lượt/ngày).
• quant_compute [Tối thiểu: FREE ] : Tính toán chỉ báo định lượng trên dữ liệu ngoài do người dùng cung cấp.
• research_tables [Tối thiểu: GUEST ] : Liệt kê danh sách các bảng dữ liệu đã lưu trong phiên nghiên cứu cục bộ.
• research_load [Tối thiểu: FREE ] : Nạp bảng dữ liệu đã lưu trên máy để đưa vào các phép tính tiếp theo.
• research_save [Tối thiểu: FREE ] : Lưu bảng dữ liệu vào thư mục nghiên cứu máy tính với định dạng CSV/Parquet/JSON.
• research_compare [Tối thiểu: FREE ] : Đối chiếu và so sánh hai bảng dữ liệu từ 2 nguồn khác nhau.
• research_journal [Tối thiểu: FREE ] : Xem nhật ký phiên nghiên cứu hoặc sinh mã nguồn Python độc lập tái lập.3. Xem danh sách công cụ mở cho cấp Bronze
Shell
vnstock-mcp --tools --tier bronze
# Hiển thị 33 công cụ bao gồm đo lường rủi ro danh mục (quant_risk) và dữ liệu nến toàn lịch sử.