fubon-api-mcp-server AGENTS.md

Repository Guidelines

AGENTS.md

• Do not preserve backward compatibility. Remove obsolete paths instead of adding compatibility layers, fallbacks, or migrations.
• Choose the simplest implementation that fully meets the current requirements. Avoid speculative abstractions, configuration, and indirection.
• Grow the system in layers. Start from the smallest version that works end to end, and add each new capability on top of a product that already works. Never trade a working product for unfinished complexity.
• Keep components modular and concerns clearly separated.
• Prefer established, well-maintained libraries when they reduce overall complexity or improve reliability. Do not reimplement common functionality without a clear reason.
• Lean on the dependencies already in the project before writing your own implementation or adding packages. Do not assume a library lacks a capability without checking its documentation and types.
• Make architectural decisions for the long term. Do not accept a stopgap that only works for now and is meant to be replaced later.

Project Structure & Module Organization

• fubon_api_mcp_server/ contains the Python MCP server. server.py is the entry point; service modules cover trading, market data, accounts, reports, analysis, and indicators. Shared helpers live in config.py, enums.py, and utils.py.
• tests/ contains pytest tests and SDK-mocking fixtures in tests/conftest.py. examples/ contains manual API examples, and vscode-extension/ contains the VS Code extension.
• scripts/ holds PowerShell release/version tooling; specs/ holds implementation plans. data/, assets/, and wheels/ are runtime or distribution assets.

Build, Test, and Development Commands

Use Python 3.10–3.13 and install the editable development package:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

• python -m fubon_api_mcp_server.server starts the MCP server; configure FUBON_* variables from .env.example first.
• python -m pytest runs the test suite; target a test with python -m pytest tests/test_account_service.py -v.
• python -m pytest --cov=fubon_api_mcp_server --cov-report=html creates coverage output in htmlcov/.
• ./scripts/quick_check.ps1 runs the fast formatting, lint, and smoke-test checks on Windows.
• python -m build followed by python -m twine check dist/* validates a package build.