Dòng lệnh, tham số máy chủ và biến môi trường
Mục lục
Chương trình dòng lệnh vnstock-mcp vừa đảm nhiệm vai trò máy chủ giao thức MCP phục vụ các ứng dụng AI, vừa cung cấp bộ lệnh quản trị và chẩn đoán trực tiếp trên Terminal.
1. Danh sách các lệnh dòng lệnh (vnstock-mcp <lệnh>)
Khi bạn gõ vnstock-mcp không kèm đối số trong cửa sổ Terminal, chương trình sẽ mở giao diện tương tác trực quan. Các lệnh dưới đây đều có thể chạy trực tiếp từ dòng lệnh hệ điều hành hoặc gõ ngay bên trong giao diện tương tác đó (trừ những lệnh có ghi chú riêng):
| Cú pháp lệnh | Chức năng thực hiện |
|---|---|
vnstock-mcp onboard [--json] | Hiển thị quy tắc vận hành, trạng thái thiết lập hiện tại của máy và các bước cần làm tiếp theo (được trình bày tối ưu để trợ lý AI đọc hiểu trước khi bắt đầu phiên làm việc). |
vnstock-mcp status [--json] | Tổng hợp nhanh: phiên bản các thư viện, cấp quyền hạn tài khoản, danh sách nguồn đã lưu khóa, số lượng công cụ đang mở và các ứng dụng AI đã kết nối (chỉ chạy từ dòng lệnh ngoài). |
vnstock-mcp doctor | Kiểm tra sức khỏe cấu hình: xác thực môi trường Python, tệp cấu hình ứng dụng AI, quyền đọc thư mục và thực hiện một truy vấn dữ liệu thật để xác nhận kết nối. |
vnstock-mcp setup [ứng_dụng] [--write] | Tạo cấu hình kết nối cho một ứng dụng AI (nếu bỏ trống tên ứng dụng sẽ liệt kê danh sách 8 ứng dụng hỗ trợ). Tương đương cờ --setup. |
vnstock-mcp sources [show] | Hiển thị danh sách các nguồn dữ liệu đang dùng được trên máy và quy tắc ưu tiên nguồn đang áp dụng. |
vnstock-mcp sources which <route> | Tra cứu xem những nguồn dữ liệu nào hỗ trợ đọc một tuyến dữ liệu cụ thể (ví dụ: vnstock-mcp sources which market.equity.ohlcv). |
vnstock-mcp sources use <nguồn>… [--route mẫu] | Lưu quy tắc chọn nguồn: nguồn liệt kê đầu tiên là nguồn chính, các nguồn theo sau là nguồn dự phòng; có thể giới hạn theo tuyến bằng --route (ví dụ: --route "market.equity.*"). |
vnstock-mcp sources clear [--route mẫu] | Xóa quy tắc chọn nguồn ưu tiên đã lưu. |
vnstock-mcp tools [tên] [--profile hồ_sơ] | Liệt kê các công cụ đang hiển thị trên máy; truyền thêm tên một công cụ cụ thể để xem chi tiết các tham số và lựa chọn method đang mở của công cụ đó. |
vnstock-mcp call <tool> [tham_số=giá_trị …] | Gọi thử một công cụ trực tiếp ngay trên dòng lệnh để kiểm tra kết quả (ví dụ: vnstock-mcp call market_equity symbol=FPT source=ssi). |
vnstock-mcp workspace [--json] | Liệt kê các bảng dữ liệu đã lưu và các tệp kịch bản Python tái lập đang có trong thư mục nghiên cứu ~/vnstock_research. |
vnstock-mcp serve [--profile hồ_sơ] [-t truyền_tải] | Khởi chạy tiến trình máy chủ MCP (đây là lệnh mà các ứng dụng AI tự động gọi ngầm khi kết nối; chỉ gọi từ dòng lệnh ngoài). |
Phân tách rõ lệnh quản lý khóa của vnstock: Các thao tác lưu khóa nguồn dữ liệu thuộc về lệnh vnstock keys set <nguồn> và thao tác đăng nhập tài khoản Vnstock thuộc về lệnh vnstock login / vnstock status. Công cụ vnstock-mcp không bọc lại các lệnh nhập khóa này để đảm bảo khóa mật chỉ đi qua trình quản lý keyring chuẩn của vnstock.
2. Các tham số khởi chạy máy chủ
| Tham số dòng lệnh | Giá trị mặc định | Ý nghĩa và phạm vi áp dụng |
|---|---|---|
-t, --transport | stdio | Giao thức truyền tải: dùng stdio cho các ứng dụng AI trên Desktop và IDE; dùng streamable-http khi kết nối từ công cụ khác trên cùng máy tính qua HTTP. |
--host | 127.0.0.1 | Địa chỉ lắng nghe cho chế độ HTTP (chỉ chấp nhận các địa chỉ loopback nội bộ: 127.0.0.1, ::1, localhost). |
-p, --port | 8000 | Cổng lắng nghe khi chạy máy chủ ở chế độ HTTP. |
--path | /mcp | Đường dẫn endpoint khi chạy máy chủ ở chế độ HTTP. |
--token | (trống) | Mã xác thực Bearer token cho chế độ HTTP (khuyến nghị đặt qua biến môi trường VNSTOCK_MCP_TOKEN để bảo mật). |
--rate-limit | 120 | Số lượng yêu cầu HTTP tối đa cho phép trong mỗi phút. |
--profile | research | Chọn hồ sơ công cụ nạp vào phiên làm việc: minimal, research, data hoặc full. |
--layers | (mọi tầng) | Lọc thêm theo tầng chức năng (ví dụ: --layers market,quant). |
--doctor, --setup [APP], --write | — | Các cờ viết tắt tương đương với lệnh con doctor và setup. |
--log-level | WARNING | Mức độ ghi nhật ký kỹ thuật ra luồng stderr (DEBUG, INFO, WARNING, ERROR). |
-v, --version | — | In số phiên bản hiện tại của vnstock-mcp và thoát. |
3. Danh mục biến môi trường (VNSTOCK_MCP_*)
Bạn có thể cấu hình hành vi của máy chủ thông qua các biến môi trường dưới đây trong khối env của tệp cấu hình ứng dụng AI:
| Tên biến môi trường | Giá trị mặc định | Ý nghĩa và tác dụng |
|---|---|---|
VNSTOCK_MCP_PROFILE | research | Hồ sơ công cụ mặc định khi khởi động (minimal, research, data, full). |
VNSTOCK_MCP_LAYERS | (mọi tầng) | Danh sách các tầng công cụ được bật (ví dụ: reference,market,quant). |
VNSTOCK_MCP_WORKSPACE | ~/vnstock_research | Đường dẫn thư mục không gian làm việc dùng để lưu nhật ký, bảng dữ liệu và kịch bản Python. |
VNSTOCK_MCP_JOURNAL | 1 | Bật ghi nhật ký phiên làm việc ra ổ cứng (1 là bật, đặt 0 để tắt). |
VNSTOCK_MCP_RESULT_MEMORY | 32 | Số lượng kết quả gần nhất được giữ trong bộ nhớ RAM để tham chiếu qua call_id. Các kết quả cũ hơn ngưỡng này cần được lưu bằng research_save hoặc gọi lại. |
VNSTOCK_MCP_MAX_ROWS | 60 | Số dòng dữ liệu tối đa hiển thị trực tiếp trong mỗi câu trả lời cho trợ lý AI đọc (bảng gốc trong call_id vẫn giữ đủ 100% số dòng). |
VNSTOCK_MCP_DIGITS | 6 | Số chữ số có nghĩa được làm tròn khi hiển thị cho trợ lý AI (các tệp lưu xuống đĩa qua research_save luôn giữ nguyên độ chính xác gốc). |
VNSTOCK_MCP_FORMAT | table | Định dạng đóng gói bảng trả về cho AI: table (tách mảng cột và dòng gọn nhẹ) hoặc records (mỗi dòng là một đối tượng JSON). |
VNSTOCK_MCP_TIMEOUT | 60 | Thời gian chờ tối đa (tính bằng giây) cho mỗi lần gọi công cụ trước khi chuyển sang trạng thái StillRunning (đặt 0 nếu không muốn giới hạn). |
VNSTOCK_MCP_CACHE | 1 | Bật bộ nhớ đệm theo thời hạn ngắn để tránh gọi lặp lại tới nguồn dữ liệu khi trợ lý AI gửi trùng câu hỏi. |
VNSTOCK_MCP_CACHE_SIZE | 256 | Số lượng kết quả tối đa lưu trong bộ nhớ đệm. |
VNSTOCK_MCP_IMPORT_MB | 200 | Dung lượng tệp tối đa (tính bằng MB) mà công cụ research_import cho phép đọc vào bộ nhớ. |
VNSTOCK_MCP_TOKEN | (trống) | Chuỗi Bearer token bảo vệ máy chủ khi chạy ở chế độ HTTP nội bộ. |
VNSTOCK_TELEMETRY | (theo tài khoản) | Đặt bằng 0 nếu muốn tắt thống kê tần suất gọi công cụ trên máy hiện tại. |
4. Chính sách quyền riêng tư khi thống kê lượt gọi công cụ
Tính năng thống kê kỹ thuật mặc định tắt cho đến khi tài khoản Vnstock của bạn xác nhận đồng ý trên vnstocks.com. Ngay cả khi được bật, máy chủ chỉ ghi nhận thông tin vận hành ẩn danh gồm: tên công cụ được gọi, cặp công cụ gọi nối tiếp nhau, loại ứng dụng AI, giao thức (stdio hay HTTP) và mã lỗi kỹ thuật. Hệ thống không bao giờ ghi nhận mã chứng khoán bạn tra cứu, giá trị tham số, nội dung câu hỏi hay bất kỳ số liệu nào trong bảng kết quả.
