Modelcostsaver

ModelCostSaver

在发起大模型调用前预测成本，并从编辑器中离线挑选能完成任务的最便宜模型。

ModelCostSaver 是一个 Model Context Protocol 服务。它为任何 AI 编码 Agent 或 IDE 提供免费的零配置工具，回答每个 Agent 在调用大模型前都应提出的三个问题：

1. 此提示词在每个候选模型上的成本是多少？（predict_cost、estimate_cost）
2. 满足任务要求的最便宜模型是哪一个？（select_optimal_model）
3. 如何并排比较各个选项？（compare_models）

它基于内置的、带日期的目录进行纯粹的定价与路由计算，因此核心功能无需 API 密钥，也不会发起网络请求。

---

快速开始

直接使用 npx 运行（无需安装，无需密钥）：

npx -y @workswarm/modelcostsaver

或者用一条命令为编辑器写入配置：

npx -y @workswarm/modelcostsaver install --client cursor

添加到 Cursor — 单击即可在 Cursor 中安装。也可以将下面的代码块放入 ~/.cursor/mcp.json，或运行 npx -y @workswarm/modelcostsaver install --client cursor。

已收录于官方 MCP registry 和编辑器 MCP 目录，名称为 io.github.sachinuppal/modelcostsaver。

---

七种工具

工具	功能
estimate_cost	已知（或可估算）Token 数量时，计算单次调用的成本。
predict_cost	调用前根据提示词预测候选模型集的成本，并按价格从低到高排序。
select_optimal_model	满足任务等级、能力和预算要求的最便宜模型，并提供完整的推理过程。
compare_models	针对固定 Token 数量，并排显示成本表，并提供 relativeToCheapest。
list_models / get_pricing	定价目录，可按提供商、等级、能力或最高输入价格筛选。
optimize_request	“我打算调用模型 X，有没有更好的选择？”返回更便宜的选项和节省金额。
record_usage	追加本地使用记录（可选启用；除非设置 MODELCOSTSAVER_LEDGER=on，否则默认关闭）。

每个包含成本的结果都带有 catalogVersion 和 asOf，方便查看价格的新旧程度。每次模型选择都会附带 reasoning 数组，绝不会黑箱选择。

信任：无需密钥、离线运行、无遥测

对于一款驻留在编辑器中的工具来说，信任就是其核心卖点。ModelCostSaver：

• 无需 API 密钥。 核心功能负责定价计算，不会调用服务提供商。没有任何信息会泄露。
• 默认离线运行。 核心工具无需网络连接即可返回正确结果。唯一的出站请求是选择启用的目录刷新（MODELCOSTSAVER_REFRESH=on）：它只会 GET 一个静态 JSON，在通过 zod 验证后才能替换内置目录；任何失败情况下都会回退到内置目录。
• 无遥测。 永远如此。默认情况下静默运行，数据保留在本地。只有在设置 MODELCOSTSAVER_LEDGER=on 时，record_usage 才会写入数据，而且只会写入你自己的配置目录下的 JSONL 文件。
• 仅有两个依赖。 @modelcontextprotocol/sdk 和 zod。除此之外别无其他。供应链攻击面小，npx 冷启动速度快。
• Apache-2.0。 由 Workswarm 以 @workswarm/modelcostsaver 名义发布的开源开发者工具。发布的程序包不含专有代码或内部服务代码：不导入内部框架，也不含内部标识符，仅包含无依赖的定价与路由计算逻辑。

stdout 仅承载 JSON-RPC；所有日志都写入 stderr。

---

按 IDE 安装

ModelCostSaver 使用 stdio MCP，因此在所有 IDE 中入口都是相同的 npx 命令。使用 install --client <name> 以幂等方式写入配置，或手动粘贴配置块。

Cursor

~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目）：

{ "mcpServers": { "modelcostsaver": { "command": "npx", "args": ["-y", "@workswarm/modelcostsaver"] } } }

npx -y @workswarm/modelcostsaver install --client cursor

Claude Code

claude mcp add modelcostsaver -- npx -y @workswarm/modelcostsaver

也可以在仓库根目录中放置 .mcp.json（install --client claude 会写入该文件）：

{ "mcpServers": { "modelcostsaver": { "command": "npx", "args": ["-y", "@workswarm/modelcostsaver"], "env": { "MODELCOSTSAVER_PROVIDERS": "anthropic" } } } }

Claude 客户端使用 Claude 进行自身的推理，因此安装时会设置 MODELCOSTSAVER_PROVIDERS=anthropic，作为 target: self 推荐的合理默认值。你可以针对单次调用覆盖此值，也可以通过环境变量覆盖。参见自身与代码。

Claude Desktop

将相同的 mcpServers 配置块添加到 claude_desktop_config.json。

VS Code / GitHub Copilot

.vscode/mcp.json：

{ "servers": { "modelcostsaver": { "command": "npx", "args": ["-y", "@workswarm/modelcostsaver"], "type": "stdio" } } }

npx -y @workswarm/modelcostsaver install --client vscode

Windsurf

在 ~/.codeium/windsurf/mcp_config.json 中添加相同的 mcpServers 配置块，或使用：

npx -y @workswarm/modelcostsaver install --client windsurf

Cline / Zed / Antigravity

使用相同的 stdio command/args。选择对应的安装程序：

npx -y @workswarm/modelcostsaver install --client cline
npx -y @workswarm/modelcostsaver install --client zed
npx -y @workswarm/modelcostsaver install --client antigravity

添加服务后，重启客户端，并确认工具列表中出现了七个工具。

---

两个维度：自身与代码

ModelCostSaver 提供建议，但不会路由流量。因此，每条推荐都会沿着两个彼此独立的维度进行筛选，确保你确实可以采取相应行动。

维度 1，可用性。 推荐范围限定为一组允许使用的服务提供商。默认值根据已连接的客户端确定（从 MCP 握手中读取）：Claude 客户端默认使用 anthropic，因为其自身的推理模型是 Claude；支持多个服务提供商的客户端（Cursor、VS Code、Windsurf、Cline、Zed、Antigravity）以及未知客户端则默认允许所有服务提供商。reasoning 中始终会回显范围及其来源，并且可以覆盖：单次调用的 providers 参数，然后是 MODELCOSTSAVER_PROVIDERS，再然后是配置、客户端默认值，最后是所有服务提供商。

维度 2，目标。

• target: 'self'（默认值）：此客户端中 Agent 或你自己下一次进行的推理。适用维度 1 的范围。在 Claude Code 中，这意味着在 Anthropic 的不同套餐之间切换（从 Opus 切换到 Haiku），你可以立即采用这一建议。
• target: 'code'：你将在自己应用中调用的模型，由你提供该服务提供商的密钥。客户端范围不适用，因此目录中的所有服务提供商都符合条件。

ModelCostSaver 始终如实说明限制：如果全局最便宜的模型不在你可以采取行动的范围内，它会将该模型作为 cheaperIfAvailable 显示，并说明原因，而不会悄悄选用。例如，Claude Code 中 target: self 的 summarize 调用会选择 claude-haiku-4-5，并指出如果传入 target: code，还存在价格更低的非 Anthropic 模型。

预测方式

1. Token 数量。 如果你提供了确切数量，就使用该数量；否则使用启发式估算（~4 chars/token，可通过 MODELCOSTSAVER_CHARS_PER_TOKEN 调整）。这种启发式估算虽不精确，但对所有候选模型采用统一标准，这正是进行相对排名所需要的。输出 token 数量依次取自你提供的值、任务类别上限、模型上限，最后是保守默认值。
2. 成本。 (inTok / 1e6) * inputPerMillion + (outTok / 1e6) * outputPerMillion，以完整精度的美元和整数 usdMicros 表示。预测结果绝不会四舍五入到美分。
3. 选择。 确定目标层级（根据显式的 taskClass，否则使用透明的关键词／长度分类器），按层级（只向上降级，绝不低于下限）、能力和提供商范围筛选候选模型，预测每个模型的成本，将超出预算的模型移至 rejected，然后选出成本最低的合适模型。每一步都会记录在 reasoning 中，并返回 fallbackChain，以便失败后重试。

---

配置

所有配置均为可选。优先级：工具调用参数，然后是环境变量，再然后是 modelcostsaver.config.json（当前工作目录，其次是用户配置目录），最后是内置默认值。

键	环境变量	默认值	用途
层级覆盖	MODELCOSTSAVER_TRIVIAL_MODEL、_FAST_MODEL、_STANDARD_MODEL、_REASONING_MODEL	各层级目录中的最低价模型	为每个层级指定首选模型。
提供商	MODELCOSTSAVER_PROVIDERS	根据客户端推导	推荐模型的允许列表（轴 1）。
默认提供商	MODELCOSTSAVER_PROVIDER	无	为 select_optimal_model 提供倾向。
包含本地模型	MODELCOSTSAVER_INCLUDE_LOCAL	off	显示可自托管／价格为 $0 的模型。
字符数／token	MODELCOSTSAVER_CHARS_PER_TOKEN	4	调整 token 估算器。
刷新	MODELCOSTSAVER_REFRESH	off	启用自愿选择的远程目录刷新。
目录 URL	MODELCOSTSAVER_CATALOG_URL	随包提供	覆盖刷新来源。
使用记录	MODELCOSTSAVER_LEDGER	off	启用本地 record_usage 写入。
遥测	MODELCOSTSAVER_TELEMETRY	off	保持关闭；列出此项以确保透明度。

---

定价数据

价格经常变动，因此 ModelCostSaver 会提供带版本和日期的初始数据，并如实说明其时效性。

• 随包提供的 catalog.json 包含 catalogVersion、asOf 日期，并为每个条目标注 source。
• 默认行为为离线：只读取随包提供的目录。
• 设置 MODELCOSTSAVER_REFRESH=on 后，会获取单个静态 JSON，使用 zod 验证，将其缓存至 TTL 到期，并在任何失败时回退到随包提供的数据。
• modelcostsaver.config.json 中的 pricingOverrides 映射可让你注入协商价或企业费率，无需分叉项目。

用于计费的数字，请先核实再采信。 每次发布时，都会根据各提供商的公开定价页面重新核对初始数据；asOf 日期会告知你数据的核对时间。如需在自己的账务中达到绝对精确，请以提供商发票为准。

---

开发

npm install        # first time only
npm run build      # tsup bundle to dist/index.js
npm test           # vitest
npm run typecheck  # tsc --noEmit
npm run smoke      # stdio JSON-RPC smoke test (asserts stdout stays clean)

---

许可证

Apache-2.0。请参阅 NOTICE。