switchwize-mcp

SwitchWize MCP Server

Read-only Model Context Protocol server for SwitchWize public rate and index data. It exposes 15 tools with input/output schemas, MCP read-only annotations, text fallbacks, and structured content for clients that support it.

Start

From this directory:

npm run start

From the repository root:

npx tsx --env-file=.env.local packages/mcp-server/src/server.ts

Smoke Test

npm run smoke        # dev path, via tsx against src/server.ts
npm run smoke:dist    # against the built dist/index.js — what a real npx install runs

Both start the MCP server, run the protocol handshake, list tools, and call tools. smoke:dist additionally calls all 15 tools with sample arguments and lets the MCP SDK client validate every response's structuredContent against its declared outputSchema — the same check an external agent client makes.

Publishing

This package is published to npm as switchwize-mcp so npx -y switchwize-mcp works standalone (no monorepo checkout). The published artifact is a single bundled dist/index.js (built by scripts/build.mjs via esbuild, inlining this package's code plus everything src/lib/mcp/server.ts and src/lib/public-data/tools.ts import from the app's src/) — real node_modules dependencies (drizzle-orm, @neondatabase/serverless, @upstash/redis, zod, the MCP SDK) stay external and are declared in this package's own dependencies, so npm installs them normally for an external user.

npm run build        # bundles src/server.ts -> dist/index.js (also runs automatically via prepublishOnly)
npm run smoke:dist    # verify the built artifact against all 15 tools before publishing
npm publish           # requires npm login with access to the switchwize-mcp package name

An end user needs a DATABASE_URL (Neon) reachable from wherever they run npx switchwize-mcp; UPSTASH_REDIS_REST_URL/UPSTASH_REDIS_REST_TOKEN are optional — usage telemetry silently no-ops without them.

Tools

• get_top_rates
• get_top_hysa_rates
• get_bank_gap
• compare_switch_savings
• get_rate_freshness
• get_index_dataset
• get_bank_gap_index
• get_reality_score
• get_card_offers — current welcome-bonus offers, verified and sourced
• get_transfer_bonuses — current point-transfer bonuses with best-ever-for-route
• get_card_changes — recent verified fee/APR changes
• get_reward_valuations — cents-per-point valuations per reward currency
• best_move_this_week — dollar-ranked actions for a supplied wallet of card ids
• get_cd_rollover_rules — verified bank CD renewal, grace-period, opt-out, and penalty rules
• get_card_downgrade_path — verified product-change targets and fee-refund windows

All tools are read-only and delegate to the same validated public-data tool functions used by /api/public/tools. Production records aggregate request, tool, outcome, client-label, and latency counters for 90 days. It never stores tool arguments, response bodies, IP addresses, or financial values.

Prompts

Canned workflows a client can surface directly (e.g. as slash commands), instead of requiring the user to phrase the right freeform question. See src/lib/mcp/prompts.ts.

• audit_savings — is the user losing money in their current savings account, and by how much per year.
• audit_wallet — given a wallet of held cards, this week's highest-value move.
• prepare_cd_maturity — what happens automatically when a CD matures, and whether the rollover rate is competitive.

Resources

Reference material an agent can read once and cite, instead of re-deriving (or inventing) it from a tool response's summary field. See src/lib/mcp/resources.ts.

• switchwize://methodology — how SwitchWize sources and verifies data.
• switchwize://freshness-policy — what freshnessStatus/asOf/verified_at mean and how to act on them.
• switchwize://tools — the full tool catalog with suggested chaining.
• switchwize://supported-institutions — how to get the current live institution list per category (not hardcoded, since coverage grows).

Eval suite

src/lib/mcp/eval.ts calls every tool in-process with realistic sample arguments (~22 cases across the 15 tools, including a few deliberate not-found lookups) and scores the real response against what a client actually depends on — did it throw, does it carry freshnessStatus, reasonable latency. Runs weekly via /api/cron/mcp-weekly-quality-report (not yet registered on cron-job.org — see CLAUDE.md's cron table) alongside the 7d/30d usage telemetry, stores the result for /admin/mcp to display, and emails a summary if ADMIN_EMAIL/CEO_EMAIL and RESEND_API_KEY are set.