tw-stock-agent: 台灣股市資料 MCP 服務器

簡介

tw-stock-agent 是一個基於 Model Context Protocol (MCP) 的服務器，提供台灣股市資料查詢與分析功能。項目目前處於開發階段，正在進行架構重構以實現生產就緒的狀態。

核心功能

• 台灣上市上櫃股票基本資料（公司概況、產業別、市值等）
• 股票歷史價格走勢和技術分析
• 即時股票資訊和市場概況
• 四大買賣點技術分析
• Taiwan Stock Exchange (TWSE) 和 Taipei Exchange (TPEx) 數據

技術特色

• 基於 FastMCP 框架的 MCP 協議實現
• 異步 I/O 處理和高效能快取
• 結構化輸出與 Pydantic 數據驗證
• 完整的錯誤處理和日誌記錄
• 支援多種 MCP 傳輸協議

開發狀態

⚠️ 重要提示: 本專案目前正在進行架構重構，請參考 TODO.md 了解開發路線圖。

當前架構狀態:

• ✅ 基本 MCP 工具實現
• 🔄 正在整合雙架構（FastAPI + FastMCP）
• 🔄 實現完整異步 I/O 模式
• ⏳ 待實現結構化輸出和資源模式
• ⏳ 待添加資料庫持久化層

系統需求

• Python: 3.11 或更高版本
• 套件管理: 僅支援 uv（依照 CLAUDE.md 開發規範）

安裝與設置

開發環境設置

1. 克隆專案：

git clone https://github.com/yourusername/tw-stock-agent.git
cd tw-stock-agent

2. 安裝依賴（僅使用 uv）：

uv sync

3. 設置 pre-commit hooks：

uv run pre-commit install

4. 環境配置：

# 複製環境變數模板（如果存在）
cp .env.example .env

運行 MCP 服務器

開發模式

# 使用 FastMCP 服務器（推薦）
uv run python mcp_server.py

# 使用 MCP 開發工具
uv run mcp dev mcp_server.py

MCP 客戶端整合

當前實現方式（FastMCP stdio 模式）：

{
  "mcpServers": {
    "tw-stock-agent": {
      "command": "uv",
      "args": ["run", "python", "mcp_server.py"],
      "cwd": "/path/to/tw-stock-agent"
    }
  }
}

未來支援（HTTP 傳輸）：

{
  "mcpServers": {
    "tw-stock-agent": {
      "command": "uvicorn",
      "args": ["tw_stock_agent.main:app", "--host", "127.0.0.1", "--port", "8000"]
    }
  }
}

⚠️ 注意: HTTP 傳輸配置將在架構重構完成後可用。

MCP 工具與功能

可用 MCP 工具

工具名稱	參數	功能描述
get_stock_data	stock_code: str	獲取股票基本資料（公司概況、產業別、市值等）
get_price_history	stock_code: str, period: str	獲取歷史價格數據（OHLCV、成交量）
get_realtime_data	stock_code: str	獲取即時股票資訊（當前價格、成交量）
get_best_four_points	stock_code: str	四大買賣點技術分析
get_market_overview	無	大盤指數和市場概況

MCP 資源（規劃中）

• stock://info/{stock_code} - 股票基本資訊
• stock://price/{stock_code} - 價格歷史
• stock://realtime/{stock_code} - 即時數據

資料來源

• TWSE (台灣證券交易所): 上市股票、TAIEX 指數
• TPEx (證券櫃檯買賣中心): 上櫃股票、興櫃市場
• 使用 twstock 函式庫進行資料擷取

效能特性

• 即時資料快取：1分鐘 TTL
• 歷史資料快取：30分鐘 TTL
• API 速率限制：每5秒最多3個請求（符合 TWSE 限制）

項目架構

當前架構狀態

tw-stock-agent/
├── CLAUDE.md                 # 開發規範與指導原則
├── TODO.md                   # 開發路線圖與改進計劃
├── README.md
├── pyproject.toml
├── mcp_server.py            # 🔄 FastMCP 伺服器實現
├── tw_stock_agent/
│   ├── main.py              # ⚠️  FastAPI 實現（將移除）
│   ├── services/
│   │   ├── stock_service.py  # 股票資料服務
│   │   └── cache_service.py  # 快取服務
│   ├── tools/
│   │   ├── stock_tools.py   # MCP 工具定義
│   │   ├── stock_code.py    # 股票代碼工具
│   │   └── *.csv           # 股票交易所資料
│   └── utils/
│       ├── config.py        # 配置管理
│       ├── data_fetcher.py  # 資料擷取工具
│       ├── error_handler.py # 錯誤處理
│       └── rate_limiter.py  # 速率限制
├── scripts/                 # 獨立資料收集腳本
│   ├── download_twse.py     # TWSE 資料下載
│   ├── download_tpex.py     # TPEx 資料下載
│   └── ...
└── tests/
    ├── unit/
    └── integration/

架構重構計劃

目標架構 (參考 TODO.md):

• 🎯 整合為純 FastMCP 架構
• 🎯 完整異步 I/O 實現
• 🎯 結構化資料輸出
• 🎯 資料庫持久化層
• 🎯 全面錯誤處理和監控

技術棧:

• MCP 框架: FastMCP (代替雙重架構)
• 資料驗證: Pydantic v2
• HTTP 客戶端: aiohttp (異步)
• 資料庫: SQLAlchemy + SQLite/PostgreSQL
• 快取: Redis (生產) / 記憶體快取 (開發)
• 測試: pytest + anyio

開發指南

詳細的開發規範請參考 CLAUDE.md。

快速開始

# 安裝依賴
uv sync

# 執行程式碼品質檢查
uv run ruff check --fix       # 程式碼檢查與格式化
uv run ruff format           # 程式碼格式化
uv run mypy tw_stock_agent/  # 型別檢查

# 執行測試
uv run pytest --cov=tw_stock_agent

# 執行 MCP 伺服器
uv run python mcp_server.py

開發規範

• 套件管理: 僅使用 uv，禁止使用 pip
• 程式碼風格: 遵循 PEP 8，使用 ruff 進行檢查
• 型別標註: 所有函數必須有完整的型別標註
• 文檔字串: 使用 Google 風格，公開 API 必須有文檔
• 測試: 使用 pytest + anyio 進行異步測試
• 行長度: 最大 88 字元

貢獻流程

1. 查看 TODO.md 了解當前優先事項
2. 遵循 CLAUDE.md 開發規範
3. 執行所有品質檢查工具
4. 確保測試覆蓋率 >90%
5. 提交 Pull Request

重要限制與注意事項

API 限制

• TWSE API: 每5秒最多3個請求
• 資料更新頻率: 交易時間內每分鐘更新
• 快取策略: 即時資料1分鐘，歷史資料30分鐘

開發限制

• 市場交易時間: 週一至週五 09:00-13:30 (台灣時間)
• 假日處理: 遵循台灣股市交易日曆
• 資料完整性: 部分歷史資料可能有缺漏

已知問題

• 目前存在雙架構實現 (FastAPI + FastMCP)
• 混合同步/異步程式設計模式
• 參數命名不一致 (stock_code vs stock_id)
• 缺乏結構化輸出和完整錯誤處理

請參考 TODO.md 了解改進計劃。

使用範例

基本工具調用

# 通過 MCP 客戶端調用工具範例
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def example_usage():
    server_params = StdioServerParameters(
        command="uv",
        args=["run", "python", "mcp_server.py"],
        cwd="/path/to/tw-stock-agent"
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # 獲取台積電 (2330) 股票資料
            result = await session.call_tool("get_stock_data", {
                "stock_code": "2330"
            })
            print(f"股票資料: {result.content}")
            
            # 獲取歷史價格
            result = await session.call_tool("get_price_history", {
                "stock_code": "2330",
                "period": "1mo"
            })
            print(f"歷史價格: {result.content}")

常用股票代碼

• 2330: 台積電 (TSMC)
• 2317: 鴻海 (Foxconn)
• 2454: 聯發科 (MediaTek)
• 2891: 中信金 (CTBC Financial)
• 3008: 大立光 (Largan Precision)

相關資源

• Model Context Protocol 官方文檔
• FastMCP Python SDK
• 台灣證券交易所 API
• 證券櫃檯買賣中心

授權條款

本專案採用 MIT 授權條款 - 詳見 LICENSE 文件。

貢獻與回饋

歡迎貢獻程式碼、回報問題或提出改進建議：

1. 查看 TODO.md 了解開發優先事項
2. 遵循 CLAUDE.md 開發規範
3. 提交 Issue 回報問題或建議功能
4. 提交 Pull Request 貢獻程式碼

開發者: 本專案正在積極開發中，歡迎參與貢獻！