earnrate 0.1.2 → 0.1.4

package/dist/engine/wallet-change.js

@@ -0,0 +1,179 @@
+import { periodKey } from "./periods.js";
+import { knownMemberships, searchCards, setupNotes, } from "./setup.js";
+const failed = (error) => ({ ok: false, error });
+const list = (ids) => ids.join(', ');
+export function findCatalogCard(catalog, id, today) {
+    const card = catalog.cards.find((c) => c.id === id);
+    if (card)
+        return card;
+    const near = searchCards(catalog, id, null, today).cards.map((c) => c.id);
+    return near.length > 0
+        ? `No card '${id}' in earnrate. Closest: ${list(near)}.`
+        : `No card '${id}' in earnrate. Search the catalog to find its id.`;
+}
+export function isAnniversary(text) {
+    const m = /^(\d{2})-(\d{2})$/.exec(text);
+    if (!m)
+        return false;
+    const date = new Date(`2024-${text}T00:00:00Z`); // a leap year allows 02-29
+    return (!Number.isNaN(date.getTime()) && date.toISOString().slice(5, 10) === text);
+}
+// The period key picks are filed under: the card's choice period, or for
+// picks that carry over, the current year (it's never compared).
+function pickPeriod(card, today) {
+    const periods = [
+        ...new Set(card.choices.map((c) => c.period).filter((p) => p !== 'until_changed')),
+    ];
+    if (periods.length > 1)
+        return null;
+    return periodKey(periods[0] ?? 'calendar_year', today, null);
+}
+export function cardFields(card, held, input, today) {
+    const problems = [];
+    const fields = {};
+    if (input.checkoutLabel !== undefined) {
+        if (input.checkoutLabel.trim() === '')
+            problems.push('The checkout label is empty.');
+        // earnrate never stores card numbers; a last four is fine.
+        if (/\d{8,}/.test(input.checkoutLabel.replace(/[\s-]/g, '')))
+            problems.push('The checkout label looks like it has a card number in it. earnrate never stores card numbers; use a name like "Amex Gold".');
+        fields.checkout_label = input.checkoutLabel.trim();
+    }
+    if (input.anniversary !== undefined) {
+        if (!isAnniversary(input.anniversary)) {
+            problems.push(`"${input.anniversary}" isn't an anniversary. Use MM-DD, like 03-15.`);
+        }
+        fields.anniversary = input.anniversary;
+    }
+    if (input.activated !== undefined) {
+        const needing = card.rules
+            .filter((r) => r.requires?.activation)
+            .map((r) => r.id);
+        for (const id of input.activated) {
+            if (!needing.includes(id)) {
+                problems.push(needing.length > 0
+                    ? `'${id}' isn't a ${card.id} rule that needs activating. Those are: ${list(needing)}.`
+                    : `${card.id} has no rules that need activating.`);
+            }
+        }
+        fields.activated = [...new Set(input.activated)];
+    }
+    if (input.picks !== undefined) {
+        for (const [choiceId, picks] of Object.entries(input.picks)) {
+            const choice = card.choices.find((c) => c.id === choiceId);
+            if (!choice) {
+                problems.push(card.choices.length > 0
+                    ? `${card.id} has no '${choiceId}' pick. Its picks are: ${list(card.choices.map((c) => c.id))}.`
+                    : `${card.id} has no categories to pick.`);
+                continue;
+            }
+            const options = Object.keys(choice.options);
+            for (const p of picks) {
+                if (!options.includes(p)) {
+                    problems.push(`'${p}' isn't a ${choiceId} option for ${card.id}. Options: ${list(options)}.`);
+                }
+            }
+            if (picks.length === 0 || picks.length > choice.pick) {
+                problems.push(`${choiceId} takes ${choice.pick === 1 ? '1 pick' : `1 to ${String(choice.pick)} picks`}, not ${String(picks.length)}.`);
+            }
+        }
+        const period = pickPeriod(card, today);
+        if (period === null) {
+            problems.push(`${card.id} has picks on different schedules; edit the wallet by hand.`);
+        }
+        else {
+            const kept = held?.chosen?.period === period ? held.chosen.picks : {};
+            fields.chosen = {
+                period,
+                picks: { ...kept, ...input.picks },
+            };
+        }
+    }
+    return problems.length > 0 ? problems.join('\n') : fields;
+}
+export const newHolding = (id) => ({
+    id,
+    cap_usage: {},
+    activated: [],
+});
+export const withFields = (held, f) => ({
+    ...held,
+    ...(f.checkout_label === undefined
+        ? {}
+        : { checkout_label: f.checkout_label }),
+    ...(f.anniversary === undefined ? {} : { anniversary: f.anniversary }),
+    ...(f.chosen === undefined ? {} : { chosen: f.chosen }),
+    ...(f.activated === undefined ? {} : { activated: f.activated }),
+});
+// `wallet` is null when there isn't one yet; adding a card starts it.
+export function addToWallet(catalog, wallet, input, today) {
+    const card = findCatalogCard(catalog, input.id, today);
+    if (typeof card === 'string')
+        return failed(card);
+    if (wallet?.cards.some((c) => c.id === card.id)) {
+        return failed(`${card.id} is already in the wallet. Update it instead.`);
+    }
+    const fields = cardFields(card, null, input, today);
+    if (typeof fields === 'string')
+        return failed(fields);
+    const held = withFields(newHolding(card.id), fields);
+    const next = wallet
+        ? { ...wallet, cards: [...wallet.cards, held] }
+        : { valuations: {}, memberships: [], cards: [held] };
+    return {
+        ok: true,
+        wallet: next,
+        fields,
+        notes: setupNotes(catalog, next, held, today),
+    };
+}
+export function updateInWallet(catalog, wallet, input, today) {
+    const held = wallet.cards.find((c) => c.id === input.id);
+    const card = catalog.cards.find((c) => c.id === input.id);
+    if (!held || !card) {
+        return failed(`${input.id} isn't in the wallet. Cards: ${list(wallet.cards.map((c) => c.id))}.`);
+    }
+    const fields = cardFields(card, held, input, today);
+    if (typeof fields === 'string')
+        return failed(fields);
+    if (Object.keys(fields).length === 0)
+        return failed('Nothing to change.');
+    const updated = withFields(held, fields);
+    const next = {
+        ...wallet,
+        cards: wallet.cards.map((c) => (c.id === held.id ? updated : c)),
+    };
+    return {
+        ok: true,
+        wallet: next,
+        fields,
+        notes: setupNotes(catalog, next, updated, today),
+    };
+}
+export function removeFromWallet(wallet, id) {
+    if (!wallet.cards.some((c) => c.id === id)) {
+        return failed(`${id} isn't in the wallet. Cards: ${list(wallet.cards.map((c) => c.id))}.`);
+    }
+    if (wallet.cards.length === 1) {
+        return failed(`${id} is the last card in the wallet, and a wallet needs one. Add the new card first, then remove this one.`);
+    }
+    return {
+        ok: true,
+        wallet: { ...wallet, cards: wallet.cards.filter((c) => c.id !== id) },
+        fields: {},
+        notes: [],
+    };
+}
+export function withMemberships(catalog, wallet, memberships) {
+    const known = knownMemberships(catalog);
+    const unknown = memberships.filter((m) => !known.includes(m));
+    if (unknown.length > 0) {
+        return failed(`No card rule uses ${unknown.map((m) => `'${m}'`).join(', ')}. Memberships earnrate knows: ${list(known)}.`);
+    }
+    return {
+        ok: true,
+        wallet: { ...wallet, memberships: [...new Set(memberships)] },
+        fields: {},
+        notes: [],
+    };
+}

package/dist/mcp/schemas.js

@@ -218,3 +218,86 @@ export const WalletChangeSchema = z.object({
         text: z.string(),
     })),
 });
+const ExcludedCardSchema = z.object({
+    cardId: z.string(),
+    cardName: z.string(),
+    checkoutLabel: z.string().nullable(),
+    network: Network,
+    reason: z.string(),
+});
+const Picks = z.record(z.string(), z.array(z.string()));
+export const ExplorationSchema = z.object({
+    merchant: MerchantResolutionSchema,
+    ranked: z.array(RankedCardSchema.extend({
+        issuer: z.string(),
+        network: CardNetwork,
+        annualFee: z.number().nullable(),
+        firstYearFee: z.number().nullable(),
+        picks: Picks,
+        requirements: z.object({
+            pick: z
+                .object({
+                choice: z.string(),
+                options: z.array(z.string()),
+                period: z.string(),
+            })
+                .nullable(),
+            activation: z.string().nullable(),
+            membership: z.string().nullable(),
+            cap: z
+                .object({
+                amount: z.number(),
+                period: z.string(),
+                thenRate: z.number(),
+                currency: z.string(),
+            })
+                .nullable(),
+        }),
+        conditions: z.array(z.string()),
+        evidence: z.object({ quote: z.string(), url: z.string() }).nullable(),
+        withMembership: z.array(z.object({ membership: z.string(), effectiveReturnPct: z.number() })),
+    })),
+    excluded: z.array(ExcludedCardSchema),
+    assumptions: z.array(z.string()),
+    warnings: z.array(z.string()),
+});
+const SimulationSchema = z.object({
+    cards: z.array(z.object({ cardId: z.string(), picks: Picks })),
+    spend: z.number(),
+    rewards: z.number(),
+    annualFees: z.number(),
+    net: z.number(),
+    lines: z.array(z.object({
+        label: z.string(),
+        spend: z.number(),
+        earned: z.number(),
+        returnPct: z.number(),
+        cards: z.array(z.string()),
+    })),
+    notes: z.array(z.string()),
+});
+export const SpendingSimulationSchema = z.object({
+    singles: z.array(SimulationSchema),
+    pairs: z.array(SimulationSchema.extend({ alternatives: z.array(z.string()) })),
+    current: SimulationSchema.nullable(),
+    additions: z.array(z.object({
+        cardId: z.string(),
+        picks: Picks,
+        extraRewards: z.number(),
+        annualFee: z.number(),
+        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,20 +3,26 @@ 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";
 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";
 import { capBooking } from "../engine/record.js";
 import { recommend } from "../engine/recommend.js";
+import { resolveSpendLines, simulateAdditions, simulateCatalog, } from "../engine/simulate.js";
 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, MerchantResolutionSchema, 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)
@@ -26,7 +32,7 @@ const ChannelInput = z
     .optional()
     .describe('How the purchase is made. Omit if unknown; the answer says what it assumed.');
 const DateInput = IsoDate.optional().describe('Purchase date, YYYY-MM-DD. Defaults to today.');
-const INSTRUCTIONS = `earnrate picks which of the user's credit cards earns the most for a purchase. Its wallet lists the cards they hold by product id, never card numbers; never ask for card numbers, expiry dates or security codes.
+const INSTRUCTIONS = `earnrate picks which of the user's credit cards earns the most for a purchase. best_cards_for and simulate_spending compare every card earnrate knows and need no wallet, for questions like "what's the best grocery card?" or "which cards fit my spending?". Its wallet lists the cards they hold by product id, never card numbers; never ask for card numbers, expiry dates or security codes.
 
 If a tool says there's no wallet yet, ask the user which cards they have, find each with search_cards, and add it with add_card. add_card and update_card reply with what a card still needs, such as category picks, memberships like Amazon Prime, or activated bonus categories. Ask the user about those and set them with update_card or set_memberships.`;
 const fail = (text) => ({
@@ -37,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;
@@ -45,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)}`;
         }
@@ -54,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) {
@@ -88,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,
@@ -100,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],
@@ -142,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)
@@ -194,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,
@@ -211,6 +244,176 @@ export function createEarnrateServer(deps) {
             structuredContent: comparison,
         };
     });
+    const CatalogCategory = z
+        .enum(ids)
+        .describe(`A spending category: ${catalog.categories.map((c) => `${c.id} (${c.name})`).join(', ')}.`);
+    const issuers = [...new Set(catalog.cards.map((c) => c.issuer))].sort();
+    const membershipIds = knownMemberships(catalog);
+    const CatalogFilters = {
+        kind: z
+            .enum(['any', 'cash', 'points'])
+            .optional()
+            .describe('cash: cash back cards only. points: points and miles cards only.'),
+        noAnnualFee: z
+            .boolean()
+            .optional()
+            .describe('Only cards with no annual fee.'),
+        business: z
+            .boolean()
+            .optional()
+            .describe('Business cards instead of personal ones.'),
+        issuer: z.enum(issuers).optional().describe("Only this issuer's cards."),
+        memberships: z
+            .array(z.enum(membershipIds))
+            .optional()
+            .describe("Memberships the user has, such as amazon-prime. Rates that need one they don't have are listed separately."),
+        valuation: z
+            .enum(['flat', 'points-heavy'])
+            .optional()
+            .describe('flat (default): points at their cash-out value, about 1¢. points-heavy: Amex MR and Chase UR at 1.7¢, for people who transfer points to airlines and hotels.'),
+    };
+    const settings = (args) => ({
+        filters: {
+            ...ALL_PERSONAL_CARDS,
+            kind: args.kind ?? 'any',
+            noAnnualFee: args.noAnnualFee ?? false,
+            business: args.business ?? false,
+            issuer: args.issuer ?? null,
+        },
+        memberships: args.memberships ?? [],
+        valuations: args.valuation ? VALUATION_PROFILES[args.valuation] : {},
+    });
+    server.registerTool('best_cards_for', {
+        title: 'Best cards for a purchase',
+        description: 'Ranks every card earnrate knows, not only the user\'s, for one purchase or category, each set up at its best (the right category pick, activated, cap unused), with its annual fee and what earning the rate takes. Use it for questions like "what\'s the best card for groceries?" or "which card should I get for Amazon?". It needs no wallet. For which of the user\'s own cards to use, call best_card_for_purchase instead. Mention the annual fee and any conditions alongside each card.',
+        inputSchema: z.object({
+            merchant: Merchant.optional(),
+            category: CatalogCategory.optional(),
+            amount: z
+                .number()
+                .positive()
+                .optional()
+                .describe('Purchase amount in US dollars, if known.'),
+            channel: ChannelInput,
+            ...CatalogFilters,
+        }),
+        outputSchema: ExplorationSchema,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, (args) => {
+        if (args.merchant === undefined && args.category === undefined)
+            return fail('Give a merchant or a category.');
+        const result = exploreCards(catalog, {
+            merchant: args.merchant ?? null,
+            category: args.merchant === undefined ? (args.category ?? null) : null,
+            amount: args.amount ?? null,
+            channel: args.channel ?? null,
+            date: deps.today(),
+        }, settings(args));
+        const trimmed = { ...result, ranked: result.ranked.slice(0, 10) };
+        return {
+            content: [{ type: 'text', text: formatExploration(trimmed, true) }],
+            structuredContent: trimmed,
+        };
+    });
+    server.registerTool('simulate_spending', {
+        title: 'Simulate a year of spending',
+        description: 'Spends the user\'s monthly amounts for a year across every card earnrate knows, and ranks single cards and two-card pairs by rewards minus annual fees. With compareToWallet, it starts from the user\'s wallet and ranks the cards that would add the most to it. Use it for "which card fits my spending?" or "is it worth adding a card?". Ask for rough monthly amounts if the user hasn\'t given them. It leaves out welcome bonuses.',
+        inputSchema: z.object({
+            spending: z
+                .array(z.object({
+                merchant: Merchant.optional(),
+                category: CatalogCategory.optional(),
+                monthly: z.number().positive().describe('US dollars a month.'),
+            }))
+                .min(1)
+                .describe('Monthly spending lines, each a category (grocery.supermarket, dining, gas, other) or a merchant (Amazon, Costco).'),
+            compareToWallet: z
+                .boolean()
+                .optional()
+                .describe("Rank the cards that would add the most to the user's wallet."),
+            ...CatalogFilters,
+        }),
+        outputSchema: SpendingSimulationSchema,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async (args) => {
+        if (args.spending.some((l) => l.merchant === undefined && l.category === undefined))
+            return fail('Each spending line needs a merchant or a category.');
+        const lines = resolveSpendLines(catalog, args.spending.map((l) => ({
+            merchant: l.merchant ?? null,
+            category: l.merchant === undefined ? (l.category ?? null) : null,
+            monthly: l.monthly,
+        })));
+        const unknown = lines.filter((l) => l.merchant.source === 'none');
+        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() };
+        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,
+                    valuations: {
+                        ...w.valuations,
+                        ...VALUATION_PROFILES[args.valuation],
+                    },
+                }
+                : w;
+            const result = simulateAdditions(catalog, valued, lines, options);
+            return {
+                content: [
+                    { type: 'text', text: formatAdditions(result, catalog, false) },
+                ],
+                structuredContent: {
+                    singles: [],
+                    pairs: [],
+                    current: result.current,
+                    additions: result.additions
+                        .slice(0, 10)
+                        .map(({ simulation: _, ...a }) => a),
+                },
+            };
+        }
+        const result = simulateCatalog(catalog, lines, options);
+        const text = formatCatalogSimulation(result, catalog, false);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: read?.start ? `${read.start}\n\n${text}` : text,
+                },
+            ],
+            structuredContent: {
+                singles: result.singles.slice(0, 10),
+                pairs: result.pairs.slice(0, 5),
+                current: null,
+                additions: [],
+            },
+        };
+    });
+    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.",
@@ -441,14 +644,13 @@ export function createEarnrateServer(deps) {
             openWorldHint: false,
         },
     }, ({ cardId }) => withWalletLock(deps.walletFile, async () => changed(await removeCard(deps.walletFile, catalog, cardId), `Removed ${cardName(cardId)} (${cardId}).`, false)));
-    const memberships = knownMemberships(catalog);
     server.registerTool('set_memberships', {
         title: 'Set memberships',
         description: "Sets the memberships that unlock some cards' rates, such as amazon-prime for Prime Visa's 5% or a Bank of America Preferred Rewards tier. Replaces the whole list, so include the ones to keep.",
         inputSchema: z.object({
             memberships: z
-                .array(z.enum(memberships))
-                .describe(`Every membership the user has. Known: ${memberships.join(', ')}.`),
+                .array(z.enum(membershipIds))
+                .describe(`Every membership the user has. Known: ${membershipIds.join(', ')}.`),
         }),
         outputSchema: WalletChangeSchema,
         annotations: {

package/dist/schema/card.js

@@ -133,6 +133,8 @@ export const CardSchema = z
     source_urls: z.array(z.url()).min(1),
     base_rate: z.number().nonnegative(),
     business: z.boolean().default(false),
+    // When the issuer stopped taking applications; cardholders keep earning.
+    applications_closed: IsoDate.optional(),
     annual_fee: z.number().nonnegative().optional(), // dollars
     // When the first year differs, usually a waived fee.
     first_year_fee: z.number().nonnegative().optional(),

package/dist/schema/category.js

@@ -6,6 +6,8 @@ export const CategorySchema = z.strictObject({
     // Typical MCCs, as hints for explanations and the LLM fallback. Matching is
     // by category, not by these.
     mccs: z.array(Mcc).default([]),
+    // Everyday words people search by ("groceries"), besides the name.
+    aliases: z.array(z.string().min(1)).default([]),
     note: z.string().optional(),
 });
 export const CategoriesFileSchema = z.array(CategorySchema).min(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "earnrate",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Picks the best credit card from your wallet for a merchant, and explains why",
   "keywords": [
     "credit cards",
@@ -40,11 +40,15 @@
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "prepack": "yarn build",
     "smoke:pack": "node scripts/smoke-pack.ts",
-    "site:deploy": "WRANGLER_SEND_METRICS=false wrangler deploy",
+    "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",
     "test:watch": "vitest",
     "coverage": "vitest run --coverage --coverage.include=src/**",
-    "typecheck": "tsc",
+    "typecheck": "tsc && tsc -p site",
     "lint": "eslint",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -57,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",
@@ -64,6 +69,7 @@
     "eslint": "^10.13.0",
     "eslint-config-prettier": "^10.1.8",
     "playwright": "1.64.1",
+    "preact": "^10.29.8",
     "prettier": "^3.9.10",
     "typescript": "~6.0.3",
     "typescript-eslint": "^8.72.0",