shioaji-mcp: Instructions file for Claude Code

Shioaji MCP Server - Claude Code 專案配置

專案概述

Shioaji MCP Server 是一個提供永豐金證券交易 API 功能的模型上下文協議 (MCP) 伺服器。專案已達到生產就緒狀態，支援完整的交易操作和市場資料存取功能。

任務管理系統

配置狀態: 使用本地 markdown 檔案進行任務管理

• 系統類型: Claude Code 內建 TodoWrite 工具
• 任務追蹤: 透過對話中的 todo list 進行即時追蹤
• 狀態同步: 任務狀態會在每次更新時同步顯示

技術棧和工具

開發環境

• Python: 3.10-3.12
• 套件管理: uv (優先選擇)
• MCP 框架: mcp>=1.0.0
• 交易 API: shioaji==1.2.5

程式碼品質工具

• 代碼檢查: ruff (取代 black, isort, flake8)
• 型別檢查: mypy
• 測試框架: pytest with pytest-asyncio

部署和分發

• 容器化: Docker with multi-platform support
• 容器註冊表: GitHub Container Registry (ghcr.io)
• CI/CD: GitHub Actions

開發工作流程

代碼提交規範

• 使用 conventional commits 格式: <type>[optional scope]: <description>
• 例如: feat(trading): add order cancellation functionality
• 例如: fix(auth): resolve connection timeout issues

測試要求

• 所有新功能必須包含對應的單元測試
• 測試覆蓋率應保持在合理水平
• 使用 mock 進行 API 相關測試以避免真實交易

安全考量

• 交易安全: 交易功能預設關閉，需要明確啟用 SHIOAJI_TRADING_ENABLED=true
• 憑證管理: 所有敏感資訊透過環境變數管理
• 權限控制: 實施分層權限管理系統

專案架構

src/shioaji_mcp/
├── server.py          # MCP 伺服器主程式
├── tools/             # MCP 工具模組
│   ├── contracts.py   # 合約搜尋工具
│   ├── market_data.py # 市場資料工具  
│   ├── orders.py      # 訂單操作工具
│   ├── positions.py   # 持倉查詢工具
│   └── terms.py       # 服務條款工具
└── utils/             # 共用工具程式
    ├── auth.py        # 身份驗證管理
    ├── formatters.py  # 資料格式化
    ├── permissions.py # 權限管理
    └── shioaji_wrapper.py # Shioaji API 包裝器

期貨帳戶支援

自版本 0.1.1 起，get_positions 和 get_account_balance 工具新增期貨帳戶支援：

使用範例

// 查詢所有帳戶持倉（預設）
{"account_type": "all"}

// 只查詢股票帳戶
{"account_type": "stock"}

// 只查詢期貨帳戶
{"account_type": "futures"}

回應格式差異

• 股票持倉：包含股數、張數計算和持股成本分析
• 期貨持倉：包含合約數量、保證金和損益資訊
• 期貨餘額：額外提供維持保證金、初始保證金等期貨特有欄位

常用命令

開發環境設置

# 安裝開發相依套件
uv sync --extra dev

# 設定環境變數
export SHIOAJI_API_KEY=your_api_key
export SHIOAJI_SECRET_KEY=your_secret_key
export SHIOAJI_TRADING_ENABLED=false  # 預設唯讀模式