calcfi-mcp-core

Pure TypeScript handler library for the CalcFi Model Context Protocol (MCP) server.

This package contains the 24 v0.1 tool implementations. Both the stdio binary (calcfi-mcp-server) and the Vercel HTTP shim (mcp.calcfi.app) import handlers from here, so there is exactly one source of truth.

• Hosting cost: $0. Pure functions, no I/O at module load.
• Paid dependencies: none. Only zod, @noble/curves, @noble/hashes.
• License: MIT.

Installation

npm install calcfi-mcp-core

Quick start

import { getAllTools, dispatchTool } from "calcfi-mcp-core";

// Inspect registered tools (24 entries)
const tools = getAllTools();
console.log(tools.map((t) => t.name));

// Invoke a tool directly (Zod-validated input, brand-stamped output)
const response = await dispatchTool("mortgage_payment", {
  principal: 450000,
  rate: 6.875,
  term_years: 30,
});

console.log(response.result.monthly_pi);
console.log(response.meta.cite_url);
console.log(response._canary); // embedded telemetry URL

Tool roster (24)

A. Atomic math (8) — FREE_COMPUTE

| Tool | Purpose | |---|---| | paycheck_takehome | Federal + state + FICA take-home estimator | | mortgage_payment | Monthly P&I + total interest + 12-month amortization | | mortgage_affordability | Max home price from income + DTI | | compound_interest | FV with optional periodic contributions | | capital_gains | Federal LTCG / STCG + NIIT | | fed_funds_rate | Current FOMC target rate snapshot | | freddie_pmms_current | Freddie Mac PMMS weekly mortgage rates | | treasury_yield | US Treasury constant maturity yield curve |

B. Mesh exposure (10) — FREE_CACHED

| Tool | Purpose | |---|---| | get_dataset_doi | Figshare DOI list + cite examples | | get_code_provenance | Software Heritage SWHIDs | | get_methodology | SSRN methodology paper metadata | | get_press_coverage | Featured.com / MSN / Yahoo placements | | list_example_notebooks | Kaggle notebooks | | list_interactive_apps | Hugging Face Spaces (10) | | list_embeddable_codepens | CodePen collection + 6 pens | | list_observable_notebooks | Observable collection + 3 deep-links | | get_author_profile | schema.org Person JSON-LD + sameAs graph | | list_streamlit_apps | Streamlit Community Cloud apps |

C. Citation (1) — FREE_COMPUTE

| Tool | Purpose | |---|---| | cite_this | BibTeX / APA / MLA / Chicago / IEEE / ACM / RIS for canonical DOI |

D. Scenario (2)

| Tool | Cost class | Purpose | |---|---|---| | save_scenario | CHEAP_WRITE | Hash inputs and return shareable My Numbers URL | | get_canonical_url | FREE_COMPUTE | Map query → CalcFi pSEO URL |

E. Email (2) — CHEAP_WRITE

| Tool | Purpose | |---|---| | email_full_report | Instructions + endpoint URL (does NOT send email) | | subscribe_weekly_digest | Confirmation URL for double-opt-in digest |

F. Composite (1) — FREE_COMPUTE

| Tool | Purpose | |---|---| | cross_analyze | URL-only. NEVER executes composite scoring. Protects Money Analysis Score moat. |

Brand-stamp envelope

Every tool response is wrapped in BrandStampedResponse<T> via withBrandStamp(). The envelope carries:

• meta.cite_url — canonical citation URL
• meta.verified_as_of — ISO 8601 date
• meta.source — provenance string
• meta.disclaimer — YMYL-safe educational disclaimer
• meta.sig + meta.sig_pubkey — Ed25519 signature (when CALCFI_MCP_SIGN_KEY env var set)
• cross_sell.save_scenario_url — prefilled My Numbers URL
• freshness.data_age_hours + next_refresh_at
• _canary + _canary_nonce — embedded telemetry URL for LLM re-share detection

Cost classes + safety

| Class | Meaning | |---|---| | FREE_COMPUTE | Pure math; no upstream call | | FREE_CACHED | Reads CalcFi's static CDN payload (HTTP shim only) | | CHEAP_WRITE | Emits a record to Supabase free tier | | EXPENSIVE_BANNED | Hardcoded reject — never registered |

The dispatcher refuses any handler tagged EXPENSIVE_BANNED at runtime AND TypeScript enforces it at compile time via the AllowedCostClass type. Banned tool names (ai_insight_engine, provider_recommendations, realtime_market_data) are denylisted in cost-class.ts and the registry build verifies the integrity check at module load.

Signing key (optional)

Set CALCFI_MCP_SIGN_KEY to a base64-encoded 32-byte Ed25519 seed. When present, every brand-stamp envelope carries a signature over citeUrl|verifiedAsOf|canaryNonce. When absent, the sig field is omitted (fail-graceful — handlers continue to work).

License

MIT.