rightcard-mcp 0.1.0

package/dist/model.js

@@ -0,0 +1,133 @@
+// Mirrors Models/CreditCard.swift, Models/SpendCategory.swift, SupabaseModels.swift.
+// Every rule here has a Swift twin; parity is enforced by test/parity.test.ts.
+export const ALL_CATEGORIES = ["dining", "grocery", "travel", "gas", "online", "drugstore", "transit", "streaming", "general"];
+export const CATEGORY_DISPLAY = {
+    dining: "Dining", grocery: "Grocery", travel: "Travel", gas: "Gas", online: "Online",
+    drugstore: "Drugstores", transit: "Transit", streaming: "Streaming", general: "General",
+};
+export const CURRENCY_DISPLAY = {
+    points: "points", miles: "miles", cashback: "cash back",
+};
+/** Supabase `cards` row → CreditCard (SupabaseCard.toCreditCard). */
+export function cardFromRow(row) {
+    const multipliers = {};
+    const sm = row.standard_multipliers ?? {};
+    for (const [k, v] of Object.entries(sm)) {
+        const key = k === "other" ? "general" : k;
+        multipliers[key] = fieldFromJSON(v);
+    }
+    if (multipliers["general"] === undefined)
+        multipliers["general"] = Number(row.base_rate ?? 1);
+    const cur = row.reward_currency;
+    return {
+        id: row.id,
+        displayName: row.name,
+        issuer: row.issuer ?? null,
+        rewardCurrency: cur === "points" || cur === "miles" || cur === "cashback" ? cur : null,
+        multipliers,
+        annualFee: row.annual_fee ?? null,
+        verifyStatus: row.verify_status ?? null,
+    };
+}
+function fieldFromJSON(v) {
+    if (typeof v === "number")
+        return v;
+    if (v && typeof v === "object") {
+        const values = {};
+        let def = 1;
+        for (const [k, x] of Object.entries(v)) {
+            if (k === "default")
+                def = Number(x);
+            else
+                values[k] = Number(x);
+        }
+        return { default: def, values };
+    }
+    return 1;
+}
+function normalizeSubKey(subKey) {
+    if (!subKey || subKey.trim() === "")
+        return null;
+    let s = subKey.trim().toLowerCase().replace(/-/g, "_").replace(/ /g, "_");
+    if (s === "instore" || s === "in_store" || s === "in_store_")
+        return "in_store";
+    return s;
+}
+function fieldValue(f, subKey) {
+    if (typeof f === "number")
+        return f;
+    if (subKey == null)
+        return f.default;
+    const k = subKey.trim().toLowerCase().replace(/-/g, "_").replace(/ /g, "_");
+    return f.values[k] ?? f.default;
+}
+/** CreditCard.multiplier(for:subKey:) — direct key → "other" for general → "general" → 1.0 */
+export function multiplier(card, category, subKey) {
+    const key = category; // multiplierKey == rawValue for every case
+    const sub = normalizeSubKey(subKey);
+    const direct = card.multipliers[key];
+    if (direct !== undefined)
+        return fieldValue(direct, sub);
+    if (key === "general" && card.multipliers["other"] !== undefined)
+        return fieldValue(card.multipliers["other"], null);
+    if (card.multipliers["general"] !== undefined)
+        return fieldValue(card.multipliers["general"], null);
+    return 1.0;
+}
+/** CreditCard.hasAnyReward */
+export function hasAnyReward(card) {
+    return Object.values(card.multipliers).some((f) => typeof f === "number" ? f > 1.0 : f.default > 1.0 || Object.values(f.values).some((v) => v > 1.0));
+}
+export function overrideFromRow(r) {
+    return {
+        id: String(r.id), cardId: r.card_id, category: r.category, bonusRate: Number(r.bonus_rate),
+        startDate: r.start_date, endDate: r.end_date, requiresActivation: !!r.requires_activation,
+        label: r.label ?? null, merchant: r.merchant ?? null,
+    };
+}
+/** UTC-day canon (SupabaseDateFormat.utcCalendar): compare yyyy-MM-dd strings as UTC days. */
+export function utcDay(now) {
+    return now.toISOString().slice(0, 10);
+}
+export function overrideIsActive(o, now) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(o.startDate) || !/^\d{4}-\d{2}-\d{2}$/.test(o.endDate))
+        return false;
+    const today = utcDay(now);
+    return today >= o.startDate && today <= o.endDate;
+}
+/** SupabaseOverride.isPermanentMerchantBenefit: merchant-scoped, no activation, ends > 2 years out. */
+export function isPermanentMerchantBenefit(o, now) {
+    if (!o.merchant || o.merchant === "" || o.requiresActivation)
+        return false;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(o.endDate))
+        return false;
+    const twoYears = new Date(Date.UTC(now.getUTCFullYear() + 2, now.getUTCMonth(), now.getUTCDate()));
+    const end = new Date(o.endDate + "T00:00:00Z");
+    return end.getTime() > twoYears.getTime();
+}
+export function merchantFromRow(r) {
+    const cat = ALL_CATEGORIES.includes(r.category) ? r.category : "general";
+    return {
+        id: r.id, displayName: r.display_name, category: cat, subKey: r.sub_key ?? null,
+        isOnline: !!r.is_online, aliases: Array.isArray(r.aliases) ? r.aliases : [], merchantType: r.merchant_type ?? null,
+    };
+}
+/** Merchant.exclusionCaveat */
+export function exclusionCaveat(m) {
+    switch (m.merchantType) {
+        case "superstore":
+            return `${m.displayName} usually codes as a superstore (not a supermarket), so grocery bonuses often don't post — this is your best guaranteed card.`;
+        case "warehouse_club":
+            return `${m.displayName} codes as a warehouse club, so category bonuses usually don't post — this is your best guaranteed card.`;
+        default:
+            return null;
+    }
+}
+/** Merchant.isCuratedBrand */
+export function isCuratedBrand(m) {
+    if (m.aliases.length > 0)
+        return true;
+    if (m.merchantType && m.merchantType !== "standard")
+        return true;
+    return false;
+}

package/dist/search.d.ts

@@ -0,0 +1,27 @@
+import { type Merchant } from "./model.js";
+/** Merchant.searchNormalized */
+export declare function searchNormalized(s: string): string;
+export declare function compactForm(normalized: string): string;
+export declare function entityKey(s: string): string;
+/** Merchant.withinOneEdit — Damerau-Levenshtein ≤ 1 */
+export declare function withinOneEdit(aStr: string, bStr: string): boolean;
+export interface SearchForms {
+    raw: string;
+    norm: string;
+    compact: string;
+}
+export declare const searchForms: (raw: string) => SearchForms;
+/** Merchant.matchScore(queryNorm:queryCompact:rawQuery:candidates:) */
+export declare function matchScore(q: string, qc: string, rawQuery: string, candidates: SearchForms[]): number | null;
+export interface IndexEntry {
+    merchant: Merchant;
+    candidates: SearchForms[];
+    entityKey: string;
+    displayNorm: string;
+}
+export declare function buildIndex(directory: Merchant[]): IndexEntry[];
+/** MerchantSearchViewModel.rankedBrandMatches(query:index:offerKeys:limit:) */
+export declare function rankedBrandMatches(query: string, index: IndexEntry[], offerKeys?: Set<string>, limit?: number): {
+    merchant: Merchant;
+    hasOffer: boolean;
+}[];

package/dist/search.js

@@ -0,0 +1,209 @@
+// Mirrors Merchant.searchNormalized / compactForm / matchScore / entityKey / withinOneEdit
+// and MerchantSearchViewModel.rankedBrandMatches (ranking + family collapse).
+import { merchantMatches } from "./matching.js";
+import { isCuratedBrand } from "./model.js";
+const normCache = new Map();
+/** Merchant.searchNormalized */
+export function searchNormalized(s) {
+    const hit = normCache.get(s);
+    if (hit !== undefined)
+        return hit;
+    // diacritic-insensitive + case-insensitive fold
+    let t = s.normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase();
+    for (const junk of ["’", "'", "®", "™", "."])
+        t = t.split(junk).join("");
+    t = t.replace(/&/g, " and ");
+    t = t.replace(/(?<=[\p{L}\p{N}])\+(?=[\p{L}\p{N}])/gu, " and ");
+    t = t.replace(/(?<=\s)\+(?=\s)/g, " and ");
+    t = t.replace(/\+/g, " plus ");
+    for (const dash of ["-", "–", "—", "/"])
+        t = t.split(dash).join(" ");
+    let words = t.split(/\s+/).filter((w) => w.length > 0);
+    if (words.length > 1 && words[0] === "the")
+        words = words.slice(1);
+    const result = words.join(" ");
+    if (normCache.size > 8192)
+        normCache.clear();
+    normCache.set(s, result);
+    return result;
+}
+export function compactForm(normalized) {
+    return normalized.split(" ").filter((w) => w !== "and" && w.length > 0).join("");
+}
+export function entityKey(s) {
+    return searchNormalized(s).replace(/ /g, "");
+}
+/** Merchant.withinOneEdit — Damerau-Levenshtein ≤ 1 */
+export function withinOneEdit(aStr, bStr) {
+    if (aStr === bStr)
+        return true;
+    const a = [...aStr], b = [...bStr];
+    if (Math.abs(a.length - b.length) > 1)
+        return false;
+    if (a.length === b.length) {
+        const diffs = [];
+        for (let i = 0; i < a.length; i++)
+            if (a[i] !== b[i]) {
+                diffs.push(i);
+                if (diffs.length > 2)
+                    return false;
+            }
+        if (diffs.length === 1)
+            return true;
+        return diffs.length === 2 && diffs[1] === diffs[0] + 1 && a[diffs[0]] === b[diffs[1]] && a[diffs[1]] === b[diffs[0]];
+    }
+    const [long, short] = a.length > b.length ? [a, b] : [b, a];
+    let i = 0, j = 0, skipped = false;
+    while (i < long.length && j < short.length) {
+        if (long[i] === short[j]) {
+            i++;
+            j++;
+        }
+        else if (!skipped) {
+            skipped = true;
+            i++;
+        }
+        else
+            return false;
+    }
+    return true;
+}
+export const searchForms = (raw) => {
+    const norm = searchNormalized(raw);
+    return { raw, norm, compact: compactForm(norm) };
+};
+/** Merchant.matchScore(queryNorm:queryCompact:rawQuery:candidates:) */
+export function matchScore(q, qc, rawQuery, candidates) {
+    if ([...q].length < 2)
+        return null;
+    let best = -1;
+    for (const c of candidates) {
+        const n = c.norm;
+        if (n.length === 0)
+            continue;
+        if (n === q) {
+            best = Math.max(best, 100);
+            continue;
+        }
+        if (qc.length > 0 && c.compact === qc)
+            best = Math.max(best, 95);
+        if (n.startsWith(q))
+            best = Math.max(best, 85);
+        if ([...qc].length >= 3 && c.compact.startsWith(qc))
+            best = Math.max(best, 80);
+        if (q.startsWith(n + " "))
+            best = Math.max(best, 75);
+        const words = n.split(" ");
+        if (words.slice(1).some((w) => w.startsWith(q)))
+            best = Math.max(best, 70);
+        if (n.includes(q))
+            best = Math.max(best, 55);
+        if (best < 45 && merchantMatches(c.raw, rawQuery))
+            best = Math.max(best, 45);
+        if (best < 30 && [...q].length >= 5) {
+            if (withinOneEdit(n, q) || words.some((w) => [...w].length >= 5 && withinOneEdit(w, q)))
+                best = Math.max(best, 30);
+        }
+    }
+    return best >= 0 ? best : null;
+}
+export function buildIndex(directory) {
+    return directory.map((m) => ({
+        merchant: m,
+        candidates: [m.displayName, ...m.aliases].map(searchForms),
+        entityKey: entityKey(m.displayName),
+        displayNorm: searchNormalized(m.displayName),
+    }));
+}
+/** Swift localizedCaseInsensitiveCompare ascending (approximation: locale compare, case-insensitive). */
+function nameCompare(a, b) {
+    return a.localeCompare(b, "en", { sensitivity: "accent" });
+}
+/** MerchantSearchViewModel.rankedBrandMatches(query:index:offerKeys:limit:) */
+export function rankedBrandMatches(query, index, offerKeys = new Set(), limit = 6) {
+    const q = searchNormalized(query);
+    if ([...q].length < 2)
+        return [];
+    const qc = compactForm(q);
+    const ranked = [];
+    for (const e of index) {
+        const score = matchScore(q, qc, query, e.candidates);
+        if (score === null)
+            continue;
+        const hasOffer = offerKeys.has(e.entityKey);
+        const specific = (e.merchant.category !== "general" || isCuratedBrand(e.merchant)) ? 1 : 0;
+        const boost = hasOffer && score >= 70 ? 400 : 0;
+        ranked.push([e, score * 2 + specific + boost, hasOffer]);
+    }
+    ranked.sort((a, b) => a[1] !== b[1] ? b[1] - a[1] : nameCompare(a[0].merchant.displayName, b[0].merchant.displayName));
+    const qKey = q.replace(/ /g, "");
+    const glueSuffixes = new Set(["com", "net", "online", "us", "usa", "store", "shop"]);
+    const extendsName = (key, norm, base) => {
+        if (norm.startsWith(base.norm + " "))
+            return true;
+        if (key.startsWith(base.key) && glueSuffixes.has(key.slice(base.key.length)))
+            return true;
+        let glued = "";
+        const words = norm.split(" ");
+        for (let i = 0; i < words.length; i++) {
+            glued += words[i].replace(/[^\p{L}\p{N}]/gu, "");
+            if (glued === base.key)
+                return i < words.length - 1;
+            if (!base.key.startsWith(glued))
+                return false;
+        }
+        return false;
+    };
+    const kept = [];
+    let repCategory = null;
+    outer: for (const row of ranked) {
+        if (kept.length >= limit)
+            break;
+        const e = row[0];
+        for (let i = 0; i < kept.length; i++) {
+            const k = kept[i];
+            if (k[0].entityKey === e.entityKey)
+                continue outer;
+            if (e.merchant.category === "general" && e.entityKey === "new" + k[0].entityKey)
+                continue outer;
+            if (k[0].merchant.category === "general" && k[0].entityKey === "new" + e.entityKey) {
+                kept[i] = row;
+                continue outer;
+            }
+        }
+        const inQueryFamily = e.displayNorm === q || extendsName(e.entityKey, e.displayNorm, { key: qKey, norm: q });
+        if (inQueryFamily) {
+            if (row[2]) {
+                kept.push(row);
+                if (repCategory === null)
+                    repCategory = e.merchant.category;
+            }
+            else if (e.displayNorm === q && isCuratedBrand(e.merchant)) {
+                kept.push(row);
+                if (repCategory === null)
+                    repCategory = e.merchant.category;
+            }
+            else if (repCategory !== null) {
+                if (e.merchant.category === repCategory || e.merchant.category === "general")
+                    continue;
+                kept.push(row);
+            }
+            else {
+                repCategory = e.merchant.category;
+                kept.push(row);
+            }
+            continue;
+        }
+        if (!row[2]) {
+            for (const k of kept) {
+                if (extendsName(e.entityKey, e.displayNorm, { key: k[0].entityKey, norm: k[0].displayNorm })) {
+                    const sameAnswer = e.merchant.category === k[0].merchant.category || e.merchant.category === "general";
+                    if (sameAnswer)
+                        continue outer;
+                }
+            }
+        }
+        kept.push(row);
+    }
+    return kept.map((r) => ({ merchant: r[0].merchant, hasOffer: r[2] }));
+}

package/dist/stdio.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/stdio.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Local stdio server: `npx rightcard-mcp`. Reads the public catalog once an hour,
+// answers over stdin/stdout, sends nothing anywhere else.
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildServer } from "./tools.js";
+import { catalogCache } from "./data.js";
+const server = buildServer(catalogCache());
+await server.connect(new StdioServerTransport());

package/dist/tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Catalog } from "./data.js";
+export declare function buildServer(getCatalog: () => Promise<Catalog>): McpServer;

package/dist/tools.js

@@ -0,0 +1,205 @@
+// The MCP surface (RIGHTCARD_MCP_SPEC.md §5). Read-only. Every answer carries `basis`
+// and `caveats`; verified rows only in rankings; quarantined cards are NAMED, never ranked.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { ALL_CATEGORIES, exclusionCaveat, hasAnyReward, multiplier, overrideIsActive, isPermanentMerchantBenefit } from "./model.js";
+import { recommend, formatPercent, formatMultiplier } from "./engine.js";
+import { rankedBrandMatches, searchNormalized } from "./search.js";
+import { makeValuation, centsPerPoint, withPooling, effectiveProgram, PROGRAM_DISPLAY, TRAVEL_CPP } from "./valuation.js";
+import { specFor, isConfigurable } from "./configurable.js";
+const CategorySchema = z.enum(ALL_CATEGORIES);
+const PRIVACY = "RightCard never receives a bank login, balances, or transactions. This tool takes a list of card ids and a store name, returns an answer, and stores nothing.";
+function cardSummary(c) {
+    return {
+        id: c.id, name: c.displayName, issuer: c.issuer, reward_currency: c.rewardCurrency,
+        verify_status: c.verifyStatus ?? "unknown", annual_fee: c.annualFee ?? null,
+    };
+}
+function resolveWallet(catalog, ids) {
+    const cards = [];
+    const unknown = [];
+    const unverified = [];
+    for (const id of ids) {
+        const c = catalog.cardsById.get(id);
+        if (!c) {
+            unknown.push(id);
+            continue;
+        }
+        if (c.verifyStatus !== "verified" && !isConfigurable(c))
+            unverified.push(id);
+        cards.push(c);
+    }
+    return { cards, unknown, unverified };
+}
+function resolveMerchant(catalog, name) {
+    return rankedBrandMatches(name, catalog.index)[0]?.merchant ?? null;
+}
+function shapeAnswer(r, merchant, mode, unverified) {
+    const caveats = [];
+    if (merchant) {
+        const cv = exclusionCaveat(merchant);
+        if (cv)
+            caveats.push(cv);
+    }
+    if (r.tieNote)
+        caveats.push(r.tieNote);
+    if (r.portalNote)
+        caveats.push(r.portalNote);
+    if (unverified.length)
+        caveats.push(`Not yet verified by two independent sources (ranked on published data, treat with care): ${unverified.join(", ")}.`);
+    return {
+        card_id: r.cardId, card_name: r.cardName, rate_display: r.rateDisplay,
+        value_per_dollar_cents: r.loggableRate, basis: r.valuationBasis, valuation: mode,
+        reason: r.reason, details: r.breakdownLines, value_math: r.valueMath,
+        subcategory_split: r.subcategoryBreakdown, caveats, privacy: PRIVACY,
+    };
+}
+export function buildServer(getCatalog) {
+    const server = new McpServer({ name: "rightcard", version: "0.1.0" }, {
+        instructions: "RightCard answers 'which of these credit cards should pay here?' from bank-published, two-source-verified reward data. " +
+            "Pass the user's card ids (from search_cards) plus a store name or a category. Cash value is the default; ask for valuation='points' to value points at conservative per-program travel values. " +
+            "Every answer includes honest caveats: superstores/warehouse clubs that do not post grocery bonuses, rotating quarters that need activation, ties. " + PRIVACY,
+    });
+    server.registerTool("best_card", {
+        title: "Best card for a store or category",
+        description: "Which of the given cards earns the most at a store (merchant) or for a spend category, today. Returns the card, the honest rate, why, and caveats (merchant-code traps, activation, ties). Base rates + rotating bonuses + built-in card benefits only; a user's personal bank offers live on their phone and are not consulted here.",
+        inputSchema: {
+            wallet: z.array(z.string()).min(1).describe("Card ids the person holds (from search_cards)."),
+            merchant: z.string().optional().describe("Store name, e.g. 'Costco', 'Whole Foods', 'Uber'. Use this OR category."),
+            category: CategorySchema.optional().describe("Spend category when there is no specific store."),
+            valuation: z.enum(["cash", "points"]).default("cash").describe("'cash' counts every point at 1¢ (default). 'points' values points per program at conservative travel values."),
+            on: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("Date (YYYY-MM-DD, UTC) for rotating windows; defaults to today."),
+            chosen_categories: z.record(z.string(), z.array(CategorySchema)).optional().describe("For choose-your-category cards (Citi Custom Cash, BofA Customized, Venmo): card id → the categories the person set."),
+        },
+    }, async ({ wallet, merchant, category, valuation, on, chosen_categories }) => {
+        const catalog = await getCatalog();
+        const { cards, unknown, unverified } = resolveWallet(catalog, wallet);
+        if (cards.length === 0)
+            return err(`No known cards in wallet. Unknown ids: ${unknown.join(", ")}. Use search_cards to find ids.`);
+        let cat = category;
+        let subKey = null;
+        let dir = null;
+        if (merchant) {
+            dir = resolveMerchant(catalog, merchant);
+            cat = dir?.category ?? cat ?? "general";
+            subKey = dir?.subKey ?? null;
+        }
+        if (!cat)
+            return err("Pass a merchant or a category.");
+        const mode = valuation === "points" ? "smart" : "cash";
+        const configs = {};
+        for (const [k, v] of Object.entries(chosen_categories ?? {}))
+            configs[k] = new Set(v);
+        const now = on ? new Date(on + "T00:00:00Z") : new Date();
+        const r = recommend({ cards, category: cat, subKey, merchantName: merchant ?? null, overrides: catalog.overrides,
+            valuation: makeValuation(mode), cardConfigs: configs, now });
+        if (!r)
+            return err("No recommendation could be computed.");
+        const answer = {
+            ...shapeAnswer(r, dir, valuation, unverified),
+            merchant: dir ? { id: dir.id, name: dir.displayName, category: dir.category, merchant_type: dir.merchantType } : null,
+            category: cat, unknown_card_ids: unknown,
+        };
+        return ok(answer);
+    });
+    server.registerTool("lookup_merchant", {
+        title: "How a store is coded",
+        description: "The store's reward category as RightCard's directory files it, its merchant type, and the merchant-code caveat when a category bonus usually will not post there (superstores like Walmart/Target, warehouse clubs like Costco/Sam's). Same ranking the app uses.",
+        inputSchema: { name: z.string().min(2) },
+    }, async ({ name }) => {
+        const catalog = await getCatalog();
+        const rows = rankedBrandMatches(name, catalog.index);
+        if (rows.length === 0)
+            return ok({ query: name, found: false, note: "Not in the directory. The app would classify it by name and answer with the base rate." });
+        const top = rows[0].merchant;
+        return ok({
+            query: name, found: true,
+            match: { id: top.id, name: top.displayName, category: top.category, sub_key: top.subKey, merchant_type: top.merchantType, caveat: exclusionCaveat(top) },
+            family: rows.slice(1).map((r) => ({ id: r.merchant.id, name: r.merchant.displayName, category: r.merchant.category, merchant_type: r.merchant.merchantType })),
+        });
+    });
+    server.registerTool("search_cards", {
+        title: "Find card ids",
+        description: "Search RightCard's catalog by card or issuer name to get the ids to pass into best_card. Verified cards first; unverified cards are flagged, never hidden.",
+        inputSchema: { query: z.string().min(2), issuer: z.string().optional(), limit: z.number().int().min(1).max(50).default(12) },
+    }, async ({ query, issuer, limit }) => {
+        const catalog = await getCatalog();
+        const q = searchNormalized(query);
+        const toks = q.split(" ").filter((t) => t.length > 0);
+        let hits = catalog.cards.filter((c) => {
+            if (issuer && !(c.issuer ?? "").toLowerCase().includes(issuer.toLowerCase()))
+                return false;
+            const hay = searchNormalized(`${c.displayName} ${c.issuer ?? ""} ${c.id.replace(/_/g, " ")}`);
+            return toks.every((t) => hay.includes(t));
+        });
+        hits.sort((a, b) => (rank(a) - rank(b)) || a.displayName.localeCompare(b.displayName));
+        return ok({ query, results: hits.slice(0, limit).map(cardSummary), total: hits.length });
+        function rank(c) { return c.verifyStatus === "verified" ? 0 : (hasAnyReward(c) ? 1 : 2); }
+    });
+    server.registerTool("card", {
+        title: "A card's verified rates",
+        description: "Everything RightCard knows about one card: rates by category, base rate, currency, annual fee, verification status, live rotating windows, and the choose-your-category spec if it has one.",
+        inputSchema: { id: z.string() },
+    }, async ({ id }) => {
+        const catalog = await getCatalog();
+        const c = catalog.cardsById.get(id);
+        if (!c)
+            return err(`Unknown card id '${id}'. Use search_cards.`);
+        const now = new Date();
+        const rates = {};
+        for (const cat of ALL_CATEGORIES) {
+            const m = multiplier(c, cat, null);
+            rates[cat] = c.rewardCurrency === "cashback" || !c.rewardCurrency ? formatPercent(m) : formatMultiplier(m);
+        }
+        const rot = catalog.overrides.filter((o) => o.cardId === id).map((o) => ({
+            category: o.category, merchant: o.merchant, bonus_rate: o.bonusRate, start: o.startDate, end: o.endDate,
+            activation_required: o.requiresActivation, label: o.label,
+            status: isPermanentMerchantBenefit(o, now) ? "card benefit" : overrideIsActive(o, now) ? "live now" : (o.startDate > now.toISOString().slice(0, 10) ? "upcoming" : "past"),
+        }));
+        const spec = specFor(c);
+        const v = withPooling(makeValuation("smart"), [c]);
+        return ok({
+            ...cardSummary(c), rates_by_category: rates,
+            points_program: c.rewardCurrency && c.rewardCurrency !== "cashback" ? { name: PROGRAM_DISPLAY[effectiveProgram(v, c)], travel_cents_per_point: centsPerPoint(v, c) } : null,
+            rotating_and_benefits: rot,
+            choose_your_category: spec ? { bonus_rate: spec.bonusRate, slots: spec.slots, eligible: spec.eligible, note: spec.note } : null,
+            verification_note: c.verifyStatus === "verified" ? "Two independent sources agreed on these rates." : `verify_status=${c.verifyStatus ?? "unknown"}: not yet confirmed by two sources; shown, not vouched for.`,
+        });
+    });
+    server.registerTool("rotating_calendar", {
+        title: "Rotating 5% windows",
+        description: "Live and upcoming rotating-category windows (Freedom Flex, Discover it, Citi Dividend…) and permanent merchant benefits, from the same verified data as the app. Optionally filter by card id.",
+        inputSchema: { card_id: z.string().optional() },
+    }, async ({ card_id }) => {
+        const catalog = await getCatalog();
+        const today = new Date().toISOString().slice(0, 10);
+        const rows = catalog.overrides.filter((o) => !card_id || o.cardId === card_id).filter((o) => o.endDate >= today)
+            .map((o) => ({ card_id: o.cardId, card_name: catalog.cardsById.get(o.cardId)?.displayName ?? o.cardId,
+            category: o.category, merchant: o.merchant, bonus_rate: o.bonusRate, start: o.startDate, end: o.endDate,
+            activation_required: o.requiresActivation, label: o.label,
+            status: isPermanentMerchantBenefit(o, new Date()) ? "card benefit" : o.startDate <= today ? "live now" : "upcoming" }))
+            .sort((a, b) => a.start.localeCompare(b.start) || a.card_id.localeCompare(b.card_id));
+        return ok({ as_of: today, windows: rows, note: "A window appears only after it passed two-source verification. Nothing here is predicted." });
+    });
+    server.registerResource("catalog", "rightcard://catalog", { title: "Verified card catalog", mimeType: "application/json" }, async (uri) => {
+        const catalog = await getCatalog();
+        return { contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(catalog.cards.map(cardSummary)) }] };
+    });
+    server.registerResource("valuation", "rightcard://valuation", { title: "How points are valued", mimeType: "application/json" }, async (uri) => ({
+        contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify({ mode_cash: "every point = 1¢", mode_points_travel_cents_per_point: TRAVEL_CPP, source: "Conservative blended baselines (The Points Guy, Bankrate, Frequent Miler), Q2 2026." }) }],
+    }));
+    server.registerPrompt("which-card", {
+        title: "Which card should I use here?",
+        description: "Ask RightCard for the best card at a store, given the cards you hold.",
+        argsSchema: { cards: z.string().describe("Your cards, in your own words"), store: z.string().describe("Where you're paying") },
+    }, ({ cards, store }) => ({
+        messages: [{ role: "user", content: { type: "text", text: `I hold these cards: ${cards}. First call search_cards to resolve each to an id, then call best_card with the wallet and merchant "${store}". Tell me the card, the rate, and repeat any caveat about the store's merchant code or activation exactly as returned.` } }],
+    }));
+    return server;
+}
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }], structuredContent: data };
+}
+function err(message) {
+    return { isError: true, content: [{ type: "text", text: message }] };
+}

package/dist/valuation.d.ts

@@ -0,0 +1,24 @@
+import type { CreditCard } from "./model.js";
+export type ValuationMode = "cash" | "smart";
+export type RewardProgram = "cash" | "amexMR" | "chaseUR" | "capOneMiles" | "citiTYP" | "wellsFargo" | "bilt" | "tdRewards" | "scenePlus" | "rbcAvion" | "bmoRewards" | "hyatt" | "marriott" | "ihg" | "hilton" | "delta" | "united" | "american" | "southwest" | "jetBlue" | "alaska" | "avios" | "aeroplan" | "fixedValue" | "genericPoints" | "genericMiles";
+export declare const PROGRAM_DISPLAY: Record<RewardProgram, string>;
+export declare const TRAVEL_CPP: Record<RewardProgram, number>;
+/** RewardProgram.cashOutCPP */
+export declare function cashOutCPP(p: RewardProgram): number;
+/** RewardProgram.infer(issuer:id:currency:) — order matters, mirrors the Swift needle list exactly. */
+export declare function inferProgram(issuer: string | null, id: string, currency: CreditCard["rewardCurrency"]): RewardProgram;
+export interface Valuation {
+    mode: ValuationMode;
+    pooledPrograms: Record<string, RewardProgram>;
+}
+export declare function makeValuation(mode?: ValuationMode): Valuation;
+/** RewardValuation.pooledPrograms(wallet:) */
+export declare function pooledPrograms(wallet: CreditCard[]): Record<string, RewardProgram>;
+export declare function withPooling(v: Valuation, wallet: CreditCard[]): Valuation;
+export declare function effectiveProgram(v: Valuation, card: CreditCard): RewardProgram;
+export declare function centsPerPoint(v: Valuation, card: CreditCard): number;
+export declare function valuesPointsAboveCash(v: Valuation, card: CreditCard): boolean;
+export declare function earnUnitLabel(v: Valuation, card: CreditCard): string;
+export declare function basisLabel(v: Valuation, card: CreditCard): string;
+/** Swift String(format: "%.1f") */
+export declare function fmt1(x: number): string;