earnrate 0.1.3 → 0.1.4

package/README.md

@@ -51,6 +51,8 @@ Assumes Whole Foods Market codes as supermarkets (MCC 5411).
 
 Options: `--online` or `--in-store`, `--valuation flat|points-heavy`, `--all`, `--json`, `--date`, `--country`. Run `earnrate --help` for details. To keep the wallet somewhere else, set `EARNRATE_WALLET` to its path.
 
+`earnrate cheatsheet` prints the card to use for each everyday kind of purchase this quarter (groceries, dining, gas, Amazon, Costco, travel, streaming, drugstores, everything else), with your caps, picks and activations as they are now. It's also in the My wallet tab on [earnrate.dev](https://earnrate.dev).
+
 ### Your wallet
 
 The wallet is a YAML file (`~/.earnrate/wallet.yaml`) listing your cards by ID, which is each card's file name in [`data/cards/`](data/cards). `earnrate add`, `update`, `remove` and `memberships` write it for you and keep your comments, or you can edit it by hand. Only the cards are required:
@@ -152,12 +154,13 @@ Spotted a wrong rate, or want a card added? [Open an issue](https://github.com/c
 
 ## Use it from an AI agent (MCP)
 
-`earnrate mcp` runs earnrate as a local MCP server over stdio, with twelve tools:
+`earnrate mcp` runs earnrate as a local MCP server over stdio, with thirteen tools:
 
 - `best_card_for_purchase`: which card to use, with reasons
 - `best_cards_for` and `simulate_spending`: compare every card earnrate knows, for one purchase or a year of spending, with no wallet needed
 - `resolve_merchant`: how a merchant was identified
 - `list_wallet`: your cards, caps left this period, chosen categories and welcome-bonus progress
+- `cheat_sheet`: the card to use for each everyday kind of purchase this quarter
 - `compare_welcome_offers`: the best public sign-up offers on cards you don't have
 - `record_purchase`: books a purchase against its cap and any open welcome bonus in your wallet file, keeping your comments
 - `search_cards`, `add_card`, `update_card`, `remove_card` and `set_memberships`: set up the wallet in conversation
@@ -166,6 +169,8 @@ There's no wallet to write first: tell the assistant which cards you have, and i
 
 For a merchant earnrate doesn't know, the calling model can pass a `category` (e.g. `grocery.supermarket`). It's used only for unknown merchants and is labeled in the answer. The command line takes the same thing as `--category`.
 
+**Claude Desktop, one click:** download [earnrate.mcpb](https://github.com/cwasley/earnrate/releases/latest/download/earnrate.mcpb) and open it; Claude Desktop installs it (Settings → Extensions). No terminal or Node install needed. Its one setting is where your wallet file lives, by default `~/.earnrate/wallet.yaml`, the same file the command line uses.
+
 To add it to Claude Code:
 
 ```sh

package/dist/cli/cheatsheet.js

@@ -0,0 +1,81 @@
+import { parseArgs } from 'node:util';
+import { CLI_NAME } from "../brand.js";
+import { walletProblems } from "../data/integrity.js";
+import { loadCatalog, walletPath } from "../data/load.js";
+import { cheatSheet } from "../engine/cheat-sheet.js";
+import { isValuationProfile, withValuationProfile } from "../engine/profiles.js";
+import { displayPath, readWallet, RUNTIME_ERROR, USAGE_ERROR, } from "./run.js";
+export const CHEATSHEET_HELP = `Usage: ${CLI_NAME} cheatsheet [options]
+
+The card in your wallet to use for each everyday kind of purchase this
+quarter, with your caps, picks and activations as they are now.
+
+Options:
+  --valuation <profile>  flat or points-heavy, instead of your wallet's values.
+  --date <YYYY-MM-DD>    The day to check. Default: today.
+  --json                 Print the cheat sheet as JSON.
+  -h, --help             Show this help.
+`;
+const pct = (n) => `${String(Number(n.toFixed(2)))}%`;
+export function formatCheatSheet(sheet) {
+    const labelWidth = Math.max(...sheet.rows.map((r) => r.label.length));
+    const cardWidth = Math.max(...sheet.rows.map((r) => (r.cardName ?? 'none of your cards').length));
+    const lines = [`Your cheat sheet for ${sheet.quarter}`, ''];
+    for (const row of sheet.rows) {
+        lines.push(`  ${row.label.padEnd(labelWidth)}  ${(row.cardName ?? 'none of your cards').padEnd(cardWidth)}  ${row.effectiveReturnPct === null ? '' : pct(row.effectiveReturnPct).padStart(5)}`.trimEnd());
+        if (row.note)
+            lines.push(`  ${' '.repeat(labelWidth)}  ! ${row.note}`);
+    }
+    if (sheet.notes.length > 0)
+        lines.push('', ...sheet.notes);
+    return `${lines.join('\n')}\n`;
+}
+export async function runCheatSheet(argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            options: {
+                valuation: { type: 'string' },
+                date: { type: 'string' },
+                json: { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+            },
+        });
+    }
+    catch (e) {
+        io.stderr(`${e instanceof Error ? e.message : String(e)}\n${CHEATSHEET_HELP}`);
+        return USAGE_ERROR;
+    }
+    const { values } = parsed;
+    if (values.help) {
+        io.stdout(CHEATSHEET_HELP);
+        return 0;
+    }
+    if (values.valuation !== undefined && !isValuationProfile(values.valuation)) {
+        io.stderr(`Unknown valuation "${values.valuation}". Use flat or points-heavy.\n`);
+        return USAGE_ERROR;
+    }
+    if (values.date !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(values.date)) {
+        io.stderr(`"${values.date}" isn't a date. Use YYYY-MM-DD.\n`);
+        return USAGE_ERROR;
+    }
+    const file = walletPath(io.env);
+    const loaded = await readWallet(file, io);
+    if (!loaded)
+        return RUNTIME_ERROR;
+    const catalog = await loadCatalog();
+    const problems = walletProblems(loaded, catalog);
+    if (problems.length > 0) {
+        io.stderr(`Your wallet at ${displayPath(file)} has problems:\n${problems.map((p) => `  - ${p}\n`).join('')}`);
+        return RUNTIME_ERROR;
+    }
+    const wallet = values.valuation !== undefined && isValuationProfile(values.valuation)
+        ? withValuationProfile(loaded, values.valuation)
+        : loaded;
+    const sheet = cheatSheet(catalog, wallet, values.date ?? io.today);
+    io.stdout(values.json
+        ? `${JSON.stringify(sheet, null, 2)}\n`
+        : formatCheatSheet(sheet));
+    return 0;
+}

package/dist/cli/run.js

@@ -12,6 +12,7 @@ import { llmEnabled, openLlmSession } from "../merchants/from-env.js";
 import { resolveMerchant, withCallerCategory } from "../merchants/resolve.js";
 import { packageVersion } from "../version.js";
 import { parseCliArgs } from "./args.js";
+import { runCheatSheet } from "./cheatsheet.js";
 import { runBest, runSimulate } from "./explore.js";
 import { runImport } from "./import.js";
 import { runOffers } from "./offers.js";
@@ -38,6 +39,7 @@ Set up your wallet:
   ${CLI_NAME} memberships [names...]               Show or set memberships (amazon-prime).
 
 Other commands:
+  ${CLI_NAME} cheatsheet                           Your best card for each category this quarter.
   ${CLI_NAME} import <statement.csv> --card <id>   Replay a statement against your wallet.
   ${CLI_NAME} offers [--cash | --points]           Rank welcome offers on cards you don't have.
   ${CLI_NAME} mcp                                  Run the MCP server over stdio, for AI agents.
@@ -94,6 +96,8 @@ export async function run(argv, io) {
         return runOffers(argv.slice(1), io);
     if (argv[0] === 'best')
         return runBest(argv.slice(1), io);
+    if (argv[0] === 'cheatsheet')
+        return runCheatSheet(argv.slice(1), io);
     if (argv[0] === 'simulate')
         return runSimulate(argv.slice(1), io);
     const command = argv[0];

package/dist/engine/cheat-sheet.js

@@ -0,0 +1,48 @@
+import { resolveMerchantById } from "../merchants/resolve.js";
+import { categoryResolution } from "./explore.js";
+import { periodKey } from "./periods.js";
+import { recommend } from "./recommend.js";
+import { setupNotes } from "./setup.js";
+export const CHEAT_SHEET_ITEMS = [
+    { label: 'Groceries', category: 'grocery.supermarket' },
+    { label: 'Dining', category: 'dining' },
+    { label: 'Gas', category: 'gas' },
+    { label: 'Amazon', merchant: 'amazon' },
+    { label: 'Costco', merchant: 'costco' },
+    { label: 'Travel', category: 'travel' },
+    { label: 'Streaming', category: 'streaming' },
+    { label: 'Drugstores', category: 'drugstore' },
+    { label: 'Everything else', category: 'other' },
+];
+// The best card in the wallet for each everyday kind of purchase on `date`,
+// with caps, picks and activations as the wallet has them.
+export function cheatSheet(catalog, wallet, date, items = CHEAT_SHEET_ITEMS) {
+    const rows = items.map((item) => {
+        const merchant = 'merchant' in item
+            ? resolveMerchantById(catalog, item.merchant, null)
+            : categoryResolution(catalog, item.category, null);
+        if (!merchant)
+            throw new Error(`unknown merchant '${item.label}'`);
+        const rec = recommend(catalog, wallet, {
+            merchant: merchant.input,
+            amount: null,
+            channel: null,
+            date,
+            country: 'US',
+        }, merchant);
+        const top = rec.ranked.find((r) => r.cardId === rec.decision?.cardId);
+        return {
+            label: item.label,
+            cardId: top?.cardId ?? null,
+            cardName: top ? (top.checkoutLabel ?? top.cardName) : null,
+            effectiveReturnPct: top?.effectiveReturnPct ?? null,
+            matchedRule: top?.matchedRule ?? null,
+            note: top?.warnings[0] ?? null,
+        };
+    });
+    const notes = [
+        ...new Set(wallet.cards.flatMap((held) => setupNotes(catalog, wallet, held, date).map((n) => n.text))),
+    ];
+    const [year, q] = (periodKey('quarter', date, null) ?? '').split('-');
+    return { quarter: `${q ?? ''} ${year ?? ''}`, date, rows, notes };
+}

package/dist/mcp/schemas.js

@@ -288,3 +288,16 @@ export const SpendingSimulationSchema = z.object({
         gain: z.number(),
     })),
 });
+export const CheatSheetSchema = z.object({
+    quarter: z.string(),
+    date: z.string(),
+    rows: z.array(z.object({
+        label: z.string(),
+        cardId: z.string().nullable(),
+        cardName: z.string().nullable(),
+        effectiveReturnPct: z.number().nullable(),
+        matchedRule: z.string().nullable(),
+        note: z.string().nullable(),
+    })),
+    notes: z.array(z.string()),
+});

package/dist/mcp/server.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { MCP_SERVER_NAME } from "../brand.js";
 import { formatCardInfo, formatNotes } from "../cli/cards.js";
 import { formatRecommendation } from "../cli/format.js";
+import { formatCheatSheet } from "../cli/cheatsheet.js";
 import { formatAdditions, formatCatalogSimulation, formatExploration, } from "../cli/explore.js";
 import { formatOffers } from "../cli/offers.js";
 import { walletProblems } from "../data/integrity.js";
@@ -10,6 +11,7 @@ import { loadWallet } from "../data/load.js";
 import { withWalletLock, writeBonusSpent, writeCapBooking, } from "../data/wallet-write.js";
 import { addCard, removeCard, setMemberships, updateCard, } from "../data/wallet-setup.js";
 import { bonusStatus, countsTowardBonus } from "../engine/bonus.js";
+import { cheatSheet } from "../engine/cheat-sheet.js";
 import { ALL_PERSONAL_CARDS, exploreCards } from "../engine/explore.js";
 import { compareOffers } from "../engine/offers.js";
 import { VALUATION_PROFILES } from "../engine/profiles.js";
@@ -20,7 +22,7 @@ import { knownMemberships, searchCards } from "../engine/setup.js";
 import { walletSummary } from "../engine/wallet-summary.js";
 import { resolveMerchant, withCallerCategory } from "../merchants/resolve.js";
 import { IsoDate } from "../schema/common.js";
-import { CardSearchSchema, ExplorationSchema, MerchantResolutionSchema, SpendingSimulationSchema, RecommendationSchema, OfferComparisonSchema, RecordResultSchema, WalletChangeSchema, WalletSummarySchema, } from "./schemas.js";
+import { CardSearchSchema, CheatSheetSchema, ExplorationSchema, MerchantResolutionSchema, SpendingSimulationSchema, RecommendationSchema, OfferComparisonSchema, RecordResultSchema, WalletChangeSchema, WalletSummarySchema, } from "./schemas.js";
 const Merchant = z
     .string()
     .min(1)
@@ -41,6 +43,7 @@ const dollars = (n) => `$${n.toLocaleString('en-US', { maximumFractionDigits: 2
 export function createEarnrateServer(deps) {
     const server = new McpServer({ name: MCP_SERVER_NAME, version: deps.version }, { instructions: INSTRUCTIONS });
     const { catalog } = deps;
+    const noWallet = `There's no wallet yet (${deps.walletFile}), which is normal before the user adds a card. Ask the user which credit cards they have, find each one with search_cards, and add it with add_card. best_cards_for and simulate_spending work without a wallet.`;
     // Read on every call, so edits to the wallet file apply without a restart.
     async function wallet() {
         let loaded;
@@ -49,7 +52,7 @@ export function createEarnrateServer(deps) {
         }
         catch (e) {
             if (e instanceof Error && 'code' in e && e.code === 'ENOENT') {
-                return `There's no wallet yet (${deps.walletFile}). Ask the user which credit cards they have, find each one with search_cards, and add it with add_card.`;
+                return noWallet;
             }
             return `Couldn't read the wallet at ${deps.walletFile}: ${e instanceof Error ? e.message : String(e)}`;
         }
@@ -58,6 +61,16 @@ export function createEarnrateServer(deps) {
             ? `The wallet at ${deps.walletFile} has problems:\n${problems.map((p) => `- ${p}`).join('\n')}`
             : loaded;
     }
+    // No wallet yet is the first-run state, not a failure: read-only tools
+    // answer from an empty wallet and say how to start one.
+    async function readableWallet() {
+        const w = await wallet();
+        if (typeof w !== 'string')
+            return { wallet: w, start: null };
+        return w === noWallet
+            ? { wallet: { valuations: {}, memberships: [], cards: [] }, start: w }
+            : w;
+    }
     // The caller's category is free and comes before the paid Claude fallback;
     // neither ever overrides a merchant earnrate already knows.
     async function resolve(merchant, channel, category) {
@@ -92,9 +105,10 @@ export function createEarnrateServer(deps) {
             openWorldHint: deps.llm !== null,
         },
     }, async ({ merchant, amount, channel, date, category }) => {
-        const w = await wallet();
-        if (typeof w === 'string')
-            return fail(w);
+        const read = await readableWallet();
+        if (typeof read === 'string')
+            return fail(read);
+        const w = read.wallet;
         const purchase = {
             merchant,
             amount: amount ?? null,
@@ -104,6 +118,16 @@ export function createEarnrateServer(deps) {
         };
         const resolved = await resolve(merchant, purchase.channel, category ?? null);
         const rec = recommend(catalog, w, purchase, resolved.merchant);
+        if (read.start !== null) {
+            const output = {
+                ...rec,
+                warnings: [read.start, ...resolved.notices],
+            };
+            return {
+                content: [{ type: 'text', text: read.start }],
+                structuredContent: output,
+            };
+        }
         const output = {
             ...rec,
             warnings: [...rec.warnings, ...resolved.notices],
@@ -146,10 +170,15 @@ export function createEarnrateServer(deps) {
         outputSchema: WalletSummarySchema,
         annotations: { readOnlyHint: true, openWorldHint: false },
     }, async () => {
-        const w = await wallet();
-        if (typeof w === 'string')
-            return fail(w);
-        const summary = walletSummary(catalog, w, deps.today());
+        const read = await readableWallet();
+        if (typeof read === 'string')
+            return fail(read);
+        const summary = walletSummary(catalog, read.wallet, deps.today());
+        if (read.start !== null)
+            return {
+                content: [{ type: 'text', text: read.start }],
+                structuredContent: summary,
+            };
         const lines = summary.cards.map((c) => {
             const caps = c.caps
                 .filter((cap) => cap.remaining !== null)
@@ -198,10 +227,10 @@ export function createEarnrateServer(deps) {
         outputSchema: OfferComparisonSchema,
         annotations: { readOnlyHint: true, openWorldHint: false },
     }, async (args) => {
-        const w = await wallet();
-        if (typeof w === 'string')
-            return fail(w);
-        const comparison = compareOffers(catalog, w, {
+        const read = await readableWallet();
+        if (typeof read === 'string')
+            return fail(read);
+        const comparison = compareOffers(catalog, read.wallet, {
             kind: args.kind ?? 'any',
             noAnnualFee: args.noAnnualFee ?? false,
             business: args.business ?? false,
@@ -318,10 +347,11 @@ export function createEarnrateServer(deps) {
         if (unknown.length > 0)
             return fail(`earnrate doesn't know ${unknown.map((l) => `"${l.merchant.input}"`).join(', ')}. Give a category for those lines instead.`);
         const options = { ...settings(args), start: deps.today() };
-        if (args.compareToWallet) {
-            const w = await wallet();
-            if (typeof w === 'string')
-                return fail(w);
+        const read = args.compareToWallet ? await readableWallet() : null;
+        if (typeof read === 'string')
+            return fail(read);
+        if (read && read.start === null) {
+            const w = read.wallet;
             const valued = args.valuation
                 ? {
                     ...w,
@@ -347,11 +377,12 @@ export function createEarnrateServer(deps) {
             };
         }
         const result = simulateCatalog(catalog, lines, options);
+        const text = formatCatalogSimulation(result, catalog, false);
         return {
             content: [
                 {
                     type: 'text',
-                    text: formatCatalogSimulation(result, catalog, false),
+                    text: read?.start ? `${read.start}\n\n${text}` : text,
                 },
             ],
             structuredContent: {
@@ -362,6 +393,27 @@ export function createEarnrateServer(deps) {
             },
         };
     });
+    server.registerTool('cheat_sheet', {
+        title: 'Cheat sheet',
+        description: "The card in the user's wallet to use for each everyday kind of purchase right now: groceries, dining, gas, Amazon, Costco, travel, streaming, drugstores and everything else, with caps, picks and activations as the wallet has them. Use it when the user asks which card to use for what, or wants a quick reference for the quarter. For one specific store, call best_card_for_purchase instead. Pass on the notes: they say what the wallet still needs, like this quarter's picks.",
+        inputSchema: z.object({ date: DateInput }),
+        outputSchema: CheatSheetSchema,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async (args) => {
+        const read = await readableWallet();
+        if (typeof read === 'string')
+            return fail(read);
+        const sheet = cheatSheet(catalog, read.wallet, args.date ?? deps.today());
+        if (read.start !== null)
+            return {
+                content: [{ type: 'text', text: read.start }],
+                structuredContent: { ...sheet, notes: [read.start] },
+            };
+        return {
+            content: [{ type: 'text', text: formatCheatSheet(sheet) }],
+            structuredContent: sheet,
+        };
+    });
     server.registerTool('record_purchase', {
         title: 'Record a purchase',
         description: "Records a purchase the user has already made, so spending caps and welcome-bonus progress stay accurate for future recommendations. It updates the user's wallet file. Only call it after the purchase has happened, and only once per purchase: calling it twice counts the spend twice. Purchases with no cap and no open welcome bonus are acknowledged and nothing is written.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "earnrate",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Picks the best credit card from your wallet for a merchant, and explains why",
   "keywords": [
     "credit cards",
@@ -40,7 +40,9 @@
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "prepack": "yarn build",
     "smoke:pack": "node scripts/smoke-pack.ts",
-    "site:build": "vite build site",
+    "mcpb:pack": "node scripts/build-mcpb.ts",
+    "smoke:mcpb": "node scripts/smoke-mcpb.ts",
+    "site:build": "vite build site && node scripts/build-pages.ts",
     "site:dev": "vite site",
     "site:deploy": "yarn site:build && WRANGLER_SEND_METRICS=false wrangler deploy",
     "test": "vitest run",
@@ -59,6 +61,7 @@
     "zod": "^4.6.7"
   },
   "devDependencies": {
+    "@anthropic-ai/mcpb": "^2.1.2",
     "@eslint/js": "^10.0.1",
     "@modelcontextprotocol/client": "2.3.1",
     "@types/node": "^24",