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

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ư])

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

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

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

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

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

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

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