creditkarma-mcp 2.0.4 → 2.0.6

package/README.md

@@ -65,7 +65,7 @@ cp .env.example .env
       "command": "node",
       "args": ["/absolute/path/to/creditkarma-mcp/dist/index.js"],
       "env": {
-        "CK_COOKIES": "your-ckat-value-here"
+        "CK_COOKIES": "CKTRKID=...; CKAT=eyJ...%3BeyJ...; ..."
       }
     }
   }
@@ -85,44 +85,47 @@ Credit Karma uses short-lived JWTs. This server handles automatic token refresh
 #### Option A — scripted (recommended)
 
 ```bash
-npm run auth               # prints the CKAT value to the console
-npm run auth -- .env       # writes CK_COOKIES=<ckat> to .env
+npm run auth               # prints the Cookie header to the console
+npm run auth -- .env       # writes CK_COOKIES=<header> to .env
 ```
 
-Launches Chrome with a dedicated profile at `~/.creditkarma-mcp/chrome-profile`, waits for you to sign in at creditkarma.com, then captures the `CKAT` cookie (the URL-encoded bundle of access + refresh JWTs). Either prints it (for pasting into Claude Desktop / MCPB) or writes it to the env file you pass. Requires Google Chrome installed locally; the script installs `puppeteer-core` on first run (~1 MB).
+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`).
 
-#### Option B — manual (DevTools)
+#### Option B — manual paste (secure prompt)
+
+```bash
+npm run auth -- --manual           # prompts for the cookie, prints CK_COOKIES
+npm run auth -- --manual .env      # prompts for the cookie, writes to .env
+```
+
+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.
+
+#### Option C — manual (DevTools)
 
 1. Log in to [creditkarma.com](https://www.creditkarma.com) in Chrome
-2. Open DevTools → **Application** → **Cookies** → `https://www.creditkarma.com`
-3. Find the `CKAT` cookie and copy its value
+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` (or your CKAT cookie) into `CK_COOKIES` in your `.env` or Claude config
-- Or call `ck_set_session` from within Claude with the cookie value — it accepts any of:
-
-| Format | Example |
-|--------|---------|
-| Raw CKAT value | `eyJraWQ...%3BeyJraWQ...` |
-| `CKAT=<value>` | `CKAT=eyJraWQ...%3BeyJraWQ...` |
-| Full Cookie header | *(what `npm run auth` prints)* |
+- 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
 
-The server automatically extracts both the access token and refresh token from the CKAT cookie, and refreshes the access token as needed.
+The server extracts the access and refresh JWTs from the `CKAT` cookie inside the header and refreshes the access token automatically as needed.
 
 ### Session expiry
 
 - **Access token**: ~15 minutes (auto-refreshed transparently)
 - **Refresh token**: ~8 hours
-- When the refresh token expires, re-run `npm run auth` (or grab the new CKAT cookie from DevTools) and either update `CK_COOKIES` or call `ck_set_session`
+- 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`
 
 ## Available tools
 
 | Tool | What it does |
 |------|-------------|
-| `ck_set_session` | Store credentials from your browser cookies (auto-extracts tokens from CKAT) |
+| `ck_set_session` | Store credentials from your browser Cookie header (auto-extracts JWTs from the CKAT cookie) |
 | `ck_sync_transactions` | Sync transactions into the local SQLite database |
 | `ck_list_transactions` | List transactions with filters (date, account, category, merchant, amount) |
 | `ck_get_recent_transactions` | Fetch the N most recent transactions |
@@ -153,14 +156,14 @@ sync_state   (key, value)
 
 | Env var | Description | Default |
 |---------|-------------|---------|
-| `CK_COOKIES` | CKAT value, `CKAT=<value>`, or full Cookie header | *(required)* |
+| `CK_COOKIES` | Full Cookie header from a signed-in creditkarma.com request | *(required)* |
 | `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 new CKAT cookie) and update `CK_COOKIES` or call `ck_set_session`.
+**"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`.
 
-**Sync returns 0 transactions** — check that your `CK_COOKIES` value is fresh. CKAT cookies expire after ~8 hours.
+**Sync returns 0 transactions** — check that your `CK_COOKIES` value 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.
 
@@ -169,33 +172,44 @@ sync_state   (key, value)
 ## Security
 
 - Credentials are stored only in your local `.env` file (gitignored) or Claude config
-- The server never logs credentials
-- Only SELECT queries are permitted via `ck_query_sql` — no writes to Credit Karma
+- `.env` is written at mode 0600 (owner read/write only) by both `npm run auth` and `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 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
 
 ## Development
 
 ```bash
-npm test            # run the test suite
-npm run build       # compile TypeScript → dist/
-npm run test:watch  # watch mode
+npm test               # run the test suite (vitest)
+npm run build          # compile TypeScript → dist/, copy transaction.graphql, bundle for MCPB
+npm run test:watch     # watch mode
+npm run test:coverage  # coverage report (CI enforces 100% on src/**)
 ```
 
+Versions are bumped automatically by the **Tag & Bump** GitHub Action (`.github/workflows/tag-and-bump.yml`). Do not bump manually.
+
 ### Project structure
 
 ```
 src/
-  client.ts             Credit Karma GraphQL client with auto-refresh
-  index.ts              MCP server entry point
-  db.ts                 SQLite schema and upsert helpers
-  transaction.graphql   GraphQL query for transactions
+  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
+  transaction.graphql   GraphQL query for transactions (copied to dist/ at build time)
   tools/
-    auth.ts             ck_set_session
-    sync.ts             ck_sync_transactions
-    query.ts            ck_list_transactions, ck_get_recent_transactions, etc.
-    sql.ts              ck_query_sql
+    auth.ts             ck_set_session — refuses stale refresh tokens, writes .env at 0600
+    sync.ts             ck_sync_transactions — incremental sync with resume-on-failure
+    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 — SELECT-only escape hatch
+scripts/
+  setup-auth.mjs        npm run auth — Puppeteer flow + manual paste fallback
 tests/
+  helpers.ts            Shared test helpers (fakeServer, makeJwt)
   client.test.ts
   db.test.ts
+  setup-auth.test.ts
   tools/
     auth.test.ts
     sync.test.ts

package/SKILL.md

@@ -23,7 +23,7 @@ Add to `.mcp.json` in your project or `~/.claude/mcp.json`:
       "command": "npx",
       "args": ["-y", "creditkarma-mcp"],
       "env": {
-        "CK_COOKIES": "your-ckat-value-here"
+        "CK_COOKIES": "CKTRKID=...; CKAT=eyJ...%3BeyJ...; ..."
       }
     }
   }
@@ -47,7 +47,7 @@ Then add to `.mcp.json`:
       "command": "node",
       "args": ["/path/to/creditkarma-mcp/dist/index.js"],
       "env": {
-        "CK_COOKIES": "your-ckat-value-here"
+        "CK_COOKIES": "CKTRKID=...; CKAT=eyJ...%3BeyJ...; ..."
       }
     }
   }
@@ -60,33 +60,31 @@ Or use a `.env` file in the project directory with `CK_COOKIES=<value>`.
 
 **Scripted (recommended — source install):**
 ```bash
-npm run auth               # prints the CKAT value to the console
-npm run auth -- .env       # writes CK_COOKIES=<ckat> to .env
+npm run auth               # prints the Cookie header to the console
+npm run auth -- .env       # writes CK_COOKIES=<header> to .env
 ```
 
-Launches Chrome with a dedicated profile, waits for sign-in at creditkarma.com, then captures the `CKAT` cookie (the URL-encoded bundle of access + refresh JWTs). Use the printed value with Claude Desktop / MCPB, or the `.env` form when running from source.
+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.
 
 **Manual (DevTools):**
 1. Log in to [creditkarma.com](https://www.creditkarma.com) in Chrome
-2. DevTools → **Application** → **Cookies** → `creditkarma.com`
-3. Copy the `CKAT` cookie value
-
-Accepts: raw CKAT value, `CKAT=<value>`, or the full Cookie header string from any CK network request.
+2. DevTools → **Network** → any creditkarma.com request → **Request Headers**
+3. Right-click the `cookie` header → **Copy value**
 
 ## Authentication
 
-Call `ck_set_session` with your cookie value to store credentials and enable auto-refresh.
+Call `ck_set_session` with your Cookie header to store credentials and enable auto-refresh.
 
 - Access token: ~15 min TTL, auto-refreshed transparently
 - Refresh token: ~8 hours TTL
-- When expired: re-run `npm run auth` (or grab a new CKAT cookie) and call `ck_set_session`
+- When expired: re-run `npm run auth` (or grab a fresh Cookie header) and call `ck_set_session`
 
 ## Tools
 
 ### Auth
 | Tool | Description |
 |------|-------------|
-| `ck_set_session(cookies)` | Store credentials — accepts CKAT value, `CKAT=<value>`, or full Cookie header |
+| `ck_set_session(cookies)` | Store credentials — paste the full Cookie header from a signed-in creditkarma.com request |
 
 ### Sync
 | Tool | Description |
@@ -106,7 +104,7 @@ Call `ck_set_session` with your cookie value to store credentials and enable aut
 ## Workflows
 
 **First-time setup:**
-1. Run `npm run auth` (or grab the `CKAT` cookie manually from creditkarma.com DevTools)
+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
 3. `ck_sync_transactions` → initial full sync