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
  db.ts                 # SQLite schema and upsert helpers (incl. backfillAccountIds)
  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
  transaction.graphql   # GraphQL query for transactions
  tools/
    auth.ts             # ck_set_session
    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
    sql.ts              # ck_query_sql

Each tool file exports tool definitions (MCP schemas) and a handler. index.ts aggregates all tools and routes by name.

Auth resolution (Pattern A template)

src/auth.ts is the canonical "browser-bootstrap + Node-direct" auth shape shared with ofw-mcp, resy-mcp, opentable-mcp, signupgenius-mcp, zola-mcp, … Sibling MCPs follow the same selector — keep it flat, the path-selection explicit, and the error messages actionable.

Three paths in priority order: