Architecture

架構

Fubon API MCP Server 採單一 MCP runtime 搭配領域 service classes。server.py 負責生命週期、認證、transport、prompts 與共享狀態；各 service 在建構時將 methods 註冊到同一個 MCPServer。

flowchart LR
    Host[MCP Host] -->|stdio / Streamable HTTP / SSE| Server[MCPServer]
    Server --> Market[MarketDataService]
    Server --> Trading[TradingService]
    Server --> Account[AccountService]
    Server --> Reports[ReportsService]
    Server --> Analysis[AnalysisService]
    Market --> StockREST[Stock REST]
    Market --> FutOptREST[Futures and Options REST]
    Trading --> StockSDK[Stock Trading SDK]
    Account --> Accounting[Accounting SDK]
    Analysis --> StockREST
    Analysis --> Accounting
    StockSDK --> Fubon[富邦證券 API]
    StockREST --> Fubon
    FutOptREST --> Fubon
    Accounting --> Fubon
    Callbacks[SDK callbacks] --> Reports
    Market --> SQLite[(stock_data.db)]

Loading

主要模組

路徑	責任
fubon_api_mcp_server/server.py	MCPServer、prompts、認證生命週期、transport、callback、共享狀態
market_data_service.py	台股／期貨選擇權 REST、股務事件、行情正規化、SQLite 快取
trading_service.py	普通單、改刪單、批次單、條件單、當沖、分時分量、移動鎖利
account_service.py	accounting、庫存、餘額、交割、已／未實現損益
reports_service.py	讀取 process-local callback buffers
analysis_service.py	正式資料唯讀分析與技術指標整合
quant_analysis.py	報酬矩陣、VaR/CVaR、最佳化、配對統計
indicators.py、indicators_advanced.py	TA-Lib 技術指標封裝
utils.py	帳戶驗證、SDK safe calls、結果正規化、憑證匯出 helper
enums.py	字串到 fubon_neo.constant enum 的轉換
config.py	SDK／accounts／REST references、資料目錄與 logging

啟動序列

sequenceDiagram
    participant P as Process
    participant S as MCPServerState
    participant F as FubonSDK
    participant M as MCPServer
    P->>P: load_dotenv and validate env
    P->>S: initialize_sdk(...)
    S->>F: login or apikey_login
    S->>F: init_realtime()
    S->>F: set_on_order / changed / filled / event
    P->>M: construct and register five services
    P->>M: run selected transport

Loading

登入成功後才會建立 services。這表示 tools 的 runtime availability 依賴認證與初始化；只 import server 不等同於完成可用服務。

MCP 註冊模型

每個 service 的 _register_tools() 使用：

self.mcp.tool()(self.some_tool)

目前 methods 的公開 signature 通常是 some_tool(args: Dict) -> dict，因此 MCP discovery 的最外層 schema 是一個 args object；Pydantic 業務 schema 在 method 內驗證。新增功能時應維持現有 client contract，除非專案已明確決定新的統一介面。

狀態與生命週期

MCPServerState 是 process singleton，持有：

• sdk、accounts、reststock、restfutopt。
• local resource cache 與 TTL metadata。
• realtime subscription／stream placeholders。
• 四種 callback buffers。

初始化後也會將 references 指派到 config 模組，供現有 helpers 與 tests patch。登出時清除 SDK references、快取、WebSocket references、subscriptions 與 callback buffers。

帳戶驗證邊界

需要帳戶的 tools 應先透過 validate_and_get_account(account) 取得 SDK account object。這是交易安全與 test mocking 的共同邊界；新增交易 tool 不得直接用呼叫者字串跳過驗證。

資料正規化

官方 SDK endpoint 的回傳並不一致：

• 台股 REST 常見 dict／list。
• 交易與 accounting 常見 is_success、data、message object。
• 期貨／選擇權可能在 top-level 與 .data 之間使用不同形狀。
• 股務事件保留 REST wire shape。

解析與欄位正規化應留在對應 service，不要搬到 server.py 或 MCP Host。

歷史行情快取

MarketDataService 在 FUBON_DATA_DIR/stock_data.db 維護 stock_historical_data。寫入使用 INSERT OR REPLACE，主鍵語意為 symbol＋date。快取只服務未還原日線完整欄位；不同 timeframe、adjusted 或 fields 查詢不共享。

主動回報

SDK callback 事件加上接收時間後存入四個 FIFO list，每類最多 10 筆。這是 UI／Agent 近期狀態用途，不是 durable event store，也不保證跨重啟保存。

Transport

• stdio：直接呼叫 mcp.run("stdio")。
• Streamable HTTP：可設定 host、port、path、JSON response、stateless。
• SSE：使用獨立 SSE 與 message paths。

未知 transport、無效 port 或無效布林設定會 fail closed。