Price Ledger
README.md
# Price Ledger
A free, read-only MCP server for Canadian and U.S. price research. Ask how much a dozen eggs cost, check a four-package grocery total, or look up Canada's published annual inflation rate. Each answer identifies its dates, geography, units, source, and missing observations. The November 18, 2026 edition has seven series, 627 numerical observations and three tools.
## Start locally
Use Node.js 24, unpack the source, and run the following commands in the directory containing package.json. No npm install, API key, database or network connection is required.
```sh
node --test acceptance.test.mjs
node smoke.mjs
node server.mjs
```
The first command runs application and transport regressions. The second launches the server as a child process and runs a real stdio client. The last command starts the MCP server and waits for one JSON-RPC message per line on standard input. Normal operation produces no startup banner. A local MCP client can use this configuration, replacing the example path with the unpacked file:
```json
{"mcpServers":{"price-ledger":{"command":"node","args":["/absolute/path/to/server.mjs"]}}}
```
## Tools
| Tool | Arguments | Output |
| --- | --- | --- |
| price_catalog | {} | Seven IDs, types, date ranges, number of observed months, geography, units and provenance |
| price_history | series_id, start and end as YYYY-MM | All months in the interval, observations or gaps, source editions, endpoint difference and scope notes |
| price_basket | start and end as YYYY-MM | One package each of Canadian eggs, milk, white bread and butter. The result includes every component, currency and sources. One missing price makes that month's total null. |
All successful tool calls return one JSON-text MCP content item. Parse the item's text as JSON. A single call can return up to 144 months. For bulk jobs, use price_catalog to enumerate series, request ranges, and retain source editions and missing-value status. None of the tools fetches user-specified URLs or writes any data.
## Try these
**What did these four packages cost in Canada in September 2026?**
```json
{"name":"price_basket","arguments":{"start":"2026-09","end":"2026-09"}}
```
Expected total **CAD 19.49**, including eggs (one dozen, $4.83), milk (2 L, $5.50), white bread (675 g, $3.58) and butter (454 g, $5.58). This is the sum of national average package prices. No retailer or household is assumed to have paid that amount.
**How much were U.S. eggs in March 2025?**
```json
{"name":"price_history","arguments":{"series_id":"us-grade-a-large-eggs","start":"2025-03","end":"2025-03"}}
```
Expected first point: `{"month":"2025-03","value":6.227,"status":"observed","edition":"BLS-2026-11-18"}`. Unit is USD per dozen Grade A large eggs, U.S. city average. October 2025 returns null and the source-unavailable status. The Canadian and U.S. series describe different products and use different currencies.
**What was the official Canadian annual inflation rate?**
```json
{"name":"price_history","arguments":{"series_id":"ca-cpi-all-items-yoy","start":"2026-10","end":"2026-10"}}
```
Canada's all-items CPI rose **3.1% year over year** in October 2026. Food purchased from stores rose **2.0% year over year**. A difference between two published rates is in percentage points. A difference between retail prices is reported in currency per package.
## Coverage
| IDs | Area | Period in this edition |
| --- | --- | --- |
| ca-eggs-1-dozen, ca-milk-2-litres, ca-white-bread-675-grams, ca-butter-454-grams | Canada | Dec 2017–Apr 2025 and May–Sep 2026. The 12 intervening months are omitted from this official-source edition. |
| us-grade-a-large-eggs | U.S. city average | Jan 2016–Oct 2026. BLS marked Oct 2025 unavailable. |
| ca-cpi-food-at-stores-yoy, ca-cpi-all-items-yoy | Canada | Oct 2021–Oct 2026, 61 published annual rates each. |
An omitted Canadian month returns `not_in_edition`. The missing U.S. price returns `unavailable_from_source`. Requests beyond the packaged range return `outside_edition`. The server preserves all three. Prices stay in their published nominal currencies. There are no retailer listings, exchange rates, provincial retail series, user imports or live refresh in this small edition. See [source editions and refresh instructions](SOURCES.md). Project code is [MIT-licensed](LICENSE); the official data retains its separate source terms.
## MCPRush managed-host settings
| Studio field | Value |
| --- | --- |
| Source | This public GitHub repository |
| Access | Free |
| Hosting | We host it |
| Build method | Node.js (Node 24 Alpine) |
| Project directory | Repository root |
| Transport | stdio |
| Start command | node server.mjs |
| Install and build commands | Leave empty |
| Environment variables, credentials and ports | None |
The platform supplies the external HTTP adapter and gateway access. The server reads its observations from an immutable JavaScript module. It uses no writable storage, background scheduler, persistent tenant data, Apify account or external API. package.json is marked private to prevent accidental npm publication. The hosted build, tool discovery and listing review are separate steps. A free listing still uses the account's hosting allowance. [Managed hosting](https://mcprush.com/mcp-hosting) · [Publisher documentation](https://mcprush.com/docs)
The source includes the July 2026 stateless discovery exchange and earlier initialization-based MCP exchanges. The native smoke client exercises both. Upstream host compatibility requires an actual managed build and discovery check. [MCP discovery](https://modelcontextprotocol.io/specification/2026-07-28/server/discover) · [Legacy lifecycle](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues