# umeter

> umeter tracks AI usage limits and their reset windows (Claude, ChatGPT, Gemini…), subscriptions (Netflix, Spotify…), usage/budget meters (cloud spend) and one-off expirations, and sends alerts to Discord, Telegram and an in-app inbox. Data lives in workspaces; every agent connection is bound to one workspace.

## Connect an agent

- MCP server (Streamable HTTP): https://umeter.psyirius.dev/mcp
  - Sign in with OAuth: the client discovers it from https://umeter.psyirius.dev/.well-known/oauth-protected-resource/mcp (dynamic client registration, PKCE, scopes `trackers:read` and `trackers:write`). The user picks a workspace and can grant read-only access.
  - Or send a workspace API token: `Authorization: Bearer um_…` (created under Settings → API tokens).
- HTTP: `POST https://umeter.psyirius.dev/api/v1/tools/{tool}` with the tool's arguments as JSON and the same bearer token. Catalog: https://umeter.psyirius.dev/api/v1/tools
- OpenAPI 3.1: https://umeter.psyirius.dev/api/v1/openapi.json
- In the browser: when signed in, the web app registers the same tools with WebMCP (`document.modelContext`) for the current workspace.

## Tools

- `get_workspace`: The connected umeter workspace: name, time zone, default currency, tracker counts by kind, and what needs attention (limited AI limits, meters over a threshold, things due in the next 24 hours). Call this first to orient yourself.
- `list_trackers`: List trackers in the workspace. Kinds: "limit" (AI usage limits with reset windows, e.g. Claude 5-hour sessions), "subscription" (recurring bills like Netflix), "meter" (usage or budget with % thresholds, e.g. cloud spend), "expiry" (one-off dates like a domain or certificate).
- `get_tracker`: Full details of one tracker: its extra limits (`meters`, each with its own reset) and, for meters, the last 10 readings.
- `upcoming`: What happens next, soonest first: limit resets, subscription renewals (with price), meter cycle resets and expirations within the given window.
- `spending_summary`: Monthly-equivalent subscription spend, totalled separately per currency (amounts are never converted between currencies), plus each active subscription.
- `list_alerts`: Alert history, newest first: reminders, "limit available again" pings, threshold crossings and digests, with delivery status. Use `pending` to see what is scheduled next.
- `list_presets`: Built-in presets for common services (Claude, ChatGPT, Gemini, Netflix, Spotify, AWS, …) with typical windows and prices. Pass a preset key to create_tracker.
- `record_usage` (write): Set a meter to an absolute value or add to it (e.g. this month's cloud spend so far). Crossing a % threshold queues an alert. Meters only.
- `set_limit_state` (write): Update a usage-limit tracker: "running" starts a rolling window now (e.g. the first Claude message of a session), "limited" means the cap was hit (pass when it resets if the service said so), "available" means usable again. Reminders are rescheduled automatically.
- `update_meter` (write): Act on an extra limit of a tracker (see `meters` in get_tracker), e.g. Claude Max's "Weekly" or "Opus" cap. For limit meters: "start_window" (rolling window starts now), "limited" (cap hit; pass reset_at or reset_in_minutes if known), "available". For usage meters: "usage" with `value` (the new total), or "reset".
- `reset_tracker` (write): Start over: a meter goes back to 0 for a new cycle, a limit becomes available. Other kinds can't be reset.
- `create_tracker` (write): Add a tracker, ideally from a preset (see list_presets) so windows and prices are filled in. Subscriptions and expirations need `date` (next renewal or expiry date). Reminders use the preset defaults and alerts go to all channels; fine-tune in the app afterwards.

Agents can never delete data or manage members, channels, tokens or workspace settings: that stays in the web app.

## Conventions

- Instants are ISO 8601 in UTC. Each tracker and the workspace have an IANA time zone.
- Money is per tracker with an ISO 4217 currency. Totals are per currency and never converted.
- Errors: `{ "error": { "code", "message" } }` over HTTP; `isError: true` tool results over MCP.

## Ingest endpoints (scripts and cron jobs)

- `GET /api/v1/trackers`, `GET /api/v1/trackers/{id}`
- `POST /api/v1/trackers/{id}/usage` `{ "value": n }` or `{ "increment": n }`
- `POST /api/v1/trackers/{id}/limit` `{ "state": "limited" | "running" | "available", "reset_at"?, "reset_in_minutes"? }`
- `POST /api/v1/trackers/{id}/reset`