rightcard-mcp 0.1.2 → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RightCard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/data.js

@@ -25,7 +25,7 @@ async function getAll(path, fetchImpl) {
 }
 export async function loadCatalog(fetchImpl = fetch) {
     const [cardRows, overrideRows, merchantRows] = await Promise.all([
-        getAll("cards?select=id,name,issuer,reward_currency,base_rate,standard_multipliers,annual_fee,verify_status&country=eq.US&order=id", fetchImpl),
+        getAll("cards?select=id,name,issuer,reward_currency,base_rate,standard_multipliers,annual_fee,verify_status,network&country=eq.US&order=id", fetchImpl),
         getAll("active_overrides?select=*&order=id", fetchImpl),
         getAll("merchants?select=id,display_name,category,sub_key,merchant_type,is_online,aliases&country=eq.US&order=id", fetchImpl),
     ]);

package/dist/engine.d.ts

@@ -33,6 +33,8 @@ export interface RecommendInput {
     cardConfigs?: Record<string, Set<SpendCategory>>;
     now: Date;
     strictMerchantMatch?: boolean;
+    /** Register network lock (Costco = visa-only). null/undefined = no restriction. */
+    acceptedNetworks?: Set<string> | null;
 }
 export declare function formatPercent(v: number): string;
 export declare function formatMultiplier(v: number): string;

package/dist/engine.js

@@ -48,19 +48,19 @@ function tieNote(winner, runnerUp, value, v) {
     if (wRank > rRank) {
         const winProgram = effectiveProgram(v, winner);
         if (v.mode === "cash" && winProgram !== "cash" && cashOutCPP(winProgram) >= 1.0) {
-            return `${win} ties ${other} at ${rate} — picked ${win}: its points cash out the same, and can be worth more if you ever redeem for travel.`;
+            return `${other} also earns ${rate} here. We picked ${win} because its points cash out the same and can be worth more for travel.`;
         }
         const smart = { mode: "smart", pooledPrograms: v.pooledPrograms };
         if (v.mode === "cash" && centsPerPoint(smart, runnerUp) > 1.0) {
-            return `${win} and ${other} tie at ${rate} for cash. ${other}'s points can be worth more if you redeem for travel — switch to Points & miles to compare.`;
+            return `${other} also earns ${rate} here. Its points can be worth more for travel, so try Points & miles.`;
         }
         const why = v.mode === "smart" ? "transfer flexibility" : "guaranteed cash back";
-        return `${win} ties ${other} at ${rate} — picked ${win} for ${why}.`;
+        return `${other} also earns ${rate} here. We picked ${win} for ${why}.`;
     }
     if (premiumRank(winner) > premiumRank(runnerUp)) {
-        return `${win} ties ${other} at ${rate} — picked ${win}: the premium card's purchase protections come free at the same rate.`;
+        return `${other} also earns ${rate} here. We picked ${win} for its purchase protection.`;
     }
-    return `${win} ties ${other} at ${rate} — either works.`;
+    return `${other} also earns ${rate} here. Either one works.`;
 }
 const PORTAL_BONUSES = [
     { needles: ["sapphire reserve"], rate: 10, portal: "Chase Travel", premium: true },
@@ -202,7 +202,14 @@ function rateContext(card, earn, valueCents, override, configured, v, category,
     }
     else {
         reason = `${card.displayName} earns the most for ${cat} — ${valueStr} per dollar.`;
-        lines.push(`Base ${cat} earn: ${valueStr}`);
+        // Mirrors the Swift engine (Sep 2026): a points/miles card in cash mode
+        // still EARNS points — never blur the earn (4x points) with its value (4%).
+        if (card.rewardCurrency !== null && card.rewardCurrency !== "cashback") {
+            lines.push(`Base ${cat} earn: ${formatMultiplier(earn)} ${earnUnitLabel(v, card)} → ${valueStr}`);
+        }
+        else {
+            lines.push(`Base ${cat} earn: ${valueStr}`);
+        }
     }
     let caption = configured ? "your bonus category · value per $1" : override ? "rotating bonus · value per $1" : "value per $1";
     let valueMath = null;
@@ -241,9 +248,24 @@ function subcategoryBreakdown(cards, category, overrides, cardConfigs, v, now) {
 }
 /** MerchantYieldEngine.recommend — base-rate mode (offers: []) */
 export function recommend(input) {
-    const { cards, category, overrides, now } = input;
+    const { category, overrides, now } = input;
+    let cards = input.cards;
     if (cards.length === 0)
         return null;
+    // Network-acceptance gate (Costco's Visa-only registers). Mirrors the Swift
+    // engine: a KNOWN-incompatible card can't win when a compatible (or
+    // unknown-network) card exists; if every card is known-incompatible, the
+    // full wallet answers (works on the merchant's site) and the warehouse
+    // caveat carries the register story. Unknown (null) network never gates.
+    const accepted = input.acceptedNetworks;
+    if (accepted && accepted.size > 0) {
+        const eligible = cards.filter((c) => {
+            const net = c.network?.toLowerCase();
+            return net == null || accepted.has(net);
+        });
+        if (eligible.length > 0)
+            cards = eligible;
+    }
     const v = withPooling(input.valuation, cards);
     const cardConfigs = input.cardConfigs ?? {};
     const strict = input.strictMerchantMatch ?? false;

package/dist/model.d.ts

@@ -15,6 +15,8 @@ export interface CreditCard {
     multipliers: Record<string, MultiplierField>;
     annualFee?: number | null;
     verifyStatus?: string | null;
+    /** Payment network (migration 0017): visa|mastercard|amex|discover; null = unknown, never gates. */
+    network?: string | null;
 }
 /** Supabase `cards` row → CreditCard (SupabaseCard.toCreditCard). */
 export declare function cardFromRow(row: any): CreditCard;
@@ -34,7 +36,13 @@ export interface Override {
     merchant: string | null;
 }
 export declare function overrideFromRow(r: any): Override;
-/** UTC-day canon (SupabaseDateFormat.utcCalendar): compare yyyy-MM-dd strings as UTC days. */
+/** Compare yyyy-MM-dd strings as UTC days.
+ *
+ *  The iOS app judges windows in the USER'S calendar date (Sep 13 2026: an offer
+ *  or quarter marked 9/30 is live through the end of 9/30 where the user is).
+ *  This server has no user timezone, so it keeps UTC; the two can differ only
+ *  inside the few hours around midnight on a window's first or last day. The
+ *  golden fixture is exported at noon UTC so parity is unaffected. */
 export declare function utcDay(now: Date): string;
 export declare function overrideIsActive(o: Override, now: Date): boolean;
 /** SupabaseOverride.isPermanentMerchantBenefit: merchant-scoped, no activation, ends > 2 years out. */
@@ -51,5 +59,11 @@ export interface Merchant {
 export declare function merchantFromRow(r: any): Merchant;
 /** Merchant.exclusionCaveat */
 export declare function exclusionCaveat(m: Merchant): string | null;
+/** Merchant.acceptedNetworksAtRegister — Costco's Visa-only register lock.
+ *  EVERY physical Costco row (checkout, pharmacy, gas, tire) is Visa-only
+ *  for credit; null for everything else (no restriction). Costco.com /
+ *  online rows are never gated (they take other networks). Mirrors the
+ *  Swift twin exactly. */
+export declare function acceptedNetworksAtRegister(m: Merchant): Set<string> | null;
 /** Merchant.isCuratedBrand */
 export declare function isCuratedBrand(m: Merchant): boolean;

package/dist/model.js

@@ -27,6 +27,7 @@ export function cardFromRow(row) {
         multipliers,
         annualFee: row.annual_fee ?? null,
         verifyStatus: row.verify_status ?? null,
+        network: row.network ?? null,
     };
 }
 function fieldFromJSON(v) {
@@ -85,7 +86,13 @@ export function overrideFromRow(r) {
         label: r.label ?? null, merchant: r.merchant ?? null,
     };
 }
-/** UTC-day canon (SupabaseDateFormat.utcCalendar): compare yyyy-MM-dd strings as UTC days. */
+/** Compare yyyy-MM-dd strings as UTC days.
+ *
+ *  The iOS app judges windows in the USER'S calendar date (Sep 13 2026: an offer
+ *  or quarter marked 9/30 is live through the end of 9/30 where the user is).
+ *  This server has no user timezone, so it keeps UTC; the two can differ only
+ *  inside the few hours around midnight on a window's first or last day. The
+ *  golden fixture is exported at noon UTC so parity is unaffected. */
 export function utcDay(now) {
     return now.toISOString().slice(0, 10);
 }
@@ -117,12 +124,42 @@ 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.`;
+        case "warehouse_club": {
+            const base = `${m.displayName} codes as a warehouse club, so category bonuses usually don't post — this is your best guaranteed card.`;
+            // Costco alone is also NETWORK-locked: warehouse registers take Visa
+            // only (Costco.com takes other networks). Mirrors the Swift engine —
+            // keep both sides identical or the parity gate fails.
+            if (m.displayName.toLowerCase().includes("costco")) {
+                return base + " Note: Costco warehouses take Visa only at the register; other networks work on Costco.com.";
+            }
+            return base;
+        }
         default:
+            // Physical Costco DEPARTMENTS (pharmacy / gas / tire / …) share the
+            // warehouse's Visa-only registers; their own MCC stays honest (no
+            // "bonuses don't post" clause). Mirrors the Swift engine (Sep 2026).
+            if (acceptedNetworksAtRegister(m) !== null) {
+                return "Costco takes Visa only at the register — this is your best card that works in-store. Other networks work on Costco.com.";
+            }
             return null;
     }
 }
+/** Merchant.acceptedNetworksAtRegister — Costco's Visa-only register lock.
+ *  EVERY physical Costco row (checkout, pharmacy, gas, tire) is Visa-only
+ *  for credit; null for everything else (no restriction). Costco.com /
+ *  online rows are never gated (they take other networks). Mirrors the
+ *  Swift twin exactly. */
+export function acceptedNetworksAtRegister(m) {
+    const name = m.displayName.toLowerCase();
+    if (!name.includes("costco"))
+        return null;
+    // NAME is the online signal, deliberately not isOnline — the LLM-minted
+    // flag is noise on this family (costco_pharmacy sat is_online=true).
+    // Mirrors the Swift twin exactly.
+    if (name.includes(".com") || name.includes("online"))
+        return null;
+    return new Set(["visa"]);
+}
 /** Merchant.isCuratedBrand */
 export function isCuratedBrand(m) {
     if (m.aliases.length > 0)

package/dist/search.js

@@ -96,7 +96,11 @@ export function matchScore(q, qc, rawQuery, candidates) {
         const words = n.split(" ");
         if (words.slice(1).some((w) => w.startsWith(q)))
             best = Math.max(best, 70);
-        if (n.includes(q))
+        // INTERIOR substring, only for a query long enough to mean something. A 2–3
+        // character query matching mid-word is noise: "LG" returned Algenist,
+        // Bulgari, Trafalgar and the glued alias "naturalgrocers.com" and no LG
+        // (user report, Sep 17 2026). Mirrors Merchant.matchScore in the app.
+        if ([...q].length >= 4 && n.includes(q))
             best = Math.max(best, 55);
         if (best < 45 && merchantMatches(c.raw, rawQuery))
             best = Math.max(best, 45);

package/dist/tools.js

@@ -2,7 +2,7 @@
 // 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 { ALL_CATEGORIES, acceptedNetworksAtRegister, 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";
@@ -13,6 +13,10 @@ 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,
+        // Payment network (visa|mastercard|amex|discover) or null = unknown.
+        // Stated so the model never guesses it (Costco's registers are Visa-only;
+        // a guessed network in an answer is exactly the hallucination this bans).
+        network: c.network ?? null,
     };
 }
 function resolveWallet(catalog, ids) {
@@ -92,7 +96,8 @@ export function buildServer(getCatalog) {
             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 });
+            valuation: makeValuation(mode), cardConfigs: configs, now,
+            acceptedNetworks: dir ? acceptedNetworksAtRegister(dir) : null });
         if (!r)
             return err("No recommendation could be computed.");
         const answer = {

package/dist/valuation.d.ts

@@ -1,6 +1,6 @@
 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 type RewardProgram = "cash" | "amexMR" | "chaseUR" | "capOneMiles" | "citiTYP" | "wellsFargo" | "bilt" | "tdRewards" | "scenePlus" | "rbcAvion" | "bmoRewards" | "hyatt" | "marriott" | "ihg" | "choice" | "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 */
@@ -20,5 +20,12 @@ 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") */
+/** Swift String(format: "%.1f") — printf rounds the EXACT binary value, and
+ *  only an exact tie (1.25 is representable) goes to even ("1.2"). Surfaced
+ *  Aug 29 2026 when a live card hit a 1.25x earn and 27 golden cases split.
+ *  Sep 15 2026: the first mirror scaled by 10 first, and 1.5 × 1.1 =
+ *  1.6500000000000001 × 10 landed on exactly 16.5 — a FALSE tie, rounded to
+ *  "1.6" where Swift prints "1.7" (Delta Biz Platinum transit 1.5x @ 1.1¢).
+ *  toFixed(20) is the exact decimal expansion of the double, so a tie is a
+ *  tie only when the digits past the tenths are literally 5000…0. */
 export declare function fmt1(x: number): string;

package/dist/valuation.js

@@ -2,17 +2,19 @@ export const PROGRAM_DISPLAY = {
     cash: "Cash back", amexMR: "Amex Membership Rewards", chaseUR: "Chase Ultimate Rewards",
     capOneMiles: "Capital One miles", citiTYP: "Citi ThankYou Points", wellsFargo: "Wells Fargo Rewards",
     bilt: "Bilt Rewards", tdRewards: "TD Rewards", scenePlus: "Scene+", rbcAvion: "RBC Avion points",
-    bmoRewards: "BMO Rewards", hyatt: "World of Hyatt", marriott: "Marriott Bonvoy", ihg: "IHG One Rewards",
+    bmoRewards: "BMO Rewards", hyatt: "World of Hyatt", marriott: "Marriott Bonvoy", ihg: "IHG One Rewards", choice: "Choice Privileges",
     hilton: "Hilton Honors", delta: "Delta SkyMiles", united: "United MileagePlus",
     american: "American AAdvantage", southwest: "Southwest Rapid Rewards", jetBlue: "JetBlue TrueBlue",
     alaska: "Alaska Mileage Plan", avios: "British Airways Avios", aeroplan: "Air Canada Aeroplan",
     fixedValue: "Fixed-value miles", genericPoints: "Points", genericMiles: "Miles",
 };
 export const TRAVEL_CPP = {
-    cash: 1.0, amexMR: 2.0, chaseUR: 2.0, capOneMiles: 1.7, citiTYP: 1.7, wellsFargo: 1.5, bilt: 2.0,
+    // Sep 2026: median of TPG / Frequent Miler / Upgraded Points / OMAAT, rounded
+    // down, never above (mirrors Swift RewardProgram.travelCPP).
+    cash: 1.0, amexMR: 1.8, chaseUR: 1.8, capOneMiles: 1.7, citiTYP: 1.6, wellsFargo: 1.5, bilt: 1.8,
     tdRewards: 0.5, scenePlus: 1.0, rbcAvion: 1.5, bmoRewards: 0.7,
-    hyatt: 1.7, marriott: 0.7, ihg: 0.6, hilton: 0.5,
-    delta: 1.1, united: 1.3, american: 1.4, southwest: 1.3, jetBlue: 1.3, alaska: 1.4, avios: 1.3, aeroplan: 1.3,
+    hyatt: 1.4, marriott: 0.7, ihg: 0.5, choice: 0.6, hilton: 0.4,
+    delta: 1.1, united: 1.2, american: 1.4, southwest: 1.2, jetBlue: 1.3, alaska: 1.4, avios: 1.2, aeroplan: 1.3,
     fixedValue: 1.0, genericPoints: 2.0, genericMiles: 1.5,
 };
 /** RewardProgram.cashOutCPP */
@@ -40,6 +42,10 @@ export function inferProgram(issuer, id, currency) {
         return "hyatt";
     if (has("ihg"))
         return "ihg";
+    // Choice Privileges (Wells Fargo-issued) must precede the "wells" needle,
+    // which valued these hotel points at 1.5¢ (mirrors Swift, Sep 24 2026).
+    if (has("choice"))
+        return "choice";
     if (has("delta", "skymiles"))
         return "delta";
     if (has("united", "mileageplus"))
@@ -84,6 +90,10 @@ export function inferProgram(issuer, id, currency) {
         return "fixedValue";
     if (has("altitude"))
         return "fixedValue";
+    // GM Rewards (Barclays, Sep 2026): points pegged at 1¢, redeemable only toward
+    // GM — the generic 2¢ fallback read its flat 3x as "6%" (mirrors Swift).
+    if (has("gm_rewards", "gm rewards"))
+        return "fixedValue";
     return currency === "miles" ? "genericMiles" : "genericPoints";
 }
 export function makeValuation(mode = "cash") {
@@ -154,7 +164,23 @@ export function basisLabel(v, card) {
     const pooled = v.pooledPrograms[card.id] !== undefined ? " (pooled with your wallet)" : "";
     return `${PROGRAM_DISPLAY[effectiveProgram(v, card)]} · ${fmt1(cpp)}¢ travel value${pooled}`;
 }
-/** Swift String(format: "%.1f") */
+/** Swift String(format: "%.1f") — printf rounds the EXACT binary value, and
+ *  only an exact tie (1.25 is representable) goes to even ("1.2"). Surfaced
+ *  Aug 29 2026 when a live card hit a 1.25x earn and 27 golden cases split.
+ *  Sep 15 2026: the first mirror scaled by 10 first, and 1.5 × 1.1 =
+ *  1.6500000000000001 × 10 landed on exactly 16.5 — a FALSE tie, rounded to
+ *  "1.6" where Swift prints "1.7" (Delta Biz Platinum transit 1.5x @ 1.1¢).
+ *  toFixed(20) is the exact decimal expansion of the double, so a tie is a
+ *  tie only when the digits past the tenths are literally 5000…0. */
 export function fmt1(x) {
-    return (Math.round(x * 10) / 10).toFixed(1);
+    const exact = Math.abs(x).toFixed(20);
+    const [ip, fp] = exact.split(".");
+    if (/^[0-9]50{18}$/.test(fp)) {
+        let n = parseInt(ip, 10) * 10 + parseInt(fp[0], 10);
+        if (n % 2 !== 0)
+            n += 1;
+        const s = (n / 10).toFixed(1);
+        return x < 0 ? "-" + s : s;
+    }
+    return x.toFixed(1);
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "rightcard-mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "mcpName": "ai.rightcard/mcp",
-  "description": "RightCard MCP \u2014 the card-selection oracle for agents. Which of your credit cards to use at any store, from verified data. No bank login.",
+  "description": "RightCard MCP — the card-selection oracle for agents. Which of your credit cards to use at any store, from verified data. No bank login.",
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -25,7 +25,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/parikshitmadahar/rightcard-mcp"
+    "url": "git+https://github.com/rightcard/rightcard-mcp.git"
   },
   "files": [
     "dist",