fubon-api-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

An MCP (Model Context Protocol) server wrapping the Fubon Securities Python SDK (fubon_neo) to expose Taiwan stock trading, market data, account management, and quantitative analysis as AI-callable tools.

Commands

Run tests

# All tests
python -m pytest -q

# Single test class
python -m pytest tests/test_market_data_service.py::TestGetIntradayFutOptTickers -v

# With coverage
python -m pytest --cov=fubon_api_mcp_server --cov-report=html --cov-report=term-missing

Lint and format

# Lint (errors only)
flake8 fubon_api_mcp_server tests --count --select=E9,F63,F7,F82 --show-source --statistics

# Format check
black --check --diff fubon_api_mcp_server tests --exclude fubon_api_mcp_server/_version.py

# Apply formatting
black .
isort fubon_api_mcp_server tests

Type check and security

mypy fubon_api_mcp_server
bandit -r fubon_api_mcp_server -f json -o bandit-report.json

Start server

python -m fubon_api_mcp_server.server

Build and validate

python validate_server.py   # quick sanity check
python -m build             # produce dist/
twine check dist/*

Release (PowerShell)

.\scripts\release.ps1               # patch bump
.\scripts\release.ps1 -BumpType minor

Architecture

Entry point: fubon_api_mcp_server/server.py creates a FastMCP instance and instantiates all service classes. Each service calls _register_tools() in its __init__, decorating its methods with @self.mcp.tool() against the shared FastMCP instance. After registration, mcp.run() starts the server over stdio.

Service classes:

• trading_service.py — place/modify/cancel orders, condition orders, TPSL, trailing profit, time-slice splits
• market_data_service.py — REST stock and futures/options: intraday quotes, snapshots, candles, movers, actives, historical CSV cache, SQLite local DB
• account_service.py — balance, inventory, unrealized/realized PnL, margin, settlement
• reports_service.py — surfaces SDK callbacks (order fill/change/event) buffered in global lists in server.py
• analysis_service.py — Phase 3 quant: portfolio VaR, stress tests, performance attribution, arbitrage detection, sentiment index