stock-intelligence-mcp AGENTS.md

Stock Intelligence MCP — Agent Instructions

What This Is

An MCP App Server for stock market data with AI-driven dynamic charting. 10 tools: 1 interactive charting tool (stock_app with 7 views and inline controls), 7 inline data tools (for text responses), and 2 utility tools. Built with FastMCP (Python). All data from Financial Modeling Prep (FMP) free tier (250 calls/day).

Key Architectural Decision: Two Modes

Visual mode — stock_app is the single charting tool. It has meta={"ui": {"resourceUri": APP_RESOURCE_URI}} which opens the MCP App. The AI picks the view based on the user's question. The chart renders with inline controls (period, chart type, statement type) so users can adjust without a new AI call.

Inline mode — 7 data tools (stock_quote, stock_price_history, etc.) return structured data for text responses. No meta, no UI. The AI formats the data in its response.

When to use which:

• User says "show me", "chart", "visualize" → stock_app
• User says "what's the price", "tell me", "how much" → data tool
• User asks for numbers then says "chart that" → stock_app with same params

Architecture

src/stock_intelligence/
├── __init__.py        # Package init — exports get_app_html()
├── server.py          # FastMCP server — 10 tools + MCP App resource
├── core/
│   ├── views.py       # View renderers + inline data functions (public API)
│   ├── scoring.py     # Quote summarization, number formatting
│   └── clients/
│       └── fmp.py     # FMP API client — free tier endpoints only
└── ui/
    └── app.html       # Interactive chart renderer — canvas-based, zero deps, inline controls

stock_app Views & Parameters

stock_app(
    symbol="AAPL",       # Stock ticker. Ignored for market view.
    view="chart",        # chart|quote|financials|earnings|analyst|valuation|market
    period="6m",         # Chart view: 1m|3m|6m|1y|2y|5y
    chart_type="",       # Override rendering. Leave empty for best default.
    statement="income",  # Financials view: income|balance|cashflow
    fiscal_period="quarter",  # Financials view: quarter|annual
)