VF Stock Agent — Nền tảng AI cho Đầu tư Chứng khoán Việt Nam

<p align="center"> <img src="logo.png" alt="VF Stock Agent Logo"/> </p>

Nền tảng AI & FastMCP Server phân tích chứng khoán Việt Nam. Tích hợp 144+ chỉ báo kỹ thuật, 35+ MCP Tools cho Claude/Cursor và LangGraph Workflow tự động tổng hợp báo cáo đầu tư.

---

Kiến Trúc Hệ Thống (Architecture & Workflows)

1. Sơ đồ Kiến trúc Monorepo

graph TD
    User["Người dùng / Claude Desktop / Cursor / Terminal"]
    
    subgraph Monorepo["Packages Monorepo (uv workspace)"]
        CLI["vf-stock-cli<br/>(Terminal CLI Entrypoint)"]
        MCP["vf-stock-mcp<br/>(FastMCP Server - 35+ Tools)"]
        Agent["vf-stock-agent<br/>(AI Decision Tools & LangGraph Workflows)"]
        Core["vf-stock-core<br/>(Data Access Layer & 144+ TA Engine)"]
    end
    
    Vnstock["Dữ liệu thị trường (vnstock)"]

    User -->|gọi lệnh| CLI
    User -->|kết nối MCP| MCP
    CLI --> Agent
    MCP --> Core
    Agent --> Core
    Agent -.->|Mount MCP| MCP
    Core --> Vnstock

2. Sơ đồ Luồng Phân Tích LangGraph (Workflow)

flowchart LR
    Start([Bắt đầu]) --> Node1["1. fetch_quote<br/>Lấy giá lịch sử & KLGD"]
    Node1 --> Node2["2. fetch_financials<br/>Phân tích ROE, P/E, Rủi ro"]
    Node2 --> Node3["3. calculate_ta<br/>Tính RSI, MACD & Tín hiệu"]
    Node3 --> Node4["4. synthesize_report<br/>Tổng hợp khuyến nghị"]
    Node4 --> End([Báo cáo Đầu tư])

---

Cấu trúc Monorepo (uv workspace)

vf-stock-agent/
├── pyproject.toml              # Root uv workspace configuration
├── docker-compose.yml          # Docker Compose cho FastMCP Server (SSE)
├── Dockerfile                  # Production container image
├── packages/
│   ├── vf-stock-core/          # Shared Data Access & Technical Analysis Engine (144+ TA)
│   ├── vf-stock-mcp/           # Unified FastMCP Server (35+ tools cho Claude/Cursor/Cline)
│   ├── vf-stock-agent/         # AI Learning Agent & LangGraph Workflows
│   └── vf-stock-cli/           # Terminal Command-Line Interface (`vf-stock`)
├── tests/                      # Suite kiểm thử đơn vị & tích hợp
└── README.md                   # Tài liệu hướng dẫn sử dụng

---

Tính năng nổi bật

1. AI Học Thị Trường & Phân Tích:
   • explain_indicator: Giải thích khái niệm, chỉ số và tín hiệu giao dịch thực tế của từng chỉ báo.
   • compare_stocks: So sánh cơ bản (P/E, P/B, ROE) và đưa ra nhận xét định giá.
   • analyze_financials: Tóm tắt sức khỏe tài chính, điểm mạnh, điểm yếu và phát hiện rủi ro (red flags).
   • screen_stocks: Lọc danh mục cổ phiếu đạt tiêu chuẩn đầu tư (ROE, P/E, tăng trưởng).
2. LangGraph Workflow Orchestration:
   • Tự động chạy quy trình phân tích đa bước: Lấy giá OHLCV -> Đánh giá BCTCN -> Tính chỉ báo kỹ thuật -> Tạo báo cáo tổng hợp.
3. 35+ FastMCP Tools:
   • Tích hợp liền mạch với Claude Desktop, Cursor, Cline thông qua chuẩn MCP (stdio / sse / streamable-http).

---

Quick Start

Cài đặt từ source

git clone https://github.com/your-org/vf-stock-agent.git
cd vf-stock-agent
pip install -e packages/vf-stock-core -e packages/vf-stock-mcp -e packages/vf-stock-agent -e packages/vf-stock-cli

Sử dụng CLI (vf-stock)

export VNSTOCK_API_KEY="your_api_key"

# Xem giá lịch sử
vf-stock history VNM

# AI giải thích chỉ báo RSI của FPT
vf-stock explain FPT --indicator RSI

# AI phân tích sức khỏe tài chính VCB
vf-stock health VCB

# AI so sánh VNM, MSN, SAB
vf-stock compare "VNM,MSN,SAB"

# Chạy LangGraph Workflow tạo báo cáo tổng hợp
vf-stock report FPT

Chạy FastMCP Server

# Stdio mode (Claude Desktop / Cursor)
vf-stock-mcp --transport stdio

# SSE mode (Web server)
vf-stock-mcp --transport sse --port 8000

---

Cấu hình MCP Client (Claude Desktop / Cursor)

Thêm cấu hình vào file MCP settings của bạn:

{
  "mcpServers": {
    "vf-stock": {
      "command": "vf-stock-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "VNSTOCK_API_KEY": "your_api_key_here"
      }
    }
  }
}

---

Docker Deployment

docker compose up -d
# FastMCP SSE Server sẽ chạy tại: http://localhost:8000

---

Lộ trình hoàn thành (Roadmap)

• [x] Phase 1 — Monorepo & Shared Core (vf-stock-core)
• [x] Phase 2 — MCP Server Thống nhất (vf-stock-mcp ~35+ tools)
• [x] Phase 3 — AI Learning Agent & LangGraph Workflows (vf-stock-agent)
• [x] Phase 4 — Unified CLI (vf-stock-cli) & Docker deployment

---

Biến môi trường

Xem chi tiết trong file [.env.example](file:///d:/Projects/vf-stock-agent/.env.example). Sao chép thành .env để cấu hình.

Biến	Mặc định	Mô tả
VNSTOCK_API_KEY	(bắt buộc)	API Key từ vnstocks.com
VNSTOCK_SOURCE	VCI	Nguồn dữ liệu (VCI, TCBS, MSN)
VNSTOCK_MCP_TRANSPORT	stdio	Transport (stdio, sse, streamable-http)
VNSTOCK_MCP_HOST	0.0.0.0	Host bind
VNSTOCK_MCP_PORT	8000	Port

---

License & Credits

• Được phát hành dưới bản quyền MIT License.
• Dữ liệu chứng khoán bởi vnstock (@thinh-vu)