# 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

```mermaid
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)

```mermaid
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

```bash
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`)

```bash
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

```bash
# 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:

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

---

## Docker Deployment

```bash
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](https://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](/LICENSE).
- Dữ liệu chứng khoán bởi **vnstock** (`@thinh-vu`)