npm - creditkarma-mcp - Versions diffs - 2.2.0 → 2.2.2 - Mend

creditkarma-mcp 2.2.0 → 2.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/dist/client.js CHANGED Viewed

@@ -1,6 +1,7 @@
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { join, dirname } from 'path';
+import { truncateErrorMessage } from '@chrischall/mcp-utils';
 const TOKEN_TTL_MS = 10 * 60 * 1000; // 10 minutes
 export const GRAPHQL_ENDPOINT = 'https://api.creditkarma.com/graphql';
 export const CK_REFRESH_ENDPOINT = 'https://www.creditkarma.com/member/oauth2/refresh';
@@ -9,6 +10,8 @@ export class CreditKarmaClient {
     tokenSetAt = null;
     refreshToken = null;
     cookies = null;
+    /** In-flight refresh, shared across concurrent callers (see refreshAccessToken). */
+    refreshInFlight = null;
     constructor(token, refreshToken, cookies) {
         if (token)
             this.setToken(token);
@@ -60,18 +63,33 @@ export class CreditKarmaClient {
             if (retry.status === 401)
                 throw new Error('TOKEN_EXPIRED');
             if (!retry.ok)
-                throw new Error(`HTTP ${retry.status}`);
+                throw new Error(await httpErrorMessage(retry));
             return parseTransactionPage(await retry.json());
         }
         if (!response.ok)
-            throw new Error(`HTTP ${response.status}`);
+            throw new Error(await httpErrorMessage(response));
         return parseTransactionPage(await response.json());
     }
     /**
      * Refresh the access token using CK's native refresh endpoint.
      * Requires a refresh token and session cookies (captured after login).
+     *
+     * Concurrent callers share a single in-flight request: the first call starts
+     * the refresh and stores its promise; overlapping callers (e.g. a multi-page
+     * sync that 401s on several pages at once) await that same promise instead of
+     * firing duplicate POSTs to /member/oauth2/refresh (wasted quota, rate-limit
+     * risk). The slot is cleared in `finally`, so a later expiry refreshes anew.
      */
-    async refreshAccessToken() {
+    refreshAccessToken() {
+        if (this.refreshInFlight)
+            return this.refreshInFlight;
+        const p = this.doRefreshAccessToken().finally(() => {
+            this.refreshInFlight = null;
+        });
+        this.refreshInFlight = p;
+        return p;
+    }
+    async doRefreshAccessToken() {
         if (!this.refreshToken)
             throw new Error('NO_REFRESH_TOKEN: Call ck_set_session first.');
         const headers = {
@@ -155,6 +173,17 @@ export function isJwtExpired(token) {
         return false;
     return p.exp * 1000 < Date.now();
 }
+/**
+ * Emit the standard stderr warning when a refresh JWT is present but already
+ * expired. Single source of truth for the message that previously lived in
+ * both `src/index.ts` (startup) and was conceptually mirrored in
+ * `ck_set_session`. No-op when the token is absent or still valid.
+ */
+export function warnIfRefreshTokenExpired(refreshToken) {
+    if (refreshToken && isJwtExpired(refreshToken)) {
+        console.error('[creditkarma-mcp] Warning: refresh token in CK_COOKIES has expired. Sign back into creditkarma.com (with the fetchproxy extension installed) or call ck_set_session with a fresh Cookie header.');
+    }
+}
 function extractGlidFromJwt(token) {
     const p = decodeJwtPayload(token);
     const glid = p?.glid;
@@ -196,3 +225,20 @@ function parseTransactionPage(json) {
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
+/**
+ * Build an `HTTP <status>: <body>` error message for a failed GraphQL response,
+ * attaching the upstream body (redacted + length-capped via mcp-utils'
+ * `truncateErrorMessage`) so failures are debuggable instead of a bare status.
+ * Falls back to just the status when the body can't be read.
+ */
+async function httpErrorMessage(res) {
+    let body = '';
+    try {
+        body = typeof res.text === 'function' ? await res.text() : '';
+    }
+    catch {
+        body = '';
+    }
+    const safe = truncateErrorMessage(body, 200).trim();
+    return safe.length > 0 ? `HTTP ${res.status}: ${safe}` : `HTTP ${res.status}`;
+}

package/dist/index.js CHANGED Viewed

@@ -1,45 +1,22 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readEnvVar, loadDotenvSafely, runMcp } from '@chrischall/mcp-utils';
 import { homedir } from 'os';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { CreditKarmaClient, isJwtExpired, extractCookieValue } from './client.js';
+import { CreditKarmaClient, extractCookieValue, warnIfRefreshTokenExpired } from './client.js';
 import { initDb, backfillAccountIds } from './db.js';
 import { registerAuthTools } from './tools/auth.js';
 import { registerSyncTools } from './tools/sync.js';
 import { registerQueryTools } from './tools/query.js';
 import { registerSqlTools } from './tools/sql.js';
-/**
- * Read an env var, trim whitespace, and treat as unset if blank or if the value
- * looks like an unsubstituted shell placeholder (e.g. `${FOO}`) — defends
- * against MCP hosts that pass .mcp.json env blocks through unexpanded.
- */
-function readVar(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;
-}
 const __dirname = dirname(fileURLToPath(import.meta.url));
-// Load .env for local dev; silently skip if dotenv is unavailable (e.g. mcpb bundle)
-try {
-    const { config } = await import('dotenv');
-    config({ path: join(__dirname, '..', '.env'), override: false, quiet: true });
-}
-catch {
-    // not available — rely on process.env (mcpb sets credentials via mcp_config.env)
-}
+// Load .env for local dev; no-throw when absent (e.g. mcpb bundle relies on
+// mcp_config.env). `readEnvVar` below already hardens against blank /
+// `${UNEXPANDED}` placeholders passed through by some MCP hosts.
+await loadDotenvSafely({ path: join(__dirname, '..', '.env') });
 async function main() {
-    const dbPath = readVar('CK_DB_PATH') || join(homedir(), '.creditkarma-mcp', 'transactions.db');
+    const dbPath = readEnvVar('CK_DB_PATH') || join(homedir(), '.creditkarma-mcp', 'transactions.db');
     const mcpJsonPath = join(__dirname, '..', '.mcp.json');
-    const cookies = readVar('CK_COOKIES') || undefined;
+    const cookies = readEnvVar('CK_COOKIES') || undefined;
     // Canonical CK_COOKIES is a full Cookie header. Parser stays lenient and
     // also accepts a bare CKAT value or `CKAT=<value>` from legacy configs.
     let token;
@@ -50,26 +27,31 @@ async function main() {
         token = parts[0]?.trim() || undefined;
         refreshToken = parts[1]?.trim() || undefined;
     }
-    if (refreshToken && isJwtExpired(refreshToken)) {
-        console.error('[creditkarma-mcp] Warning: refresh token in CK_COOKIES has expired. Sign back into creditkarma.com (with the fetchproxy extension installed) or call ck_set_session with a fresh Cookie header.');
-    }
+    warnIfRefreshTokenExpired(refreshToken);
     const db = initDb(dbPath);
     const repaired = backfillAccountIds(db);
     if (repaired.txsUpdated > 0) {
         console.error(`[creditkarma-mcp] Repaired ${repaired.txsUpdated} transactions across ${repaired.accountsCreated} accounts (CK returned empty account.id for legacy rows).`);
     }
+    // Build the client/context here so the deferred-config-error pattern is
+    // preserved: the server boots (and answers the host's install-time
+    // tools/list) even when CK_COOKIES is absent — the auth error surfaces on
+    // the first tool call that needs credentials instead.
     const ctx = {
         client: new CreditKarmaClient(token, refreshToken, cookies),
         db,
         mcpJsonPath
     };
-    const server = new McpServer({ name: 'creditkarma-mcp', version: '2.2.0' } // x-release-please-version
-    );
-    registerAuthTools(server, ctx);
-    registerSyncTools(server, ctx);
-    registerQueryTools(server, ctx);
-    registerSqlTools(server, ctx);
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
+    await runMcp({
+        name: 'creditkarma-mcp',
+        version: '2.2.2', // x-release-please-version
+        deps: ctx,
+        tools: [
+            registerAuthTools,
+            registerSyncTools,
+            registerQueryTools,
+            registerSqlTools,
+        ],
+    });
 }
 main().catch(console.error);

package/dist/tools/auth.js CHANGED Viewed

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { rawTextResult } from '@chrischall/mcp-utils';
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 import { isJwtExpired, extractCookieValue } from '../client.js';
@@ -65,6 +66,6 @@ export function registerAuthTools(server, ctx) {
         },
     }, async (args) => {
         const result = await handleSetSession(args, ctx);
-        return { content: [{ type: 'text', text: result }] };
+        return rawTextResult(result);
     });
 }

package/dist/tools/query.js CHANGED Viewed

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { textResult } from '@chrischall/mcp-utils';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -188,7 +189,7 @@ export function registerQueryTools(server, ctx) {
         },
     }, async (args) => {
         const result = await handleListTransactions(args, ctx);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return textResult(result);
     });
     server.registerTool('ck_get_recent_transactions', {
         description: 'Return the N most recent transactions. Convenience shortcut for ck_list_transactions.',
@@ -198,7 +199,7 @@ export function registerQueryTools(server, ctx) {
         },
     }, async (args) => {
         const result = await handleGetRecentTransactions(args, ctx);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return textResult(result);
     });
     server.registerTool('ck_get_spending_by_category', {
         description: 'Group debit transactions by category and return totals.',
@@ -210,7 +211,7 @@ export function registerQueryTools(server, ctx) {
         },
     }, async (args) => {
         const result = await handleGetSpendingByCategory(args, ctx);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return textResult(result);
     });
     server.registerTool('ck_get_spending_by_merchant', {
         description: 'Return top merchants by total debit spend.',
@@ -223,7 +224,7 @@ export function registerQueryTools(server, ctx) {
         },
     }, async (args) => {
         const result = await handleGetSpendingByMerchant(args, ctx);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return textResult(result);
     });
     server.registerTool('ck_get_account_summary', {
         description: 'Return per-account debit, credit, and net totals.',
@@ -234,6 +235,6 @@ export function registerQueryTools(server, ctx) {
         },
     }, async (args) => {
         const result = await handleGetAccountSummary(args, ctx);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return textResult(result);
     });
 }

package/dist/tools/sql.js CHANGED Viewed

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { textResult } from '@chrischall/mcp-utils';
 export async function handleQuerySql(args, ctx) {
     const trimmed = args.sql.replace(/\/\*[\s\S]*?\*\//g, '').replace(/--[^\n]*/g, '').trim();
     if (!/^SELECT\s/i.test(trimmed)) {
@@ -18,6 +19,6 @@ export function registerSqlTools(server, ctx) {
         },
     }, async (args) => {
         const result = await handleQuerySql(args, ctx);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return textResult(result);
     });
 }

package/dist/tools/sync.js CHANGED Viewed

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { textResult } from '@chrischall/mcp-utils';
 import { upsertAccount, upsertCategory, upsertMerchant, upsertTransaction, getSyncState, setSyncState } from '../db.js';
 import { deriveAccountId } from '../accountId.js';
 import { loadAuthIntoClient } from '../auth.js';
@@ -137,6 +138,6 @@ export function registerSyncTools(server, ctx) {
         },
     }, async (args) => {
         const result = await handleSyncTransactions(args, ctx);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return textResult(result);
     });
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "creditkarma-mcp",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "mcpName": "io.github.chrischall/creditkarma-mcp",
   "description": "MCP server for Credit Karma — natural-language access to your transactions, spending, and accounts",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -44,8 +44,9 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@fetchproxy/bootstrap": "^0.8.0",
-    "@fetchproxy/server": "^0.8.0",
+    "@chrischall/mcp-utils": "^0.5.0",
+    "@fetchproxy/bootstrap": "^1.0.0",
+    "@fetchproxy/server": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
     "zod": "^4.4.3"

package/server.json CHANGED Viewed

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/creditkarma-mcp",
     "source": "github"
   },
-  "version": "2.2.0",
+  "version": "2.2.2",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "creditkarma-mcp",
-      "version": "2.2.0",
+      "version": "2.2.2",
       "transport": {
         "type": "stdio"
       },