{
  "markdown": "# ModelCostSaver\n\n**Predict the cost of an LLM call before you make it, and pick the cheapest model that still does the job, offline, from your editor.**\n\n[![No API keys](https://img.shields.io/badge/API%20keys-none-brightgreen)](#trust-no-keys-offline-no-telemetry)\n[![Offline by default](https://img.shields.io/badge/network-none%20by%20default-brightgreen)](#trust-no-keys-offline-no-telemetry)\n[![No telemetry](https://img.shields.io/badge/telemetry-off-brightgreen)](#trust-no-keys-offline-no-telemetry)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)\n[![Dependencies](https://img.shields.io/badge/runtime%20deps-2-blue)](#trust-no-keys-offline-no-telemetry)\n\nModelCostSaver is a [Model Context Protocol](https://modelcontextprotocol.io) server. It gives any AI coding agent or IDE a free, zero-config tool that answers the three questions every agent should ask before an LLM call:\n\n1. **What will this prompt cost on each candidate model?** (`predict_cost`, `estimate_cost`)\n2. **Which is the cheapest model that meets the task?** (`select_optimal_model`)\n3. **How do my options compare side by side?** (`compare_models`)\n\nIt is pure pricing-and-routing math over a bundled, dated catalog, so the core needs **no API keys and makes no network calls**.\n\n---\n\n## Quick start\n\nRun it directly with `npx` (no install, no keys):\n\n```bash\nnpx -y @workswarm/modelcostsaver\n```\n\nOr write the config for your editor in one command:\n\n```bash\nnpx -y @workswarm/modelcostsaver install --client cursor\n```\n\n**[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=modelcostsaver&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB3b3Jrc3dhcm0vbW9kZWxjb3N0c2F2ZXIiXX0=)** &mdash; one click installs it in Cursor. Or drop the block below into `~/.cursor/mcp.json`, or run `npx -y @workswarm/modelcostsaver install --client cursor`.\n\nListed on the official [MCP registry](https://registry.modelcontextprotocol.io) and editor MCP directories as `io.github.sachinuppal/modelcostsaver`.\n\n---\n\n## The seven tools\n\n| Tool | What it answers |\n|---|---|\n| `estimate_cost` | Cost of one call when you already know (or can estimate) the token counts. |\n| `predict_cost` | Forecast cost across a candidate set from a prompt, before the call. Ranked cheapest-first. |\n| `select_optimal_model` | The cheapest model that meets the task tier, capabilities, and budget, with full reasoning. |\n| `compare_models` | A side-by-side cost table for a fixed token shape, with `relativeToCheapest`. |\n| `list_models` / `get_pricing` | The pricing catalog, filterable by provider, tier, capability, or max input price. |\n| `optimize_request` | \"I plan to call model X, can I do better?\" Returns the cheaper option and the savings. |\n| `record_usage` | Append a local usage record (opt-in; off unless `MODELCOSTSAVER_LEDGER=on`). |\n\nEvery cost-bearing result carries `catalogVersion` and `asOf` so you can see how fresh the prices are. Every selection carries a `reasoning` array, never a black-box pick.\n\n---\n\n## Trust: no keys, offline, no telemetry\n\nFor a tool that sits in your editor, trust is the whole pitch. ModelCostSaver is:\n\n- **No API keys.** The core does pricing math, not provider calls. Nothing to leak.\n- **Offline by default.** The core tools return correct answers with no network access. The only outbound request is an opt-in catalog refresh (`MODELCOSTSAVER_REFRESH=on`), a single GET of a static JSON, zod-validated before it can replace the bundled catalog, and it always falls back to the bundle on any failure.\n- **No telemetry.** Ever. The default is silent and local. `record_usage` only writes when you set `MODELCOSTSAVER_LEDGER=on`, and only to a JSONL file under your own config dir.\n- **Two dependencies.** `@modelcontextprotocol/sdk` and `zod`. Nothing else. Small supply-chain surface, fast `npx` cold start.\n- **Apache-2.0.** An open-source developer tool published by Workswarm as `@workswarm/modelcostsaver`. The shipped bundle contains no proprietary or internal-service code: no internal-framework imports and no internal identifiers, just dependency-free pricing-and-routing math.\n\nstdout carries only JSON-RPC; all logs go to stderr.\n\n---\n\n## Install per IDE\n\nModelCostSaver speaks stdio MCP, so the entry is the same `npx` command everywhere. Use `install --client <name>` to write it idempotently, or paste the block by hand.\n\n### Cursor\n\n`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):\n\n```json\n{ \"mcpServers\": { \"modelcostsaver\": { \"command\": \"npx\", \"args\": [\"-y\", \"@workswarm/modelcostsaver\"] } } }\n```\n\n```bash\nnpx -y @workswarm/modelcostsaver install --client cursor\n```\n\n### Claude Code\n\n```bash\nclaude mcp add modelcostsaver -- npx -y @workswarm/modelcostsaver\n```\n\nor a `.mcp.json` in the repo root (which `install --client claude` writes):\n\n```json\n{ \"mcpServers\": { \"modelcostsaver\": { \"command\": \"npx\", \"args\": [\"-y\", \"@workswarm/modelcostsaver\"], \"env\": { \"MODELCOSTSAVER_PROVIDERS\": \"anthropic\" } } } }\n```\n\nClaude clients run Claude for their own inference, so the install seeds `MODELCOSTSAVER_PROVIDERS=anthropic` as a sensible default for `target: self` recommendations. Override it per call or with the env var. See [Self vs code](#two-axes-self-vs-code).\n\n### Claude Desktop\n\nAdd the same `mcpServers` block to `claude_desktop_config.json`.\n\n### VS Code / GitHub Copilot\n\n`.vscode/mcp.json`:\n\n```json\n{ \"servers\": { \"modelcostsaver\": { \"command\": \"npx\", \"args\": [\"-y\", \"@workswarm/modelcostsaver\"], \"type\": \"stdio\" } } }\n```\n\n```bash\nnpx -y @workswarm/modelcostsaver install --client vscode\n```\n\n### Windsurf\n\n`~/.codeium/windsurf/mcp_config.json` with the same `mcpServers` block, or:\n\n```bash\nnpx -y @workswarm/modelcostsaver install --client windsurf\n```\n\n### Cline / Zed / Antigravity\n\nSame stdio `command`/`args`. Use the matching installer:\n\n```bash\nnpx -y @workswarm/modelcostsaver install --client cline\nnpx -y @workswarm/modelcostsaver install --client zed\nnpx -y @workswarm/modelcostsaver install --client antigravity\n```\n\nAfter adding the server, restart the client and confirm the seven tools appear in the tool list.\n\n---\n\n## Two axes: self vs code\n\nModelCostSaver advises; it does not route traffic. So every recommendation is filtered to what you can actually act on, along two independent axes.\n\n**Axis 1, availability.** Recommendations are scoped to a set of allowed providers. The default is derived from the connected client (read from the MCP handshake): a Claude client defaults to `anthropic` because its own inference is Claude; multi-provider clients (Cursor, VS Code, Windsurf, Cline, Zed, Antigravity) and unknown clients default to all providers. The scope and its source are always echoed in `reasoning`, and it is overridable: a per-call `providers` arg, then `MODELCOSTSAVER_PROVIDERS`, then config, then the client default, then all.\n\n**Axis 2, target.**\n\n- `target: 'self'` (default): the agent's or your own next inference **in this client**. The Axis-1 scope applies. In Claude Code this means cross-tier Anthropic moves (Opus to Haiku), which you can act on right now.\n- `target: 'code'`: a model you will call from **your own application**, where you supply that provider's key. The client scope does not apply, so all in-catalog providers are eligible.\n\nModelCostSaver is always honest about the gap: if the globally-cheapest model is outside your actionable set, it is surfaced as `cheaperIfAvailable` with the reason, never silently chosen. For example, a Claude Code `target: self` summarize call selects `claude-haiku-4-5` and notes that a cheaper non-Anthropic model exists if you pass `target: code`.\n\n---\n\n## How it predicts\n\n1. **Tokens.** Exact counts if you supply them; otherwise a heuristic estimate (`~4 chars/token`, tunable via `MODELCOSTSAVER_CHARS_PER_TOKEN`). The heuristic is approximate but common-mode across candidates, which is what relative ranking needs. Output tokens come from your explicit value, then the task class cap, then the model cap, then a conservative default.\n2. **Cost.** `(inTok / 1e6) * inputPerMillion + (outTok / 1e6) * outputPerMillion`, in full-precision USD and as integer `usdMicros`. A prediction is never rounded to cents.\n3. **Selection.** Resolve the target tier (from an explicit `taskClass`, else a transparent keyword/length classifier), filter candidates by tier (degrade up, never below the floor), capabilities, and provider scope, forecast each, drop those over budget into `rejected`, and pick the cheapest survivor. Every step is recorded in `reasoning`, and a `fallbackChain` is returned for retry-on-failure.\n\n---\n\n## Configuration\n\nAll config is optional. Precedence: tool-call arg, then env var, then `modelcostsaver.config.json` (cwd, then your user config dir), then the built-in default.\n\n| Key | Env | Default | Purpose |\n|---|---|---|---|\n| tier overrides | `MODELCOSTSAVER_TRIVIAL_MODEL`, `_FAST_MODEL`, `_STANDARD_MODEL`, `_REASONING_MODEL` | catalog cheapest per tier | Pin a preferred model per tier. |\n| providers | `MODELCOSTSAVER_PROVIDERS` | client-derived | Allowlist for recommendations (Axis 1). |\n| default provider | `MODELCOSTSAVER_PROVIDER` | none | Bias `select_optimal_model`. |\n| include local | `MODELCOSTSAVER_INCLUDE_LOCAL` | `off` | Surface self-hosted / $0 models. |\n| chars/token | `MODELCOSTSAVER_CHARS_PER_TOKEN` | `4` | Tune the token estimator. |\n| refresh | `MODELCOSTSAVER_REFRESH` | `off` | Enable the opt-in remote catalog refresh. |\n| catalog url | `MODELCOSTSAVER_CATALOG_URL` | bundled | Override the refresh source. |\n| ledger | `MODELCOSTSAVER_LEDGER` | `off` | Enable the local `record_usage` write. |\n| telemetry | `MODELCOSTSAVER_TELEMETRY` | `off` | Kept off; listed for transparency. |\n\n---\n\n## Pricing data\n\nPrices change often, so ModelCostSaver ships a versioned, dated seed and is honest about its freshness.\n\n- The bundled `catalog.json` carries a `catalogVersion`, an `asOf` date, and a `source` on every entry.\n- Default behavior is offline: it reads only the bundled catalog.\n- `MODELCOSTSAVER_REFRESH=on` fetches a single static JSON, validates it with zod, caches it with a TTL, and falls back to the bundle on any failure.\n- A `pricingOverrides` map in `modelcostsaver.config.json` lets you inject negotiated or enterprise rates without forking.\n\n**Verify before you trust a number for billing.** The seed is re-checked against each provider's public pricing page at release; the `asOf` date tells you when. For absolute precision in your own accounting, confirm against your provider invoice.\n\n---\n\n## Development\n\n```bash\nnpm install        # first time only\nnpm run build      # tsup bundle to dist/index.js\nnpm test           # vitest\nnpm run typecheck  # tsc --noEmit\nnpm run smoke      # stdio JSON-RPC smoke test (asserts stdout stays clean)\n```\n\n---\n\n## License\n\n[Apache-2.0](./LICENSE). See [NOTICE](./NOTICE).\n",
  "bytes": 10869,
  "sha": "4be1fe649e2063644129628c3a1222b0d9149ef5a0fa7dd60a6bbdf8c075791b",
  "repo_slug": "sachinuppal/modelcostsaver",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sachinuppal_modelcostsaver_f01d3404/readme"
}