flowchart LR
    C["MCP Client<br/>Claude Desktop · Cursor · Goose"]
    OAuth["OAuth 2.1 Resource Server<br/>JWT validation · alg allowlist · PKCE"]

    subgraph core["FastMCP Server — MCP spec 2025-11-25"]
        Router["Tool router +<br/>MCP Apps registry"]
        EDGAR["edgar.list_filings<br/>edgar.company_facts"]
        FRED["fred.series"]
        Polygon["polygon.aggregates"]
        Extractor["tenk.extract_section<br/>citation-grounded 10-K"]
        UI["TenKSummaryCard<br/>inline UI · citation pills"]
        Evals["Eval harness<br/>smoke · full · offline"]
    end

    Cache[("SQLite cache · 24h TTL")]
    Anthropic["Anthropic Messages API"]

    C ==>|"Bearer JWT"| OAuth
    OAuth -.->|"401 + WWW-Authenticate"| C
    OAuth ==>|"authenticated"| Router
    Router --> EDGAR
    Router --> FRED
    Router --> Polygon
    Router --> Extractor
    Extractor --> UI
    Extractor ==>|"Sonnet 4.6 + Citations API"| Anthropic
    Evals ==>|"Opus 4.7 judge"| Anthropic
    Evals -.->|"replays tool calls"| Router
    EDGAR --> Cache
    FRED --> Cache
    Polygon --> Cache
    Extractor --> Cache

    classDef client fill:#15324f,stroke:#4f8cff,color:#eaf1ff
    classDef gate fill:#3a2c12,stroke:#ffb347,color:#ffe9c7
    classDef tool fill:#16233a,stroke:#2d3a4f,color:#dce6f5
    classDef key fill:#1d2f4d,stroke:#4f8cff,color:#eaf1ff
    classDef store fill:#16301f,stroke:#2ee08a,color:#d6f5e3
    classDef ext fill:#271d3d,stroke:#9b86ff,color:#ece6ff

    class C client
    class OAuth gate
    class Router,EDGAR,FRED,Polygon,UI tool
    class Extractor,Evals key
    class Cache store
    class Anthropic ext

git clone https://github.com/SebAustin/mcp-financial-data.git
cd mcp-financial-data
cp .env.example .env   # fill in API keys
make setup             # uv sync + pre-commit install
make ci                # lint + typecheck + tests + smoke eval (offline)
make serve             # run the MCP server on $MCP_HOST:$MCP_PORT

uv run python -m mcp_financial_data.evals.harness --full --offline

uv run python -m mcp_financial_data.evals.harness --full --budget 5 --min-judge-score 0.85

src/mcp_financial_data/      # the package
  server.py                  # FastMCP entrypoint
  auth/oauth.py              # OAuth 2.1 RS primitives
  tools/{edgar,fred,polygon} # async API clients
  extractors/tenk.py         # citation-grounded 10-K extractor
  apps/ui.py                 # MCP Apps inline UI registration
  evals/{harness,metrics}    # eval harness (--smoke / --full / --offline)
tests/{unit,integration}     # pytest, 85% gate, integration skipped by default
evals/cases/seed.jsonl       # 5 hand-authored eval cases
evals/runs/                  # per-SHA harness output (gitignored)
docs/adr/                    # MADR architecture decisions
.github/                     # CI templates + issue/PR templates + dependabot