Shioaji MCP Server

# Shioaji MCP 伺服器 提供永豐金證券 Shioaji 交易 API 功能的模型上下文協議 (MCP) 伺服器，透過標準化工具存取交易功能。 **繁體中文** | [English](README_en-US.md) ## 功能特色 ### 身份驗證與連線 - `get_account_info` - 取得帳戶資訊和連線狀態 ### 市場資料 - `search_contracts` - 根據關鍵字、交易所或類別搜尋交易合約 - `get_snapshots` - 取得指定合約的即時市場快照 - `get_kbars` - 取得合約的歷史 K 線資料 ### 交易操作 - `place_order` - 使用指定參數下單買賣（需要權限） - `cancel_order` - 根據訂單 ID 取消現有訂單（需要權限） - `list_orders` - 列出所有訂單及其狀態 - `get_positions` - 取得目前持倉和損益（支援股票、期貨或全部帳戶） - `get_account_balance` - 取得帳戶餘額和保證金資訊（支援股票、期貨或全部帳戶） **⚠️ 交易安全性**：交易操作（`place_order`、`cancel_order`）預設為停用。設定 `SHIOAJI_TRADING_ENABLED=true` 來啟用交易功能。 ### 服務條款與合規 - `check_terms_status` - 檢查服務條款簽署狀態和 API 測試完成情況 - `run_api_test` - 執行服務條款合規的 API 測試（登入和訂單測試） ## 必要條件 1. **永豐金證券帳戶**：您需要一個[永豐金證券帳戶](https://www.sinotrade.com.tw/openact) 2. **API 憑證**：申請並取得 API Key 和 Secret Key 3. **服務條款**：完成文件簽署和 API 測試（詳見 [docs/SERVICE_TERMS.md](docs/SERVICE_TERMS.md)） 關於使用 GitHub Container Registry 的 Docker 映像詳細資訊，請參閱 [docs/CONTAINER_REGISTRY.md](docs/CONTAINER_REGISTRY.md)。 ## 安裝與使用 ### 使用預建的 Docker 映像（建議） 使用 GitHub Container Registry 預建的 Docker 映像是最簡單的方式： ```bash # 拉取最新穩定版映像 docker pull ghcr.io/musingfox/shioaji-mcp:latest # 執行 MCP 伺服器（唯讀模式） docker run --rm -i --platform=linux/amd64 \ -e SHIOAJI_API_KEY=your_api_key \ -e SHIOAJI_SECRET_KEY=your_secret_key \ -e SHIOAJI_TRADING_ENABLED=false \ ghcr.io/musingfox/shioaji-mcp:latest # 執行 MCP 伺服器並啟用交易功能 docker run --rm -i --platform=linux/amd64 \ -e SHIOAJI_API_KEY=your_api_key \ -e SHIOAJI_SECRET_KEY=your_secret_key \ -e SHIOAJI_TRADING_ENABLED=true \ ghcr.io/musingfox/shioaji-mcp:latest ``` #### 可用標籤 - `latest` - 主分支的最新穩定發布版 - `vX.Y.Z`（如 `v0.1.0`）- 特定版本發布 - `dev` - 最新開發版本（可能包含實驗性功能） 生產環境建議使用特定版本標籤。 ### 本地建置 Docker 映像 如果偏好本地建置映像： ```bash # 建置 Docker 映像 docker build -t shioaji-mcp . # 執行 MCP 伺服器（唯讀模式） docker run --rm -i --platform=linux/amd64 \ -e SHIOAJI_API_KEY=your_api_key \ -e SHIOAJI_SECRET_KEY=your_secret_key \ -e SHIOAJI_TRADING_ENABLED=false \ shioaji-mcp ``` ### MCP 客戶端設定 在您的 MCP 客戶端中加入以下設定： ```json { "mcpServers": { "shioaji": { "command": "docker", "args": [ "run", "--rm", "-i", "--platform=linux/amd64", "-e", "SHIOAJI_API_KEY=your_api_key", "-e", "SHIOAJI_SECRET_KEY=your_secret_key", "-e", "SHIOAJI_TRADING_ENABLED=false", "ghcr.io/musingfox/shioaji-mcp:latest" ] } } } ``` **交易權限**： - 設定 `SHIOAJI_TRADING_ENABLED=false`（預設）為唯讀模式 - 設定 `SHIOAJI_TRADING_ENABLED=true` 啟用交易操作 **啟用交易的範例**： ```json "-e", "SHIOAJI_TRADING_ENABLED=true" ``` 開發或測試時，您可以使用 `dev` 標籤： ```json "ghcr.io/musingfox/shioaji-mcp:dev" ``` ### Python 客戶端範例 我們提供 Python 客戶端範例，示範如何程式化使用 Shioaji MCP 伺服器： ```bash # 安裝 MCP 客戶端程式庫 pip install mcp-client # 設定您的 API 憑證 export SHIOAJI_API_KEY=your_api_key export SHIOAJI_SECRET_KEY=your_secret_key # 執行範例 ./examples/python_client.py ``` 範例展示： - 連接到 Shioaji MCP 伺服器 - 取得帳戶資訊 - 搜尋合約 - 取得即時市場資料 - 取得歷史 K 線資料 - 檢索持倉和帳戶餘額 完整程式碼詳見 [examples/python_client.py](examples/python_client.py)。 ### 本地開發（Linux/WSL） ```bash # 複製專案 git clone <repository-url> cd shioaji-mcp # 安裝相依套件 uv sync # 設定環境變數 export SHIOAJI_API_KEY=your_api_key export SHIOAJI_SECRET_KEY=your_secret_key # 執行 MCP 伺服器 uv run python -m shioaji_mcp.server ``` ## 開發指南 ### 環境設定 ```bash # 安裝開發相依套件 uv sync --extra dev # 設定環境變數（如需本地開發） export SHIOAJI_API_KEY=your_api_key export SHIOAJI_SECRET_KEY=your_secret_key ``` ### 測試 ```bash # 執行測試 uv run pytest # 測試覆蓋率 uv run pytest --cov=src/shioaji_mcp ``` ### 程式碼品質 ```bash # 檢查和格式化程式碼 uv run ruff check --fix src/ tests/ uv run ruff format src/ tests/ # 型別檢查 uv run mypy src/ ``` ### Docker 開發 ```bash # 建置開發 Docker 映像 docker build -t shioaji-mcp-dev . # 測試 Docker 容器 docker run --rm -i --platform=linux/amd64 \ -e SHIOAJI_API_KEY=test_key \ -e SHIOAJI_SECRET_KEY=test_secret \ shioaji-mcp-dev ``` ## 架構 ``` src/shioaji_mcp/ ├── server.py # MCP 伺服器主程式 ├── tools/ # 工具模組 │ ├── contracts.py # 合約搜尋 │ ├── market_data.py # 市場資料 │ ├── orders.py # 訂單操作 │ ├── positions.py # 持倉查詢 │ └── terms.py # 服務條款 └── utils/ # 工具程式 ├── auth.py # 身份驗證管理 ├── formatters.py # 資料格式化 └── shioaji_wrapper.py # Shioaji 包裝器 ``` ## 重要注意事項 ⚠️ **真實交易 API** - 此 MCP 伺服器連接到真實的永豐金證券 API - 所有交易操作都會執行真實訂單 - 請確保您在交易前了解風險 - 建議先以小額進行測試 - 本軟體以「現況」提供，不提供任何形式的保證 - 使用者需負責自己的交易決策和法規遵循 ⚠️ **相容性** - Python 3.10-3.12 - 建議在 Linux 環境或 Docker 中執行 - macOS 使用者應使用 Docker ## 故障排除 ### Docker 設定測試 我們提供腳本來測試您的 Docker 設定是否與 Shioaji MCP 伺服器相容： ```bash # 使腳本可執行 chmod +x scripts/test_docker_setup.sh # 執行測試腳本 ./scripts/test_docker_setup.sh ``` 此腳本檢查 Docker 安裝、守護程序狀態、權限、平台支援和基本功能。 ### macOS 相依性問題 ```bash # 使用 Docker 解決 docker run --platform=linux/amd64 ... ``` ### API 連線問題 ```bash # 檢查環境變數 echo $SHIOAJI_API_KEY echo $SHIOAJI_SECRET_KEY # 檢查 API 憑證是否有效 docker run --rm -i --platform=linux/amd64 \ -e SHIOAJI_API_KEY=your_key \ -e SHIOAJI_SECRET_KEY=your_secret \ shioaji-mcp python -c "from shioaji_mcp.utils.auth import auth_manager; print(auth_manager.is_connected())" ``` ## 授權條款 本專案採用 MIT 授權條款 - 詳見 [LICENSE](LICENSE) 檔案。 ## 貢獻 我們歡迎貢獻來改善 Shioaji MCP 伺服器！請參閱 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何為此專案貢獻的詳細指南。 1. Fork 此專案 2. 建立功能分支 3. 進行變更並加入測試 4. 執行程式碼檢查和測試 5. 提交 Pull Request