Troubleshooting

故障排除

Server 啟動後立即退出

缺少必要環境變數

傳統登入必須有 FUBON_USERNAME、FUBON_PASSWORD、FUBON_PFX_PATH。API-Key 登入必須有 FUBON_USERNAME、FUBON_API_KEY、FUBON_PFX_PATH。

PowerShell 檢查是否「有設定」而不輸出值：

'FUBON_USERNAME','FUBON_PASSWORD','FUBON_API_KEY','FUBON_PFX_PATH' |
  ForEach-Object { [pscustomobject]@{ Name = $_; IsSet = ($null -ne (Get-Item "Env:$_" -ErrorAction SilentlyContinue)) } }

不要把變數實際內容貼到 Issue。

FUBON_MCP_PORT 或 boolean 無效

Port 必須介於 1–65535。boolean 只能使用 true/false、1/0、yes/no、on/off。

fubon_neo 無法安裝或 import

• 確認 Python 為 3.10–3.13。
• 使用對應作業系統與 CPU 的 2.2.8 wheel。
• Windows 使用 win_amd64；Apple Silicon 使用 macosx_11_0_arm64。
• 執行 python -m pip show fubon-neo 與 python -m pip check。
• 確認 MCP Host 使用的 Python 與你安裝套件的 Python 是同一個 executable。

TA-Lib 安裝問題

TA-Lib 可能需要平台 binary。先確認目前 Python 版本有可用 wheel；若沒有，依 TA-Lib 官方方式安裝 native library，再重建虛擬環境。不要為了解決安裝問題移除分析依賴後仍宣稱分析工具可用。

登入失敗

• 確認 PFX 存在、可讀且密碼正確。
• API-Key 登入要使用網頁匯出的憑證，且呼叫形狀不含 API Secret。
• 同時設定 API Key 與 password 時會優先走 API-Key；若想測傳統登入，移除 process 中的 FUBON_API_KEY。
• 確認 API Key 狀態、權限與 IP 限制。
• 時鐘、網路、富邦服務狀態與憑證有效期也可能影響登入。

Client 看不到工具

1. 直接執行 python -m fubon_api_mcp_server.server，確認不是啟動失敗。
2. VS Code Extension 首次安裝後執行 Fubon MCP: Configure Fubon MCP Server。
3. 檢查使用者層級 mcp.json 的 command 指向正確 Python。
4. 重新載入 Host。
5. 確認 client 支援 MCP 2026-07-28 discovery。
6. 預期數量為 72 tools、12 prompts。

股票／期貨行情服務未初始化

這通常表示登入後的 init_realtime() 或 REST client 建立失敗。不要只重試單一 tool；先檢查 server 啟動 log、event reports 與登入流程。SDK 登入成功後必須呼叫 sdk.init_realtime() 才能安全使用 market data clients。

historical_candles 沒有預期資料

• 日期必須是 YYYY-MM-DD。
• 確認商品在期間內有交易。
• adjusted=true、非日線或 fields 查詢不走 SQLite 快取。
• 檢查 FUBON_DATA_DIR/stock_data.db 的寫入權限與磁碟空間。
• API 更新失敗時服務可能繼續使用現有 cache；檢查 message、最後資料日期與實際資料範圍。

insufficient_data

量化工具通常需要至少 60 筆共同有效報酬。常見原因：空倉、商品歷史不足、不同商品共同交易日不足、行情過期或最佳化限制無可行解。增加正式資料、移除缺資料商品或調整合法限制；不要補假資料。

富邦流量控管

遇到 業務系統流量控管：

• 唯讀查詢：停止高頻探測，採有限次數的 exponential backoff，並保留最後錯誤。
• 寫入工具：先查委託、成交與 callback，確認結果後才決定下一步。
• 批次：降低 concurrency／批次大小，逐筆保存結果。

送單、改單或取消逾時

不要立即重送。依 回應與錯誤處理 的 outcome_unknown 流程，使用 get_order_results_detail、get_filled_reports／get_filled_history 與條件單查詢做 reconciliation。

中文顯示亂碼

Server 啟動時會將 stdout／stderr 設為 UTF-8。若 Host 仍顯示亂碼：

• 確認 Host 以 UTF-8 解碼 stdio。
• PowerShell 可先設定 $OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new()。
• 不要在 protocol stdout 加入其他編碼的 wrapper output。

回報 Issue 前

提供：版本／commit、Python 版本、OS、transport、tool name、去識別化的 status 與 message、重現步驟、是否為 read-only。不要提供帳號、密碼、API Key、PFX、完整委託資料或 .env。