ForgingStack Ration
# ForgingStack Ration
One quota pool, many agents, no overruns.
mcp-name: io.github.jdkabattles/forgingstack-ration
This is the **public client** for Ration. The service itself — the
token bucket, the receipt chain, the key store, and billing — runs
on ForgingStack's private service and is **not** in this repo.
Copying this repo does not give you the service: you still need an
API key and credits, from signup below.
Live API: https://forgingstack-ration.jkbattles.workers.dev
## What it does
A principal creates a pool with a capacity, a refill rate, a
per-agent cap, and a burst limit. Agents draw units from it. The
pool enforces the limits and issues a hash-chained receipt for
every draw attempt — allowed **and** denied.
A draw is denied when:
- the units exceed the burst limit (`draw_exceeds_burst`)
- the pool does not have enough available units
(`pool_insufficient_units`)
- the agent's allowed draws inside the rolling 60-minute window
would exceed the per-agent cap (`per_agent_cap_exceeded`)
The per-agent cap window is a rolling 60 minutes — a documented
design choice, not a calendar window.
## Signup (v1)
```bash
curl -X POST https://forgingstack-ration.jkbattles.workers.dev/v1/signup \
-H "Content-Type: application/json" \
-d '{"email":"you@example.com"}'
```
Returns an API key **once** and 100 starter credits. Save the key
immediately — it is stored only as a hash and cannot be shown again.
Click the verification link in the signup email before the key can
create pools or draw: until then, pool creation and draws return
403 `email_not_verified`.
## Buying more credits
1 credit per pool creation, 1 credit per draw call (allowed or
denied). Top-ups, pool reads, pool lists, and deletes are free.
```bash
curl -X POST https://forgingstack-ration.jkbattles.workers.dev/v1/billing/checkout \
-H "X-API-Key: YOUR_PRIMARY_KEY"
```
Returns the Stripe Payment Link: **$10 for 1,000 credits**. Pay on
Stripe's hosted page with the same email you signed up with.
Credits land once the payment is verified (within the hour).
## Use it (MCP, stdio)
Set the key, then run the MCP server in this repo:
```bash
export FORGINGSTACK_API_KEY="your-key-here"
python -m app.mcp_server
```
Tools: `create_pool`, `draw`, `get_pool`, `list_pools`,
`topup_pool`, `delete_pool`, `get_credits`, `get_receipt`.
See `SKILL.md` for when to use it and when not to.
## Price
1 credit per pool creation. 1 credit per draw call — a denied draw
still costs 1 credit, the draw was performed. An idempotent replay
(same `Idempotency-Key`) is free and returns the original receipt.
## Files in this repo
- `app/mcp_server.py` — MCP wrapper client (stdio, stdlib only)
- `SKILL.md` — when to use it, how to read allowed/denied
- `agent-card.json` — A2A-style discovery card
- `server.json` — MCP Registry metadata
- `pyproject.toml` — package metadata for the MCP client
TDQS
Scored across 8 tools
Each tool targets a distinct resource-action pair: pool lifecycle (create/get/list/topup/delete), unit consumption (draw), receipts (get_receipt), and billing (get_credits). The only near-pair, create_pool vs topup_pool, is cleanly separated by creation-vs-augmentation and by cost semantics. No two tools appear interchangeable.
Seven of eight tools follow a consistent snake_case verb_noun pattern (create_pool, get_pool, list_pools, topup_pool, delete_pool, get_credits, get_receipt). The lone bare verb 'draw' breaks the pattern, though its meaning remains obvious.
Eight tools is well within the sweet spot and every tool earns its place: CRUD on pools, the core draw operation, and supporting receipt/credit lookups. No redundancy or filler.
Pool lifecycle is well covered (create, read, list, topup, delete) plus draw and receipt retrieval, with billing visibility via get_credits. Gaps remain: no way to enumerate draws/receipts for a pool (receipts only fetchable by known id) and no way to adjust pool capacity or refill rate after creation.