Taiwan Stock Agent

# tw-stock-agent: 台灣股市資料 MCP 服務器 [](TODO.md) [](https://python.org) [](https://modelcontextprotocol.io) ## 簡介 **tw-stock-agent** 是一個基於 Model Context Protocol (MCP) 的服務器，提供台灣股市資料查詢與分析功能。項目目前處於開發階段，正在進行架構重構以實現生產就緒的狀態。 ### 核心功能 * 台灣上市上櫃股票基本資料（公司概況、產業別、市值等） * 股票歷史價格走勢和技術分析 * 即時股票資訊和市場概況 * 四大買賣點技術分析 * Taiwan Stock Exchange (TWSE) 和 Taipei Exchange (TPEx) 數據 ### 技術特色 * 基於 FastMCP 框架的 MCP 協議實現 * 異步 I/O 處理和高效能快取 * 結構化輸出與 Pydantic 數據驗證 * 完整的錯誤處理和日誌記錄 * 支援多種 MCP 傳輸協議 ## 開發狀態 ⚠️ **重要提示**: 本專案目前正在進行架構重構，請參考 [TODO.md](TODO.md) 了解開發路線圖。 **當前架構狀態:** - ✅ 基本 MCP 工具實現 - 🔄 正在整合雙架構（FastAPI + FastMCP） - 🔄 實現完整異步 I/O 模式 - ⏳ 待實現結構化輸出和資源模式 - ⏳ 待添加資料庫持久化層 ## 系統需求 * **Python:** 3.11 或更高版本 * **套件管理:** 僅支援 uv（依照 [CLAUDE.md](CLAUDE.md) 開發規範） ## 安裝與設置 ### 開發環境設置 1. **克隆專案**： ```bash git clone https://github.com/clsung/tw-stock-agent.git cd tw-stock-agent ``` 2. **安裝依賴**（僅使用 uv）： ```bash uv sync ``` 3. **設置 pre-commit hooks**： ```bash uv run pre-commit install ``` 4. **環境配置**： ```bash # 複製環境變數模板（如果存在） cp .env.example .env ``` ## 運行 MCP 服務器 ### 開發模式 ```bash # 使用 FastMCP 服務器（推薦） uv run python mcp_server.py # 使用 MCP 開發工具 uv run mcp dev mcp_server.py ``` ### MCP 客戶端整合 **當前實現方式**（FastMCP stdio 模式）： ```json { "mcpServers": { "tw-stock-agent": { "command": "uv", "args": ["run", "python", "mcp_server.py"], "cwd": "/path/to/tw-stock-agent" } } } ``` **未來支援**（HTTP 傳輸）： ```json { "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](TODO.md)): - 🎯 整合為純 FastMCP 架構 - 🎯 完整異步 I/O 實現 - 🎯 結構化資料輸出 - 🎯 資料庫持久化層 - 🎯 全面錯誤處理和監控 **技術棧**: - **MCP 框架**: FastMCP (代替雙重架構) - **資料驗證**: Pydantic v2 - **HTTP 客戶端**: aiohttp (異步) - **資料庫**: SQLAlchemy + SQLite/PostgreSQL - **快取**: Redis (生產) / 記憶體快取 (開發) - **測試**: pytest + anyio ## 開發指南 詳細的開發規範請參考 [CLAUDE.md](CLAUDE.md)。 ### 快速開始 ```bash # 安裝依賴 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](TODO.md) 了解當前優先事項 2. 遵循 [CLAUDE.md](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](TODO.md) 了解改進計劃。 ## 使用範例 ### 基本工具調用 ```python # 通過 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 官方文檔](https://modelcontextprotocol.io) - [FastMCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - [台灣證券交易所 API](https://www.twse.com.tw) - [證券櫃檯買賣中心](https://www.tpex.org.tw) ## 授權條款 本專案採用 MIT 授權條款 - 詳見 [LICENSE](LICENSE) 文件。 ## 貢獻與回饋 歡迎貢獻程式碼、回報問題或提出改進建議： 1. 查看 [TODO.md](TODO.md) 了解開發優先事項 2. 遵循 [CLAUDE.md](CLAUDE.md) 開發規範 3. 提交 Issue 回報問題或建議功能 4. 提交 Pull Request 貢獻程式碼 **開發者**: 本專案正在積極開發中，歡迎參與貢獻！