vn-stock-trader

VN Stock Trader — Claude Code Plugin for Vietnamese Stock Markets

Bộ plugins/skills/commands cho Claude Code giúp trader chứng khoán Việt Nam phân tích thị trường, quản lý danh mục, và nhận cảnh báo tự động.

---

Tính năng

Tính năng	Số lượng	Mô tả
MCP Tools	11	Dữ liệu realtime: giá, lịch sử, BCTC, tin tức, screener, danh mục, insider
Skills	10	TA, FA, News Impact, Portfolio Review, Screener, Sector Compare, Morning Brief, Session Summary, Portfolio Monitor, Watchlist
Slash Commands	8	/analyze, /screen, /portfolio, /news, /compare, /report, /alert, /trading-session
Agents	4	Market Watcher, News Analyst, Portfolio Manager, Research Agent

---

Cài đặt

Yêu cầu

• Python 3.12+
• uv — Python package manager
• Claude Code — CLI tool từ Anthropic

Cách 1: Plugin Install (Khuyến nghị)

# Clone repo
git clone https://github.com/hieutran/vn-stock-trader.git
cd vn-stock-trader

# Chạy installer
./install.sh

Sau đó trong Claude Code:

# Đăng ký marketplace
/plugin marketplace add ./path/to/vn-stock-trader

# Cài đặt plugin
/plugin install vn-stock-trader@vn-stock-trader

Cách 2: Install từ GitHub

# Trong Claude Code
/plugin marketplace add github:hieutran/vn-stock-trader
/plugin install vn-stock-trader@vn-stock-trader

Cách 3: Development Mode

# Load trực tiếp để phát triển
claude --plugin-dir ./path/to/vn-stock-trader

Cách 4: Manual Setup

# Clone và cài dependencies
git clone https://github.com/hieutran/vn-stock-trader.git
cd vn-stock-trader
uv sync

# Verify
uv run python -c "import vnstock; import pandas_ta; print('OK')"
uv run pytest mcp-server/tests/ -q   # 102+ tests should pass

Thêm MCP server vào .mcp.json của project hoặc ~/.claude/mcp.json toàn cục:

{
  "mcpServers": {
    "vn-stock-trader": {
      "command": "uv",
      "args": ["run", "python", "mcp-server/server.py"],
      "cwd": "/path/to/vn-stock-trader"
    }
  }
}

Kiểm tra MCP server:

uv run mcp dev mcp-server/server.py

---

🛠️ Cấu trúc Project

vn-stock-trader/
├── mcp-server/               # MCP server Python
│   ├── server.py             # Entry point (FastMCP)
│   ├── tools/                # 11 MCP tools
│   │   ├── market.py         # get_stock_price, get_market_overview, get_top_movers
│   │   ├── history.py        # get_stock_history (OHLCV + TA indicators)
│   │   ├── financials.py     # get_financial_report, get_sector_peers
│   │   ├── news.py           # get_news
│   │   ├── screener.py       # screen_stocks
│   │   ├── portfolio.py      # get_portfolio, update_portfolio
│   │   └── insider.py        # get_insider_trades
│   ├── data_sources/         # Data layer
│   │   ├── vnstock_client.py  # vnstock3 wrapper với SQLite cache
│   │   ├── vietstock_client.py# Vietstock data source
│   │   ├── news_scraper.py    # 7 nguồn tin: CafeF, VnEconomy, VNExpress,
│   │   │                      # Tin Nhanh CK, VietnamBiz, HNX, Báo Đầu tư
│   │   ├── ta_calculator.py   # pandas-ta indicators
│   │   └── portfolio.py       # Portfolio data model
│   ├── cache/                # SQLite cache module
│   └── tests/                # 102+ pytest tests
├── scripts/                  # Automation scripts
│   ├── morning_brief.py      # Tổng hợp trước phiên (8:30)
│   ├── session_summary.py    # Tổng kết phiên (14:50)
│   ├── portfolio_monitor.py  # Monitor liên tục trong phiên
│   └── watchlist_alert.py    # Check watchlist conditions
├── .claude/
│   ├── skills/               # 10 skills (auto-triggered)
│   ├── commands/             # 8 slash commands
│   └── agents/               # 4 specialized agents
└── data/
    ├── portfolio.json         # Danh mục đầu tư
    ├── watchlist.json         # Watchlist + alert conditions
    └── automation_config.json # Cấu hình automation

---

💬 Sử dụng với Claude Code

Slash Commands

/analyze VNM              # Phân tích toàn diện VNM (TA + FA + News)
/analyze HPG              # Phân tích HPG
/screen value             # Lọc cổ phiếu theo chiến lược value
/screen growth            # Lọc tăng trưởng
/screen momentum          # Lọc momentum
/portfolio                # Review danh mục hiện tại
/news VNM                 # Tin tức và impact analysis cho VNM
/compare VNM HPG          # So sánh 2 cổ phiếu
/report daily             # Báo cáo thị trường hôm nay
/report weekly            # Báo cáo tuần
/alert VNM 70000          # Đặt cảnh báo giá cho VNM