earnrate 0.1.0 → 0.1.2

package/dist/mcp/schemas.js

@@ -103,6 +103,7 @@ export const WalletSummarySchema = z.object({
         lastVerified: z.string(),
         verifiedBy: z.string(),
         dataIsStale: z.boolean(),
+        rotationGap: z.string().nullable(),
         caps: z.array(z.object({
             key: z.string(),
             rules: z.array(z.string()),
@@ -172,3 +173,48 @@ export const OfferComparisonSchema = z.object({
     withoutOffer: z.array(z.string()),
     notes: z.array(z.string()),
 });
+export const CardSearchSchema = z.object({
+    exact: z.boolean(),
+    cards: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        issuer: z.string(),
+        network: CardNetwork,
+        currency: z.string(),
+        annualFee: z.number().nullable(),
+        business: z.boolean(),
+        onlyAt: z.array(z.string()).nullable(),
+        held: z.boolean(),
+        choices: z.array(z.object({
+            id: z.string(),
+            pick: z.number(),
+            period: z.enum([
+                'month',
+                'quarter',
+                'calendar_year',
+                'until_changed',
+            ]),
+            options: z.array(z.string()),
+            default: z.array(z.string()).nullable(),
+        })),
+        memberships: z.array(z.string()),
+        activation: z.array(z.string()),
+        needsAnniversary: z.boolean(),
+    })),
+});
+export const WalletChangeSchema = z.object({
+    message: z.string(),
+    created: z.boolean(),
+    cardIds: z.array(z.string()),
+    memberships: z.array(z.string()),
+    notes: z.array(z.object({
+        kind: z.enum([
+            'pick',
+            'membership',
+            'activation',
+            'anniversary',
+            'rotation',
+        ]),
+        text: z.string(),
+    })),
+});

package/dist/mcp/server.js

@@ -1,19 +1,22 @@
 import { McpServer } from '@modelcontextprotocol/server';
 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 { 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 { compareOffers } from "../engine/offers.js";
 import { capBooking } from "../engine/record.js";
 import { recommend } from "../engine/recommend.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 { MerchantResolutionSchema, RecommendationSchema, OfferComparisonSchema, RecordResultSchema, WalletSummarySchema, } from "./schemas.js";
+import { CardSearchSchema, MerchantResolutionSchema, RecommendationSchema, OfferComparisonSchema, RecordResultSchema, WalletChangeSchema, WalletSummarySchema, } from "./schemas.js";
 const Merchant = z
     .string()
     .min(1)
@@ -23,13 +26,16 @@ 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.
+
+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) => ({
     content: [{ type: 'text', text }],
     isError: true,
 });
 const dollars = (n) => `$${n.toLocaleString('en-US', { maximumFractionDigits: 2 })}`;
 export function createEarnrateServer(deps) {
-    const server = new McpServer({ name: MCP_SERVER_NAME, version: deps.version });
+    const server = new McpServer({ name: MCP_SERVER_NAME, version: deps.version }, { instructions: INSTRUCTIONS });
     const { catalog } = deps;
     // Read on every call, so edits to the wallet file apply without a restart.
     async function wallet() {
@@ -38,6 +44,9 @@ export function createEarnrateServer(deps) {
             loaded = await loadWallet(deps.walletFile);
         }
         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 `Couldn't read the wallet at ${deps.walletFile}: ${e instanceof Error ? e.message : String(e)}`;
         }
         const problems = walletProblems(loaded, catalog);
@@ -145,13 +154,16 @@ export function createEarnrateServer(deps) {
                 ? `; chosen categories for ${c.chosen.period}${c.chosen.current ? '' : ' (out of date)'}`
                 : '';
             const onlyAt = c.onlyAt ? `; works only at ${c.onlyAt.join(', ')}` : '';
+            const rotation = c.rotationGap === null
+                ? ''
+                : `; rotating categories for ${c.rotationGap} not in earnrate yet`;
             const b = c.bonus;
             const bonus = b?.state === 'open' && b.spend !== null
                 ? `; welcome bonus ${dollars(b.spent)} of ${dollars(b.spend)} spent, due ${b.deadline ?? ''}`
                 : b
                     ? `; welcome bonus ${b.state}`
                     : '';
-            return `- ${c.checkoutLabel ?? c.cardName} (${c.cardId}): ${c.currency} at ${String(c.centsPerUnit)}¢${caps.length > 0 ? `; ${caps.join(', ')}` : ''}${chosen}${onlyAt}${bonus}`;
+            return `- ${c.checkoutLabel ?? c.cardName} (${c.cardId}): ${c.currency} at ${String(c.centsPerUnit)}¢${caps.length > 0 ? `; ${caps.join(', ')}` : ''}${chosen}${rotation}${onlyAt}${bonus}`;
         });
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
@@ -304,5 +316,149 @@ export function createEarnrateServer(deps) {
             structuredContent: output,
         };
     }));
+    const CardId = z
+        .string()
+        .min(1)
+        .describe('The card id from search_cards, e.g. chase-sapphire-preferred.');
+    const cardFields = {
+        checkoutLabel: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('How the card appears at checkout or in a browser wallet, e.g. "Amex Gold". Optional.'),
+        picks: z
+            .record(z.string(), z.array(z.string()).min(1))
+            .optional()
+            .describe('For cards where the cardholder picks bonus categories: choice id → option ids, from search_cards, e.g. {"five-percent": ["tv-internet-streaming", "fast-food"]}. Saved for the current period. Ask the user; don\'t guess.'),
+        anniversary: z
+            .string()
+            .regex(/^\d{2}-\d{2}$/)
+            .optional()
+            .describe("The account's anniversary as MM-DD, for cards whose cap resets on it."),
+        activated: z
+            .array(z.string())
+            .optional()
+            .describe('Rule ids the user has activated with the issuer, such as rotating categories. Replaces the current list.'),
+    };
+    // A card change reports what that card still needs; other changes don't.
+    function changed(result, message, cardChange = true) {
+        if (!result.ok)
+            return fail(result.error);
+        const output = {
+            message,
+            created: result.created,
+            cardIds: result.wallet.cards.map((c) => c.id),
+            memberships: result.wallet.memberships,
+            notes: result.notes,
+        };
+        const text = [
+            message,
+            `Wallet: ${output.cardIds.join(', ')}.`,
+            ...(cardChange ? [formatNotes(result.notes)] : []),
+        ].join('\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: output,
+        };
+    }
+    const cardInput = (args) => ({
+        id: args.cardId,
+        ...(args.checkoutLabel === undefined
+            ? {}
+            : { checkoutLabel: args.checkoutLabel }),
+        ...(args.picks === undefined ? {} : { picks: args.picks }),
+        ...(args.anniversary === undefined
+            ? {}
+            : { anniversary: args.anniversary }),
+        ...(args.activated === undefined ? {} : { activated: args.activated }),
+    });
+    const cardName = (id) => catalog.cards.find((c) => c.id === id)?.name ?? id;
+    server.registerTool('search_cards', {
+        title: 'Search cards',
+        description: 'Finds credit cards in earnrate\'s catalog by name or issuer, e.g. "sapphire", "amex gold" or "bofa". Returns each card\'s id (for add_card), network, annual fee, whether it\'s already in the wallet, and what it needs set up: category picks and their options, memberships, activations. Leave the query out to list every card. US cards only.',
+        inputSchema: z.object({
+            query: z
+                .string()
+                .optional()
+                .describe('Card name or issuer, as the user said it.'),
+        }),
+        outputSchema: CardSearchSchema,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ query }) => {
+        const held = await loadWallet(deps.walletFile).catch(() => null);
+        const result = searchCards(catalog, query ?? '', held, deps.today());
+        const header = result.exact
+            ? ''
+            : result.cards.length > 0
+                ? 'No card matched every word. Closest:\n'
+                : `No card matched "${query ?? ''}". earnrate covers ${String(catalog.cards.length)} US cards; list them all by leaving the query out.`;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: header + result.cards.map(formatCardInfo).join('\n'),
+                },
+            ],
+            structuredContent: result,
+        };
+    });
+    server.registerTool('add_card', {
+        title: 'Add a card',
+        description: "Adds a card the user holds to their wallet by its id from search_cards, creating the wallet if there isn't one. The reply says what the card still needs (category picks, memberships, activations); ask the user about those. Stores only the card's product id and settings, never card numbers.",
+        inputSchema: z.object({ cardId: CardId, ...cardFields }),
+        outputSchema: WalletChangeSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, (args) => withWalletLock(deps.walletFile, async () => {
+        const result = await addCard(deps.walletFile, catalog, cardInput(args), deps.today());
+        return changed(result, `Added ${cardName(args.cardId)} (${args.cardId})${result.ok && result.created ? `, starting a new wallet at ${deps.walletFile}` : ''}.`);
+    }));
+    server.registerTool('update_card', {
+        title: 'Update a card',
+        description: 'Changes settings on a card already in the wallet: its category picks for this period, checkout label, anniversary or activated categories. Picks for the current period are merged with the ones already saved. Use it when the user picks new categories, such as each quarter on U.S. Bank Cash+.',
+        inputSchema: z.object({ cardId: CardId, ...cardFields }),
+        outputSchema: WalletChangeSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, (args) => withWalletLock(deps.walletFile, async () => changed(await updateCard(deps.walletFile, catalog, cardInput(args), deps.today()), `Updated ${cardName(args.cardId)} (${args.cardId}).`)));
+    server.registerTool('remove_card', {
+        title: 'Remove a card',
+        description: "Removes a card from the wallet, with its tracked cap usage and bonus progress. Only when the user says they no longer have it or don't want it considered.",
+        inputSchema: z.object({ cardId: CardId }),
+        outputSchema: WalletChangeSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            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(', ')}.`),
+        }),
+        outputSchema: WalletChangeSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, (args) => withWalletLock(deps.walletFile, async () => changed(await setMemberships(deps.walletFile, catalog, args.memberships), args.memberships.length > 0
+        ? `Memberships set to ${args.memberships.join(', ')}.`
+        : 'Memberships cleared.', false)));
     return server;
 }

package/dist/schema/card.js

@@ -12,7 +12,13 @@ export const CapSchema = z.strictObject({
     period: CapPeriod,
     then_rate: z.number().nonnegative(),
 });
-export const SharedCapSchema = CapSchema.extend({ id: KebabId });
+export const SharedCapSchema = CapSchema.extend({
+    id: KebabId,
+    // Rotating categories (Freedom Flex): every rule on this cap covers one
+    // dated period, and a period with no rule means the issuer's categories
+    // aren't in the data yet, not that there's no bonus.
+    rotating: z.literal(true).optional(),
+});
 const hasAny = (m) => Object.values(m).some((v) => v === true || (v !== undefined && v.length > 0));
 // Kinds combine with AND, values within a kind with OR: `{ merchants:
 // [lyft], categories: [transit] }` is a Lyft purchase that codes as transit.
@@ -75,21 +81,40 @@ export const WelcomeOfferSchema = z
 export const ChoiceSchema = z.strictObject({
     id: KebabId,
     pick: z.number().int().positive(),
-    period: z.enum(['month', 'quarter', 'calendar_year']),
+    // `until_changed`: the pick carries over until the cardholder changes it,
+    // so a pick made in an earlier period is still current.
+    period: z.enum(['month', 'quarter', 'calendar_year', 'until_changed']),
     // Option ids that apply when the wallet hasn't picked, e.g. Bilt's dining.
     default: z.array(KebabId).min(1).optional(),
-    // Option id → what that option covers: a list of categories, or, when the
-    // issuer publishes the only qualifying stores, `{ merchants: [...] }`.
+    // Option id → what that option covers: a list of categories; or, when the
+    // issuer publishes the only qualifying stores, `{ merchants: [...] }`; or,
+    // for "online shopping" picks, `{ channel: online, exclude: [...] }`, any
+    // online purchase outside the excluded categories.
     options: z.record(KebabId, z.union([
         z
             .array(CategoryId)
             .min(1)
-            .transform((categories) => ({ categories, merchants: [] })),
+            .transform((categories) => ({
+            categories,
+            merchants: [],
+            online: null,
+        })),
         z
             .strictObject({ merchants: z.array(KebabId).min(1) })
             .transform(({ merchants }) => ({
             categories: [],
             merchants,
+            online: null,
+        })),
+        z
+            .strictObject({
+            channel: z.literal('online'),
+            exclude: z.array(CategoryId).default([]),
+        })
+            .transform(({ exclude }) => ({
+            categories: [],
+            merchants: [],
+            online: { exclude },
         })),
     ])),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "earnrate",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Picks the best credit card from your wallet for a merchant, and explains why",
   "keywords": [
     "credit cards",
@@ -21,7 +21,7 @@
   "mcpName": "io.github.cwasley/earnrate",
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "bin": {
     "earnrate": "./dist/cli/bin.js",