fin-data-mcp CLAUDE.md

fin-data-mcp-server — agent guide

A standalone Model Context Protocol server exposing free financial market data across 13 categories. Lives inside the cc-stack workspace but is its own Node package with its own deps. 83 no-key tools (15 providers) always on; optional free keys unlock 7 more providers (up to 110 tools / 22 providers).

Stack / runtime

• TypeScript + ESM ("type": "module", module: NodeNext). Relative imports MUST use the .js extension (e.g. import { httpGet } from "../lib/http.js").
• @modelcontextprotocol/sdk over stdio (StdioServerTransport).
• Zod v3 (^3.25) — pinned for MCP SDK inputSchema (ZodRawShape) compat. This deliberately diverges from the parent repo's Zod 4 convention; do not "upgrade" it without checking the SDK still accepts the raw-shape schemas.
• No axios/extra HTTP libs — uses native fetch via src/lib/http.ts.

Commands

npm run build        # tsc → dist/   (run before considering work done)
npm run dev          # tsx watch src/index.ts
npm start            # node dist/index.js (stdio)
npx tsc --noEmit     # typecheck (strict + noUncheckedIndexedAccess)
npx tsx scripts/smoke.ts        # core no-key endpoints
npx tsx scripts/smoke-full.ts   # broad sample incl. expanded + chained discovery
npx tsx scripts/mcp-test.ts     # MCP handshake: tools/list, resource, a tool call

Architecture

src/
  index.ts        # stdio entry (never write to stdout — logs go to stderr)
  server.ts       # createServer(): instructions, registers tools w/ annotations,
                  #   structuredContent + CHARACTER_LIMIT truncation, error mapping,
                  #   the fin-data://catalog resource
  config.ts       # all env config (all optional)
  constants.ts    # CHARACTER_LIMIT (~25k), DEFAULT_PAGE_SIZE
  lib/
    http.ts       # httpGet(url, {params,headers,accept,retries,timeoutMs}); HttpError;
                  #   formatHttpError() → actionable messages; sends Accept-Language: en
    cache.ts      # cached(key, fn, ttlMs) in-memory TTL
    tool.ts       # ToolDef + tool() helper (applies read-only annotations centrally)
  providers/
    index.ts      # PROVIDERS registry → allTools (enabled only) + catalog
    <provider>.ts # one file per source; exports `<name>Tools: ToolDef[]`