# model-cost-mcp

A small [MCP](https://modelcontextprotocol.io) server that lets an AI agent answer "which model should I use, and what will it cost?" for image, video, audio and 3D generation, with prices that are exact and errors the agent can recover from.

The catalog is **sample data**: the models and prices are invented for the demo. It is not affiliated with any provider. Replace `src/catalog.ts` with a real catalog before relying on the numbers.

## Tools

| Tool | What it does |
|---|---|
| `list_models` | Lists models with billing unit, price and a "use when" note. Filter by modality or maximum unit price. |
| `estimate_cost` | Exact cost of one job on one model. Handles per-image, per-second and per-run pricing. |
| `compare_models` | Ranks every model of one modality, cheapest first, and lists the ones it had to skip, with reasons. |

## Design choices

- **Money is integers.** Prices are stored in millionths of a dollar, so there is no floating-point drift. The billed amount rounds the exact cost up to the next whole cent, so any surface that computes from the same inputs shows the same number.
- **Per-second models bill every started second**, and the response says when it rounded.
- **Errors tell the agent what to do next.** An invalid call returns a code, a message, a hint with an example call, and for unknown model ids the closest valid ids. Nothing throws an opaque exception.
- **Tool descriptions are written for model selection.** Each says when to call it and what it needs, and every catalog entry carries a `use_when` line.

## Run

```bash
npm install
npm test          # 9 tests, in-memory MCP client against the real server
npm run typecheck
npm start         # stdio server
```

Add it to an MCP client such as Claude Desktop:

```json
{
  "mcpServers": {
    "model-cost": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/model-cost-mcp/src/index.ts"]
    }
  }
}
```

## Example

```text
estimate_cost { "model_id": "demo/video-draft", "quantity": 3, "seconds": 4.2 }
-> 3 clips x 5s = 15 billable seconds, exact $0.750000, billed $0.75
   note: "Every started second is billed, so 4.2s is billed as 5s."

estimate_cost { "model_id": "demo/video-cinema", "quantity": 2 }
-> error seconds_required
   hint: Call again with seconds, for example {"model_id": "demo/video-cinema", "quantity": 2, "seconds": 5}.
```

## Not done yet

- The catalog is a hard-coded list, not a live source.
- stdio only; no HTTP transport or authentication.
- No currency conversion, taxes or volume discounts.