creditkarma-mcp 2.0.9 → 2.1.4

package/README.md

@@ -21,7 +21,29 @@ Ask Claude things like:
 - [Claude Desktop](https://claude.ai/download) or [Claude Code](https://claude.ai/code)
 - [Node.js](https://nodejs.org) 18 or later
 - A Credit Karma account
-- [Google Chrome](https://www.google.com/chrome/) — used once for the scripted auth flow (optional; you can copy the cookie manually instead)
+- For the no-env-var path: the [fetchproxy 0.3.0 Chrome / Safari extension](https://github.com/chrischall/fetchproxy)
+
+## Acknowledgement of Terms
+
+By using this MCP server, you acknowledge and agree to the following:
+
+**1. This server accesses your own Credit Karma account.** Every request is dispatched through your own signed-in browser tab via the fetchproxy extension. **You** are the one logged in. It does not — and cannot — access anyone else's account.
+
+**2. [Credit Karma's Terms](https://www.creditkarma.com/about/terms) govern your use of this server**, just as they govern your direct use of creditkarma.com. The clauses most relevant here:
+
+> You must not sell, transfer, or assign your account to anyone else… you may not allow anyone else to log into our Services as you.
+
+CK does contemplate third-party data retrieval at the user's direction (Section 3.7). There is no explicit anti-scraping clause in the membership agreement; Section 4.1 restricts copying or distributing CK content without express prior written consent.
+
+You are agreeing to those terms — read by the maintainer 2026-05-23 — every time you invoke a tool in this server. Critically: this server runs **as you**, not as a third party logging in on your behalf. You direct the tool.
+
+**3. Personal, non-commercial use only.** This project is not affiliated with, endorsed by, sponsored by, or in partnership with Intuit, Credit Karma, or any financial institution. It is a personal automation tool that reads your transaction history, spending categories, and account snapshots — the same data Credit Karma already shows you in their app. Do not use it on someone else's account, do not redistribute their content, and do not use it to make trading or lending decisions on behalf of others.
+
+**4. This server may break.** Credit Karma rotates its internal endpoints; what works today may 404 tomorrow. This is the nature of unofficial integrations.
+
+**5. You accept full responsibility** for any consequences of using this server in connection with your Credit Karma account — rate limiting, account warnings, suspension, or any enforcement action Intuit takes. If Credit Karma objects to your use, stop using this server. **Do not commit your `.env` to git** — your CK session/auth artifacts are credentials, and the Membership Agreement holds you responsible for their confidentiality.
+
+This section is the maintainer's good-faith summary of the terms — it is not legal advice and does not modify or supersede Credit Karma's actual Membership Agreement.
 
 ## Installation
 
@@ -80,38 +102,31 @@ Fully quit and relaunch. Then ask: *"Sync my Credit Karma transactions"*.
 
 Credit Karma uses short-lived JWTs. This server handles automatic token refresh — you only need to set up credentials once (or when your session expires).
 
-### Getting your credentials
+`creditkarma-mcp` tries three auth paths in priority order; whichever succeeds first is used. Existing setups keep working unchanged.
 
-#### Option A — scripted (recommended)
+1. **`CK_COOKIES` env var (legacy).** Set the full Cookie header in your Claude Desktop config or `.env`. This is the path shown in the config above.
+2. **Cached session from `ck_set_session`.** Once called, the tool persists the Cookie header to `.env` as `CK_COOKIES` — so subsequent runs collapse into path 1.
+3. **fetchproxy fallback (no env vars needed — easiest onboarding).** When neither is configured, the server reads `CKAT` + `CKTRKID` cookies once at startup from your already-signed-in `creditkarma.com` tab via the [fetchproxy](https://github.com/chrischall/fetchproxy) browser extension. After that one read, all CK API calls go directly from Node — the extension is **not** in the request hot path. Install the fetchproxy extension (Chrome Web Store / Safari `.dmg`), sign into [creditkarma.com](https://www.creditkarma.com), and the MCP just works.
 
-```bash
-npm run auth               # prints the Cookie header to the console
-npm run auth -- .env       # writes CK_COOKIES=<header> to .env
-```
+Set `CK_DISABLE_FETCHPROXY=1` to opt out of the fallback (turns missing credentials into a hard error — useful in headless CI).
 
-Launches Chrome with a dedicated profile at `~/.creditkarma-mcp/chrome-profile`, waits for you to sign in at creditkarma.com, then captures the full session Cookie header (CKAT carries the access + refresh JWTs; CKTRKID and friends are needed by the refresh endpoint). Either prints it (for pasting into Claude Desktop / MCPB) or writes it to the env file you pass at mode 0600 (owner-only). Requires Google Chrome installed locally; on first run the script installs `puppeteer-core`, `puppeteer-extra`, and `puppeteer-extra-plugin-stealth` (a few MB, not added to `package.json`).
+### Getting your credentials (env-var path)
 
-#### Option B — manual paste (secure prompt)
+#### Option A — fetchproxy extension (recommended)
 
-```bash
-npm run auth -- --manual           # prompts for the cookie, prints CK_COOKIES
-npm run auth -- --manual .env      # prompts for the cookie, writes to .env
-```
+1. Install the [fetchproxy 0.3.0 extension](https://github.com/chrischall/fetchproxy) (Chrome Web Store or Safari `.dmg`).
+2. Sign into [creditkarma.com](https://www.creditkarma.com) in that browser.
+3. Leave `CK_COOKIES` **unset** in your Claude config.
 
-Use this if the scripted flow hits Intuit/Akamai bot detection (sign-in returns "A technical issue has unexpectedly occurred"). Grab the Cookie header from your normal Chrome (Option C below), then paste it at the prompt. Input is **not echoed** — paste, press Enter.
+The MCP reads the HttpOnly `CKAT` + `CKTRKID` cookies via `chrome.cookies.get` on the first tool call, then operates direct-to-API from Node. To re-auth (e.g. after Credit Karma signs you out), just sign back in to creditkarma.com.
 
-#### Option C — manual (DevTools)
+#### Option B — manual (DevTools)
 
 1. Log in to [creditkarma.com](https://www.creditkarma.com) in Chrome
 2. Open DevTools → **Network** → click any request to creditkarma.com → **Request Headers**
 3. Right-click the `cookie` header → **Copy value**
 
-### Setting credentials
-
-Either of these works:
-
-- Paste the value from `npm run auth` into `CK_COOKIES` in your `.env` or Claude config
-- Or call `ck_set_session` from within Claude with the Cookie header value
+Then either paste into `CK_COOKIES` in your Claude config / `.env`, or call `ck_set_session` from within Claude with the Cookie header value.
 
 The server extracts the access and refresh JWTs from the `CKAT` cookie inside the header and refreshes the access token automatically as needed.
 
@@ -119,7 +134,9 @@ The server extracts the access and refresh JWTs from the `CKAT` cookie inside th
 
 - **Access token**: ~15 minutes (auto-refreshed transparently)
 - **Refresh token**: ~8 hours
-- When the refresh token expires, re-run `npm run auth` (or grab a fresh Cookie header from DevTools) and either update `CK_COOKIES` or call `ck_set_session`
+- When the refresh token expires:
+  - **fetchproxy path:** sign back into creditkarma.com — the MCP re-reads fresh cookies on the next tool call.
+  - **env-var path:** grab a fresh Cookie header from DevTools and update `CK_COOKIES` (or call `ck_set_session`).
 
 ## Available tools
 
@@ -156,14 +173,19 @@ sync_state   (key, value)
 
 | Env var | Description | Default |
 |---------|-------------|---------|
-| `CK_COOKIES` | Full Cookie header from a signed-in creditkarma.com request | *(required)* |
+| `CK_COOKIES` | Full Cookie header from a signed-in creditkarma.com request | *(unset — falls back to fetchproxy)* |
+| `CK_DISABLE_FETCHPROXY` | Set to `1` to skip the fetchproxy fallback (headless / CI) | *(unset)* |
 | `CK_DB_PATH` | Path to SQLite database file | `~/.creditkarma-mcp/transactions.db` |
 
 ## Troubleshooting
 
-**"TOKEN_EXPIRED"** — your refresh token has expired. Re-run `npm run auth` (or grab a fresh Cookie header) and update `CK_COOKIES` or call `ck_set_session`.
+**"CK auth: set CK_COOKIES, or call the ck_set_session MCP tool, or install the fetchproxy extension…"** — neither auth path is configured. Either fill in `CK_COOKIES` in your Claude config, or install the [fetchproxy extension](https://github.com/chrischall/fetchproxy) and sign into `creditkarma.com` in your browser.
+
+**"TOKEN_EXPIRED"** — your refresh token has expired. Sign back into creditkarma.com (fetchproxy path) or grab a fresh Cookie header from DevTools and update `CK_COOKIES` / call `ck_set_session`.
+
+**"fetchproxy fallback failed"** — the env-var path wasn't configured and the extension couldn't be reached. Confirm the fetchproxy extension is installed, signed into Credit Karma, and that it's running (open the extension popup). To disable the fallback, set `CK_DISABLE_FETCHPROXY=1`.
 
-**Sync returns 0 transactions** — check that your `CK_COOKIES` value is fresh. The refresh token inside the CKAT cookie expires after ~8 hours.
+**Sync returns 0 transactions** — check that your auth is fresh. The refresh token inside the CKAT cookie expires after ~8 hours.
 
 **Tools not appearing** — fully quit and relaunch Claude Desktop. In Claude Code, run `/mcp` to check server status.
 
@@ -171,9 +193,10 @@ sync_state   (key, value)
 
 ## Security
 
-- Credentials are stored only in your local `.env` file (gitignored) or Claude config
-- `.env` is written at mode 0600 (owner read/write only) by both `npm run auth` and `ck_set_session`
+- Credentials are stored only in your local `.env` file (gitignored), Claude config, or your browser's cookie jar (fetchproxy path)
+- `.env` is written at mode 0600 (owner read/write only) by `ck_set_session`
 - `ck_set_session` refuses to save a refresh token whose JWT `exp` is already in the past — prevents stale credentials from polluting `.env`
+- The fetchproxy path doesn't persist anything to disk — cookies are read into memory once per MCP run, directly from the user's browser via `chrome.cookies.get`
 - The server never logs credentials; warnings go to stderr only (stdout is reserved for the MCP JSON-RPC stream)
 - Only `SELECT` queries are permitted via `ck_query_sql` — no writes to Credit Karma; the underlying `node:sqlite` `prepare()` also rejects multi-statement input
 
@@ -196,6 +219,7 @@ Changes land via PR, including for solo work — release notes are generated fro
 
 ```
 src/
+  auth.ts               resolveAuth() — three-path priority (CK_COOKIES env / ck_set_session cache / fetchproxy), plus loadAuthIntoClient()
   client.ts             Credit Karma GraphQL client (auto-refresh, JWT helpers, cookie parser)
   index.ts              MCP server entry point; bootstraps tokens from CK_COOKIES
   db.ts                 SQLite schema, migrations, and upsert helpers
@@ -207,13 +231,11 @@ src/
                         ck_get_spending_by_category, ck_get_spending_by_merchant,
                         ck_get_account_summary
     sql.ts              ck_query_sql — SELECT-only escape hatch
-scripts/
-  setup-auth.mjs        npm run auth — Puppeteer flow + manual paste fallback
 tests/
   helpers.ts            Shared test helpers (fakeServer, makeJwt)
+  auth.test.ts          resolveAuth + loadAuthIntoClient (mocks @fetchproxy/bootstrap)
   client.test.ts
   db.test.ts
-  setup-auth.test.ts
   tools/
     auth.test.ts
     sync.test.ts

package/SKILL.md

@@ -56,28 +56,29 @@ Then add to `.mcp.json`:
 
 Or use a `.env` file in the project directory with `CK_COOKIES=<value>`.
 
-### Getting CK_COOKIES
+### Getting CK_COOKIES (optional)
 
-**Scripted (recommended — source install):**
-```bash
-npm run auth               # prints the Cookie header to the console
-npm run auth -- .env       # writes CK_COOKIES=<header> to .env
-```
+Three onboarding paths, in priority order:
+
+**1. fetchproxy extension (easiest — no env vars):** Install the [fetchproxy 0.3.0 extension](https://github.com/chrischall/fetchproxy), sign into creditkarma.com once, and leave `CK_COOKIES` **unset**. The MCP reads HttpOnly `CKAT` + `CKTRKID` cookies on the first tool call via `chrome.cookies.get`, then operates direct-to-API from Node.
 
-Launches Chrome with a dedicated profile, waits for sign-in at creditkarma.com, then captures the full session Cookie header (CKAT carries the access + refresh JWTs; CKTRKID and friends are needed by the refresh endpoint). Use the printed value with Claude Desktop / MCPB, or the `.env` form when running from source.
+**2. ck_set_session MCP tool:** From within Claude, call `ck_set_session` with a Cookie header you copied from DevTools (see below). The tool persists it to `.env`.
 
-**Manual (DevTools):**
+**3. Manual (DevTools):**
 1. Log in to [creditkarma.com](https://www.creditkarma.com) in Chrome
 2. DevTools → **Network** → any creditkarma.com request → **Request Headers**
 3. Right-click the `cookie` header → **Copy value**
+4. Paste into `CK_COOKIES` in your Claude config
 
 ## Authentication
 
-Call `ck_set_session` with your Cookie header to store credentials and enable auto-refresh.
+The MCP handles auth automatically once any of the three paths is configured.
 
 - Access token: ~15 min TTL, auto-refreshed transparently
 - Refresh token: ~8 hours TTL
-- When expired: re-run `npm run auth` (or grab a fresh Cookie header) and call `ck_set_session`
+- When expired:
+  - **fetchproxy path:** sign back into creditkarma.com — the MCP reads fresh cookies on the next tool call
+  - **env-var / ck_set_session path:** grab a fresh Cookie header from DevTools and update `CK_COOKIES` (or call `ck_set_session` again)
 
 ## Tools
 
@@ -104,8 +105,8 @@ Call `ck_set_session` with your Cookie header to store credentials and enable au
 ## Workflows
 
 **First-time setup:**
-1. Run `npm run auth` (or grab the Cookie header manually from a creditkarma.com request in DevTools)
-2. Paste into `CK_COOKIES` env var, or call `ck_set_session(cookies)` from within Claude
+1. Easiest: install the [fetchproxy extension](https://github.com/chrischall/fetchproxy), sign into creditkarma.com, leave `CK_COOKIES` unset.
+2. Or: copy the Cookie header from DevTools and either set `CK_COOKIES` in your config or call `ck_set_session(cookies)` from within Claude.
 3. `ck_sync_transactions` → initial full sync
 
 **Regular use:**

package/dist/auth.js

@@ -0,0 +1,198 @@
+// ────────────────────────────────────────────────────────────────────────────
+// Auth resolution — Pattern A template
+// ────────────────────────────────────────────────────────────────────────────
+//
+// Mirrors the canonical "browser-bootstrap + Node-direct" shape from
+// ofw-mcp/src/auth.ts. Other MCPs in this family (resy-mcp, opentable-mcp,
+// signupgenius-mcp, zola-mcp, …) use the same selector — keep the structure
+// flat, the path-selection explicit, and the error messages actionable.
+//
+// THE PATHS, in priority order:
+//
+//   1. CK_COOKIES env var (existing behavior)
+//      A full Cookie header (e.g. `CKTRKID=...; CKAT=eyJ...%3BeyJ...; ...`)
+//      from a signed-in creditkarma.com request. The CKAT cookie contains
+//      `<accessJWT>%3B<refreshJWT>` URL-encoded, which the caller parses.
+//      Legacy users keep working without action.
+//
+//   2. Cached session from `ck_set_session` (existing behavior)
+//      The MCP tool `ck_set_session` accepts a pasted Cookie header and
+//      persists it to .env as CK_COOKIES — so once it's been called, this
+//      path collapses into path 1 on subsequent runs.
+//
+//   3. fetchproxy fallback (new)
+//      When no Cookie header is set, lift the user's session out of their
+//      signed-in creditkarma.com browser tab via the fetchproxy 0.3.0
+//      extension. `@fetchproxy/bootstrap` spins up a one-shot WebSocket
+//      bridge, asks the extension for the `CKAT` and `CKTRKID` cookies via
+//      `chrome.cookies.get`, then closes the bridge. The synthesized
+//      Cookie header has the same shape that ck_set_session produces, so
+//      the rest of the stack consumes it without branching.
+//
+//      All subsequent API calls go out via plain Node `fetch()` —
+//      fetchproxy is NOT in the request hot path. Token refresh
+//      (`POST /member/oauth2/refresh`) is also a plain Node fetch.
+//
+//      Users opt out with CK_DISABLE_FETCHPROXY=1 (anyone who wants the
+//      old behavior of "fail loudly when creds are missing").
+//
+//   4. Error
+//      Nothing to authenticate with. We throw a message that names all
+//      three onboarding paths so the user can pick whichever fits.
+//
+// Why fetchproxy is only a one-shot read:
+//   The bootstrap call snapshots the CKAT + CKTRKID cookies and returns.
+//   The MCP then operates from Node with direct fetch — latency and
+//   reliability are not coupled to the browser bridge for normal tool
+//   calls. If the access JWT inside CKAT expires, the refresh flow runs
+//   in pure Node against `creditkarma.com/member/oauth2/refresh`. If
+//   that 403s (Akamai gate / expired refresh JWT), the user re-signs into
+//   creditkarma.com in the browser and the next MCP run re-reads the
+//   fresh cookies.
+//
+// Testability:
+//   - `@fetchproxy/bootstrap` is mocked at the module boundary in tests.
+//   - This module exposes a single async `resolveAuth()` that returns a
+//     Cookie header string + a source label. Callers treat the cookies
+//     value as opaque — the existing parser in `src/index.ts` /
+//     `src/tools/auth.ts` extracts the CKAT JWTs the same way it does
+//     today.
+import { bootstrap } from '@fetchproxy/bootstrap';
+import pkg from '../package.json' with { type: 'json' };
+import { extractCookieValue } from './client.js';
+/**
+ * Read an env var, trim, and treat blank / `${UNEXPANDED}` placeholders as
+ * unset. Defends against MCP hosts that pass `.mcp.json` env blocks through
+ * without variable expansion.
+ */
+function readEnv(key) {
+    const raw = process.env[key];
+    if (typeof raw !== 'string')
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (trimmed === 'undefined' || trimmed === 'null')
+        return undefined;
+    if (/^\$\{[^}]*\}$/.test(trimmed))
+        return undefined;
+    return trimmed;
+}
+/** True if the user has explicitly disabled the fetchproxy fallback. */
+function fetchproxyDisabled() {
+    const raw = readEnv('CK_DISABLE_FETCHPROXY');
+    if (raw === undefined)
+        return false;
+    return ['1', 'true', 'yes', 'on'].includes(raw.toLowerCase());
+}
+/**
+ * Resolve CK auth using the path priority described at the top of this
+ * file. Throws with an actionable error message when no path succeeds.
+ *
+ * Callers should treat the return value as opaque credentials — they
+ * should not branch on `source`. The field exists for logging / future
+ * cache-keying only.
+ */
+export async function resolveAuth() {
+    // ── Path 1: CK_COOKIES env var (unchanged from pre-fetchproxy behavior).
+    const envCookies = readEnv('CK_COOKIES');
+    if (envCookies) {
+        return { cookies: envCookies, source: 'env' };
+    }
+    // ── Path 2: fetchproxy fallback (new).
+    //   (Path 2 — cached session from ck_set_session — also lands here at the
+    //    env-var step on subsequent runs, since that tool writes CK_COOKIES
+    //    to .env. So this branch only fires when neither env var nor cache
+    //    has been seeded.)
+    if (!fetchproxyDisabled()) {
+        try {
+            const session = await bootstrap({
+                serverName: pkg.name,
+                version: pkg.version,
+                // CK serves www.creditkarma.com (web) and api.creditkarma.com
+                // (GraphQL). Both share the apex domain; the extension matches on
+                // suffix so listing the apex covers any subdomain.
+                domains: ['creditkarma.com'],
+                declare: {
+                    // CKAT contains the access + refresh JWTs joined by `%3B`. CKTRKID
+                    // is sent as the `ck-cookie-id` header on refresh requests; without
+                    // it the refresh endpoint 403s. Both are HttpOnly — invisible to
+                    // page JS — but fetchproxy 0.3.0's `read_cookies` uses
+                    // `chrome.cookies.get` which sees HttpOnly cookies.
+                    cookies: ['CKAT', 'CKTRKID'],
+                    localStorage: [],
+                    sessionStorage: [],
+                    captureHeaders: [],
+                },
+            });
+            const ckat = session.cookies['CKAT'];
+            const cktrkid = session.cookies['CKTRKID'];
+            if (!ckat) {
+                throw new Error('CKAT cookie missing on creditkarma.com. ' +
+                    'Sign into creditkarma.com in your browser (with the fetchproxy extension installed) and retry.');
+            }
+            if (!cktrkid) {
+                throw new Error('CKTRKID cookie missing on creditkarma.com. ' +
+                    'Sign into creditkarma.com in your browser (with the fetchproxy extension installed) and retry.');
+            }
+            // Synthesize a Cookie header identical in shape to what `ck_set_session`
+            // accepts. The existing parser in `src/index.ts` / `src/tools/auth.ts`
+            // extracts CKAT and splits its `<accessJWT>%3B<refreshJWT>` payload
+            // without caring how the header was assembled.
+            const cookies = `CKTRKID=${cktrkid}; CKAT=${ckat}`;
+            return { cookies, source: 'fetchproxy' };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`CK auth: no CK_COOKIES set, and fetchproxy fallback failed: ${msg}`);
+        }
+    }
+    // ── Path 4: nothing configured. Surface all three fixes side-by-side so
+    //    the user can pick whichever fits their setup.
+    throw new Error('CK auth: set CK_COOKIES, ' +
+        'or call the ck_set_session MCP tool with a Cookie header, ' +
+        'or install the fetchproxy extension and sign into creditkarma.com ' +
+        '(unset CK_DISABLE_FETCHPROXY if it is set).');
+}
+/**
+ * Parse a Cookie header into the CK_COOKIES → (accessToken, refreshToken)
+ * shape, mirroring `src/index.ts` and `src/tools/auth.ts`. The CKAT cookie
+ * value is `<accessJWT>%3B<refreshJWT>` URL-encoded; we split on either
+ * the encoded or literal semicolon.
+ *
+ * Exported so both `src/index.ts` (startup) and `loadAuthIntoClient()`
+ * (lazy bootstrap) can share one parser. Returns nulls (not errors) when
+ * the input doesn't contain a CKAT — the caller decides whether absence
+ * is fatal.
+ */
+export function parseCookieHeader(cookies) {
+    const ckat = extractCookieValue(cookies, 'CKAT') ?? cookies.trim();
+    const parts = ckat.replace('%3B', ';').split(';');
+    const accessToken = parts[0]?.trim() || null;
+    const refreshToken = parts[1]?.trim() || null;
+    return { accessToken, refreshToken };
+}
+/**
+ * Resolve CK auth via `resolveAuth()` and apply the result to a client.
+ *
+ * Used by tool handlers on the first request that needs auth but finds no
+ * credentials on the client — i.e. the user didn't set CK_COOKIES, didn't
+ * call ck_set_session, and the fetchproxy extension is the last hope.
+ *
+ * If `resolveAuth()` lands on the env-var path (path 1) the cookies are
+ * applied with no network round-trip. If it lands on fetchproxy (path 3)
+ * the bootstrap call snapshots the browser session once; afterwards the
+ * client has fresh CKAT + CKTRKID and the normal `refreshAccessToken()`
+ * flow takes over.
+ */
+export async function loadAuthIntoClient(client) {
+    const { cookies } = await resolveAuth();
+    const { accessToken, refreshToken } = parseCookieHeader(cookies);
+    if (!accessToken) {
+        throw new Error('CK auth: resolved cookies did not contain a CKAT token.');
+    }
+    client.setToken(accessToken);
+    if (refreshToken)
+        client.setRefreshToken(refreshToken);
+    client.setCookies(cookies);
+}