# mcp-fc

MCP server exposing the `financecentre` MongoDB (stocks, prices, SEC financials,
insider trades, 13F funds, congressional trades, macro series, news) to AI agents.
Streamable HTTP (stateless), scoped API keys, token-efficient pipe-table output.

## Quick start

    cp .env.example .env   # set MCP_API_KEYS or MCP_AUTH_DISABLED=true for dev
    npm ci
    npm run ensure-indexes
    npm run dev            # or: npm run build && npm start

## Tools (v1, read-only)

search_securities · get_security_snapshot · screen_stocks · get_price_history ·
get_financials · get_insider_trades · search_funds · get_fund_holdings ·
get_political_trades · get_macro_series · search_news · get_news_for_geocoding

Write tools (scope `write`): submit_news_locations

## Auth

Two parallel mechanisms on `POST /mcp`:

- **API keys** (`MCP_API_KEYS`) — for Claude Code, curl, n8n: `Authorization: Bearer <key>`.
- **OAuth 2.1** (enabled when `MCP_JWT_SECRET` is set) — for claude.ai custom
  connectors (web/desktop/mobile). Login uses finanz-copilot accounts
  (`financecentre.users`, read-only); role `admin` → scopes `read write`,
  `member` → `read`. JWT access tokens (1 h), rotating refresh tokens (30 d),
  PKCE + dynamic client registration. OAuth data lives in the `mcp-fc` database.

## GeoNews (map feature)

`newsGeo` stores one location per news (GeoJSON Point, `[lon, lat]`, WGS84 —
MapKit: `CLLocationCoordinate2D(latitude: c[1], longitude: c[0])`) plus
denormalized news fields (title, sourceName, link, image, pubDate, category),
a `relevance` score and an optional pin `summary`. Agent loop:
`get_news_for_geocoding` (read) → locate + score → `submit_news_locations`
(**write scope**). Not-locatable news are stored as `locatable: false` markers.

`relevance` (0–1, required for located items) rates the event's significance —
0.95+ historic shock (9/11, market crash), 0.8+ major (central-bank surprise,
war escalation), 0.6+ notable, 0.3 routine, <0.1 trivial. The app scales pin
size/color with it and raises the threshold when zoomed out; indexes
`{location:2dsphere}` and `{relevance:-1, pubDate:-1}` back both query shapes.
REST integration: [docs/geonews-restapi-integration.md](docs/geonews-restapi-integration.md).

## Adding a feature

1. Create `src/features/<name>/index.ts` exporting a `FeatureModule`.
2. Add it to `allFeatures` in `src/features/index.ts`.
3. Add an integration test in `tests/integration/`.

Write tools: set `requiredScope: 'write'` and grant the scope to a key.

Design: docs/superpowers/specs/2026-07-14-mcp-financecentre-design.md
Deployment: deploy/DEPLOY.md

## Tests

    npm test   # unit + integration + e2e (needs local MongoDB with financecentre)