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 開發規範）
安裝與設置
開發環境設置
- 克隆專案：
git clone https://github.com/clsung/tw-stock-agent.git
cd tw-stock-agent
- 安裝依賴（僅使用 uv）：
uv sync
- 設置 pre-commit hooks：
uv run pre-commit install
- 環境配置：
# 複製環境變數模板（如果存在）
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 字元
貢獻流程
重要限制與注意事項
API 限制
- TWSE API: 每5秒最多3個請求
- 資料更新頻率: 交易時間內每分鐘更新
- 快取策略: 即時資料1分鐘，歷史資料30分鐘
開發限制
- 市場交易時間: 週一至週五 09:00-13:30 (台灣時間)
- 假日處理: 遵循台灣股市交易日曆
- 資料完整性: 部分歷史資料可能有缺漏
已知問題
- 目前存在雙架構實現 (FastAPI + FastMCP)
- 混合同步/異步程式設計模式
- 參數命名不一致 (
stock_codevsstock_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)
相關資源
授權條款
本專案採用 MIT 授權條款 - 詳見 LICENSE 文件。
貢獻與回饋
歡迎貢獻程式碼、回報問題或提出改進建議：
開發者: 本專案正在積極開發中，歡迎參與貢獻！