# modelpulse

modelpulse is a thin local bridge to AI Wave's hosted
MCP server, a single normalised feed over the AI model
landscape: vendor release notes, the Hugging Face and
OpenRouter catalogues, GitHub and the LiteLLM price map,
deduplicated per model. It tracks what changed, what
things cost, and what to switch to when a model goes
away.

The bridge keeps no catalogue and computes nothing. It
serves the upstream server's tool list locally — exactly
as captured from the live endpoint — and forwards each
tool call upstream, returning the result untouched.

## Tools

- `list_model_changes` — the change feed: new releases,
  price changes, API changes and deprecations, each entry
  marked official or pending review. Optional: `since`
  (unix seconds; poll by feeding the returned `latest`
  back in), `type` (`new_model`, `price_change`,
  `api_change`, `open_source_surge`, `deprecation`),
  `model` (vendor slug, e.g. `claude`), and `limit`
  (1-100, default 20).
- `get_model` — pricing, context length and catalogue
  status for one model (`id`, required: an OpenRouter id
  such as `anthropic/claude-opus-5`, or a Hugging Face
  repo id).
- `get_price_history` — when one model's price changed
  and to what (`id`, required). History starts when AI
  Wave began recording, not when the model launched.
- `search_models` — shortlist models by budget, context
  and capability, with benchmark scores next to prices.
  Optional: `vendor`, `maxInputPrice` (USD per 1M input
  tokens), `minContext`, `minIntelligence`, `sortBy`
  (a subject such as `coding` or `math`, or `buzz` for
  popularity), `outputs`, `mode`, `accepts`, and `limit`
  (1-50, default 10).
- `compare_models` — two to six models side by side
  (`ids`, required): price, context, per-subject scores
  (untested subjects are marked, not zeroed), and the
  monthly cost at a volume (`monthlyMillionTokens`,
  default 10).
- `estimate_cost` — one model's monthly bill in USD and
  KRW (`id`, required), from `monthlyMillionTokens`
  (default 10) and an `inputShare` split (0-1, default
  0.75 input / 0.25 output).
- `get_today` — today in one call: the top 5 models,
  climbers, pricing changes from the last 24h, and new
  listings from the last 7 days. No arguments.
- `find_replacement` — what to switch to when a model is
  gone (`id`, required), ranked by closeness in measured
  performance, with score, price and context deltas.
  Candidates with less than half the original's context
  window are excluded.

## Configuration

- `AIWAVE_MCP_URL` (optional) — override the upstream
  endpoint. Defaults to
  `https://aiwave.elopstudio.com/api/mcp`.
  (The override hook is this rebuild's own labelled
  reconstruction.)
- `AIWAVE_API_KEY` (optional) — when set, every upstream
  request carries `Authorization: Bearer <key>`. When it
  is unset, no auth header is sent; the capture this
  rebuild is based on was taken keyless. (This forwarding
  is this rebuild's own labelled reconstruction.)

### Forwarding mechanics

On the first tool call the client opens a streamable
HTTP session with the upstream: a JSON-RPC `initialize`
request (protocolVersion `2025-03-26`, clientInfo name
`modelpulse`), then a `notifications/initialized`
notification, then the `tools/call` request carrying
the caller's arguments unchanged. When the upstream
answers `initialize` with an `Mcp-Session-Id` header,
that value rides on every later request of the
session, which is reused for the life of the process.
Replies may arrive as plain JSON or as
server-sent events; both are read.

Successful upstream results pass through verbatim,
including any `isError` flag the upstream sets.
Failures — a JSON-RPC error, a non-2xx status, an
unreadable response, or a request that cannot be
completed — come back as an `isError` result whose
text starts with `modelpulse error:` (this rendering is
this rebuild's own labelled reconstruction).

## CLI

Each tool is also a subcommand taking one JSON
argument string (omit it for tools that take none):

```bash
npx @reneturcios/modelpulse get_today
npx @reneturcios/modelpulse get_model '{"id":"anthropic/claude-opus-5"}'
npx @reneturcios/modelpulse compare_models '{"ids":["anthropic/claude-opus-5","openai/gpt-5.2"]}'
npx @reneturcios/modelpulse --version
```

Exit codes: `0` on success, `1` on an `isError`
result, `2` on a usage error.

## MCP server

```bash
npx -y @reneturcios/modelpulse mcp
```

MCP client config:

```json
{
  "mcpServers": {
    "modelpulse": {
      "command": "npx",
      "args": ["-y", "@reneturcios/modelpulse", "mcp"]
    }
  }
}
```

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/modelpulse
docker run --rm ghcr.io/cloudcorprecords/modelpulse --version
```

The container's default command is `mcp`, so the first
form is a stdio MCP server; any other arguments reach
the CLI normally.

## Development

```bash
npm install
npm run build
npm test
npm run dev
```

The test suite runs entirely against a stubbed
JSON-RPC upstream — no live network calls.

## License

MIT — see `LICENSE`.