creditkarma-mcp: Instructions file for Claude Code

creditkarma-mcp

MCP server for Credit Karma. Syncs transactions from the Credit Karma GraphQL API into a local SQLite database and exposes query tools via stdio transport.

Commands

npm run build          # Compile TypeScript → dist/
npm test               # Run tests (vitest)
npm run test:watch     # Watch mode
npm run test:coverage  # Coverage report

Run locally (requires built dist):

CK_COOKIES=xxx node dist/index.js

Tool naming

All tools are prefixed ck_ (e.g. ck_sync_transactions, ck_list_transactions).

Architecture

src/
  index.ts              # MCP server entry point — registers all tools, starts stdio transport
  auth.ts               # resolveAuth() + loadAuthIntoClient() — Pattern A three-path priority
  client.ts             # Credit Karma GraphQL client with auto-refresh; OPERATIONS = the balance ops + their app identities
  db.ts                 # SQLite schema, migrations (v2 balances, v3 credit-report matching), upsert helpers
  http.ts               # boundedFetch — the ONE transport (mcp-utils fetchBounded: timeout over the body read, cancellation, 16 MiB cap); names the host on a refused connection; shared USER_AGENT + REQUEST_TIMEOUT_MS
  vault.ts              # Intuit vault (linked-account balances): idxAuth token → POST /v2/search/connections
  creditReport.ts       # Credit-report parsing (getCreditReportHistory → getCreditReport)
  matching.ts           # Pair credit-report rows with the linked accounts they duplicate
  json.ts               # Narrowing helpers for untyped CK / Intuit JSON
  accountId.ts          # Synthesize a stable account id from provider + last-4 (CK returns empty ids)
  queryHash.ts          # Re-read CK's persisted-query hash from its web bundle when the compiled one goes stale
  debug.ts              # CK_DEBUG=1 stderr tracing of auth + refresh (names, JWT timings, redacted bodies — never values)
  transaction.graphql   # Documentation of the GetTransactions fields we read (never sent)
  tools/
    auth.ts             # ck_set_session, ck_forget_session
    healthcheck.ts      # ck_healthcheck — hop report: credential lookup → token validity → refresh → probe
    sync.ts             # ck_sync_transactions
    query.ts            # ck_list_transactions, ck_get_recent_transactions,
                        #   ck_get_spending_by_category, ck_get_spending_by_merchant,
                        #   ck_get_account_summary
    balances.ts         # ck_get_account_balances + refreshBalances() (run once by every sync)
    sql.ts              # ck_query_sql
    hints.ts            # moneyMeta() — `_meta.mint` context-group hints (group `money`; ck_list_transactions is the canonical what's-new read, with view: brief)