@allratestoday/mcp-server 0.7.4 → 0.7.5

package/README.md

@@ -21,17 +21,17 @@ After installation, your assistant can answer questions like:
 
 ## 🚀 Why this server?
 
-- 📡 **Live mid-market rates** — 150+ ISO 4217 currencies, refreshed every ~60 seconds
+- 📡 **Live mid-market rates** — 160+ ISO 4217 currencies, refreshed every ~60 seconds
 - 📈 **Historical series built in** — `1d` / `7d` / `30d` / `1y` windows with sensible granularity per period
 - 🧰 **Eight focused tools** — `get_exchange_rate`, `get_historical_rates`, `get_rates_authenticated`, `list_currencies`, `list_central_banks`, `get_official_rates`, `get_reference_rate`, `request_trial_key`; small surface, easy for the model to use correctly
 - 🔌 **Works everywhere MCP does** — stdio transport, MCP 1.x; Claude Code, Cursor, Claude Desktop, Windsurf, or any generic host
-- 🔓 **Works with no API key** — installs and answers out of the box from the open ECB reference table; a free key unlocks real-time rates for 160+ currencies
+- 🔓 **Works with no API key** — installs and answers out of the box from open official central-bank tables (ECB first, else the bank that issues one of the two currencies); a free key unlocks real-time rates for 160+ currencies
 - 🛡️ **Honest about what it returned** — every keyless answer says which rate it is and when it was published; API errors map to clear, actionable messages
 - 🔒 **Nothing leaks** — only the request parameters and your API key ever reach allratestoday.com; never conversation context
 
 ## ⚖️ Mid-market vs official central-bank rates
 
-Everything this server returns is a **mid-market rate**, refreshed every ~60 seconds — the right number for price display, conversion, and anything that should track the market. It is *not* the official rate a tax authority or auditor may require. For those, call **`get_official_rates`**: the latest table published by any of 121 central banks and 3 tax authorities (ECB, Fed, HMRC, US Treasury, Swiss BAZG, …), fixed once published and carrying the institution's own `rate_date`, no key needed. `list_central_banks` gives the codes. Dated tables and history sit behind the free key — see the [central bank REST API](https://allratestoday.com/docs/#central-bank) and [per-bank npm SDKs](https://allratestoday.com/central-bank-rates-api/). The two can diverge by several percent, so pick by use case, not convenience.
+With a key, `get_exchange_rate`, `get_historical_rates` and `get_rates_authenticated` return a **mid-market rate**, refreshed every ~60 seconds — the right number for price display, conversion, and anything that should track the market. It is *not* the official rate a tax authority or auditor may require. For those, call **`get_official_rates`**: the latest table published by any of 121 central banks and 3 tax authorities (ECB, Fed, HMRC, US Treasury, Swiss BAZG, …), fixed once published and carrying the institution's own `rate_date`, no key needed. `list_central_banks` gives the codes. Dated official tables (a past `date`) need an API key on a **paid plan** — a free key gets `403 Historical central bank rates require a paid plan`; mid-market history (`get_historical_rates`) works on the free key. See the [central bank REST API](https://allratestoday.com/docs/#central-bank) and [per-bank npm SDKs](https://allratestoday.com/central-bank-rates-api/). The two can diverge by several percent, so pick by use case, not convenience.
 
 ## 🔓 Keyless mode — what works with no setup
 
@@ -39,24 +39,25 @@ Install it with no configuration at all and it starts, connects, and answers:
 
 | Tool | Keyless | What you get |
 |---|---|---|
-| `get_exchange_rate` | ✅ | Official **ECB daily reference rate**, ~30 major currencies. The response carries `rate_date` and a note saying so, so the assistant never passes it off as a live quote. |
+| `get_exchange_rate` | ✅ | An **official central-bank rate**: the ECB reference table first, else the central bank that issues the target or source currency (USD/GBP → Bank of England, USD/INR → Reserve Bank of India). The response carries `bank`, `rate_date`, `derived` and a note saying so, so the assistant never passes it off as a live quote. Only pairs one bank publishes, or their inverses (flagged `derived: true`), work keyless; other crosses are refused with a pointer to the key. |
 | `list_currencies` | ✅ | All 160+ supported ISO 4217 codes. |
 | `list_central_banks` | ✅ | Codes, names and latest publication date of all 121 central banks + 3 tax authorities. |
-| `get_official_rates` | ✅ | Latest **official table** (or one pair) published by any of them. A dated table needs the key. |
-| `get_reference_rate` | ✅ | The **Daily Reference Rate**: one never-revised table per business day, fixed at 16:00 London. A past date needs the key. |
+| `get_official_rates` | ✅ | Latest **official table** (or one pair) published by any of them. A dated table needs a paid-plan key. |
+| `get_reference_rate` | ✅ | The **Daily Reference Rate**: one never-revised table per business day, fixed at 16:00 London. A past date needs a paid-plan key. |
 | `request_trial_key` | ✅ | Self-issues a 100-call, 7-day key with no account and adopts it for the session. |
 | `get_historical_rates` | 🔑 | Returns one sentence explaining how to get a key. Needs a paid plan. |
 | `get_rates_authenticated` | 🔑 | Same. |
 
-The keyless path reads the open, edge-cached `/api/open/central-bank/ecb`
-endpoint — no upstream cost, no rate limit to trip over, nothing to sign up for.
+The keyless path reads the open, edge-cached `/api/open/central-bank/{bank}`
+endpoints — no upstream cost, no rate limit to trip over, nothing to sign up for.
 
 ## 🔑 Get your API key (free)
 
 A key unlocks **real-time mid-market rates across 160+ currencies** and
-multi-target lookups. The free tier (300 requests, one-time) is enough for
-development and personal use — **no credit card required**. Historical series
-and point-in-time lookups need a paid plan from €4.99/month.
+multi-target lookups. The free tier (300 requests, lifetime — it does not reset
+monthly) is enough for development and trying it out — **no credit card required**.
+Historical series, point-in-time lookups and dated official and reference-rate
+tables need a paid plan from €4.99/month.
 
 1. Register at [allratestoday.com/register](https://allratestoday.com/register) — 30 seconds
 2. Verify your email
@@ -83,7 +84,7 @@ Everything below still applies for other MCP clients.
 
 ## ☁️ Hosted endpoint — nothing to install
 
-The same tools also run as a hosted **Streamable HTTP** MCP server (together with the tools of the sibling AllRatesToday server, nine in total). Paste the URL into any client that supports remote MCP — Claude.ai and Claude Desktop connectors, ChatGPT, Cursor, VS Code, Codex, Gemini CLI:
+The same tools also run as a hosted **Streamable HTTP** MCP server, which lists **11 tools**: the 8 of this stdio package plus `get_official_rate_history`, `compare_official_rates` and `get_publication_calendar` from the sibling central-bank server. Paste the URL into any client that supports remote MCP — Claude.ai and Claude Desktop connectors, ChatGPT, Cursor, VS Code, Codex, Gemini CLI:
 
 ```
 https://allratestoday.com/api/mcp
@@ -145,7 +146,7 @@ Edit `~/.cursor/mcp.json` (or `.cursor/mcp.json` inside your project for project
 }
 ```
 
-Restart Cursor. The six tools should appear in the MCP tool picker.
+Restart Cursor. The eight tools should appear in the MCP tool picker.
 
 ### Claude Desktop
 
@@ -191,8 +192,8 @@ npx -y @allratestoday/mcp-server
 
 After configuring your client, test in this order:
 
-1. **Server starts** — open the client. A red dot or "failed to connect" means the API key is missing or wrong (see Troubleshooting below).
-2. **Tools are listed** — most clients have a "tools" or "MCP" panel showing the six tools.
+1. **Server starts** — open the client. The server starts with or without a key (no key ⇒ keyless mode), so a red dot or "failed to connect" means the client could not launch it — usually `npx` or Node ≥18 (see Troubleshooting below). A wrong key does not stop it starting; calls then return `Invalid AllRatesToday API key`.
+2. **Tools are listed** — most clients have a "tools" or "MCP" panel showing the eight tools.
 3. **A live call returns a number** — ask: *"What's the current USD to EUR rate?"* The assistant should call `get_exchange_rate(source: "USD", target: "EUR")` and reply with a real rate. If it fabricates a number without a tool call, the server isn't connected.
 
 ## 📚 Tools reference
@@ -206,7 +207,7 @@ After configuring your client, test in this order:
 - [`get_reference_rate`](#get_reference_rate) — the Daily Reference Rate, one fixed mid-market table per business day (16:00 London)
 - [`request_trial_key`](#request_trial_key) — self-issue a 100-call, 7-day trial key, no account needed
 
-`get_historical_rates` and `get_rates_authenticated` require `ALLRATES_API_KEY`; the other six work keyless. History (`get_historical_rates`, and `time` on `get_rates_authenticated`) needs a paid plan.
+`get_historical_rates` and `get_rates_authenticated` require `ALLRATES_API_KEY`; the other six of the eight work keyless. History (`get_historical_rates`, and `time` on `get_rates_authenticated`) needs a paid plan.
 
 ---
 
@@ -227,12 +228,27 @@ Current mid-market rate between two currencies.
 { "source": "USD", "target": "EUR" }
 ```
 
-**Response:**
+**Response (with a key):**
+
+```json
+{ "rate": 0.888889, "source": "interbank" }
+```
+
+**Response (keyless — `USD` → `GBP`, not in the ECB table, so the Bank of England table answers):**
 
 ```json
-{ "rate": 0.92145, "source": "wise" }
+{
+  "rate": 0.7598784195,
+  "source": "Bank of England official rate (keyless mode)",
+  "bank": "boe",
+  "rate_date": "2026-10-14",
+  "derived": true,
+  "note": "Keyless mode: this is the Bank of England official rate published on 2026-10-14, not a live mid-market quote. For real-time rates across 160+ currencies set ALLRATES_API_KEY — free tier at https://allratestoday.com/register."
+}
 ```
 
+`derived: true` means the bank publishes the inverse (GBP→USD) and the rate was inverted. A pair no single bank publishes is refused keyless with `No keyless official source covers …` and a pointer to the key.
+
 ### `get_historical_rates`
 
 Time-series data points for a currency pair over a fixed period. Needs an API key on a paid plan (free and trial keys get a 403).
@@ -268,9 +284,10 @@ Time-series data points for a currency pair over a fixed period. Needs an API ke
   "target": "INR",
   "period": "30d",
   "data": [
-    { "date": "2026-03-27T00:00:00Z", "rate": 83.42, "timestamp": 1743033600000 },
-    { "date": "2026-03-28T00:00:00Z", "rate": 83.51, "timestamp": 1743120000000 },
-    "..."
+    { "date": "2026-09-17", "rate": 96.1006, "timestamp": 1789603200000 },
+    { "date": "2026-09-18", "rate": 95.8142, "timestamp": 1789689600000 },
+    "...",
+    { "date": "2026-10-16", "rate": 94.9643, "timestamp": 1792108800000 }
   ]
 }
 ```
@@ -297,11 +314,13 @@ Multiple targets in one call, with optional historical timestamp or grouping win
 **Response:**
 
 ```json
-[
-  { "rate": 0.9214, "source": "USD", "target": "EUR", "time": "2026-04-26T11:00:00Z" },
-  { "rate": 0.7891, "source": "USD", "target": "GBP", "time": "2026-04-26T11:00:00Z" },
-  { "rate": 151.34, "source": "USD", "target": "JPY", "time": "2026-04-26T11:00:00Z" }
-]
+{
+  "rates": [
+    { "rate": 0.888889, "source": "USD", "target": "EUR", "time": "2026-10-16T12:16:01+0000" },
+    { "rate": 0.749766, "source": "USD", "target": "GBP", "time": "2026-10-16T12:16:01+0000" },
+    { "rate": 157.985, "source": "USD", "target": "JPY", "time": "2026-10-16T12:16:01+0000" }
+  ]
+}
 ```
 
 ### `list_currencies`
@@ -320,7 +339,7 @@ All supported currencies with codes, names, and symbols. Cached upstream for 24
     { "code": "GBP", "name": "British Pound", "symbol": "£" },
     "..."
   ],
-  "count": 162
+  "count": 163
 }
 ```
 
@@ -328,7 +347,7 @@ All supported currencies with codes, names, and symbols. Cached upstream for 24
 
 ### `list_central_banks`
 
-Every official source the server can quote — 121 central banks plus HMRC, the US Treasury and Swiss BAZG — with the `code` that `get_official_rates` takes as `bank`, the institution's name, its latest publication date and a `stale` flag when it is behind its own schedule. Keyless.
+Every official source the server can quote — 121 central banks plus HMRC, the US Treasury and Swiss BAZG — with the `code` that `get_official_rates` takes as `bank`, the institution's name, its latest publication date, `age_days`, its publication `cadence` and a `stale` flag when it is behind its own schedule. Keyless.
 
 **Input** — none.
 
@@ -337,12 +356,12 @@ Every official source the server can quote — 121 central banks plus HMRC, the
 ```json
 {
   "sources": [
-    { "code": "ecb", "name": "European Central Bank", "latest": "2026-09-30", "stale": false },
-    { "code": "fed", "name": "Federal Reserve", "latest": "2026-09-29", "stale": false },
+    { "code": "ecb", "name": "European Central Bank", "latest": "2026-10-15", "age_days": 1, "stale": false, "cadence": "daily" },
+    { "code": "fed", "name": "US Federal Reserve (H.10)", "latest": "2026-10-09", "age_days": 7, "stale": false, "cadence": "weekly" },
     "..."
   ],
-  "stale_count": 0,
-  "checked_at": "2026-10-01T09:00:00Z"
+  "stale_count": 3,
+  "checked_at": "2026-10-16T12:16:46.232Z"
 }
 ```
 
@@ -357,7 +376,7 @@ The fixed, citable rate an institution published — for invoices, VAT and tax r
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `bank` | string | yes | Source code from `list_central_banks`, e.g. `ecb`, `fed`, `boe`, `rbi`, `hmrc` |
-| `date` | string | no | `YYYY-MM-DD`. Omit for the latest table (keyless). Needs the API key. Weekends/holidays roll back to the last published date. |
+| `date` | string | no | `YYYY-MM-DD`. Omit for the latest table (keyless). Needs an API key on a **paid plan** — a free key gets `403 Historical central bank rates require a paid plan`. Weekends/holidays roll back to the last published date. |
 | `source` | string | no | With `target`, narrows to one pair |
 | `target` | string | no | With `source`, narrows to one pair |
 
@@ -366,18 +385,21 @@ The fixed, citable rate an institution published — for invoices, VAT and tax r
 ```json
 {
   "bank": "ecb",
-  "rate_date": "2026-09-30",
+  "rate_date": "2026-10-15",
   "source": "EUR",
   "target": "USD",
-  "rate": 1.1355,
+  "rate": 1.1208,
   "rate_type": "reference",
   "derived": false,
   "method": "published",
+  "age_days": 1,
+  "stale": false,
+  "cadence": "daily",
   "attribution": { "source": "Official rates published by ECB, served by AllRatesToday", "url": "https://allratestoday.com/central-bank-rates-api/ecb/", "terms": "Free to use with visible attribution linking to allratestoday.com" }
 }
 ```
 
-Omit `source`/`target` for the whole table as `rates: [{ base, quote, type, value }]`. Pairs the bank does not publish directly are cross-computed inside its own table and flagged `derived: true`. Always cite `rate_date`.
+Omit `source`/`target` for the whole table as `rates: [{ base, quote, type, value }]`. Keyless, only pairs the bank publishes and their inverses (flagged `derived: true`) are served; other crosses are refused. With a key, pairs the bank does not publish directly are cross-computed inside its own table and flagged `derived: true`. Always cite `rate_date`.
 
 ---
 
@@ -391,7 +413,7 @@ AllRatesToday's **Daily Reference Rate**: the per-currency median of samples tak
 |---|---|---|---|
 | `source` | string | no | With `target`, narrows to one pair (crossed via USD, flagged `derived`) |
 | `target` | string | no | See above |
-| `date` | string | no | Past business day `YYYY-MM-DD` (API key). Omit for the latest table |
+| `date` | string | no | Past business day `YYYY-MM-DD` (API key on a paid plan). Omit for the latest table |
 
 **Output** — `{ rate_date, base, time, rates }` for the table, or `{ rate_date, source, target, rate, derived }` for a pair, plus `method` and `disclaimer`. Keyless for the latest table. Docs: https://allratestoday.com/reference-rate/
 
@@ -411,23 +433,25 @@ Self-issues an API key with 100 lifetime calls, valid 7 days, with no account an
 
 | Variable | Default | Required | Purpose |
 |---|---|---|---|
-| `ALLRATES_API_KEY` | — | no | Your API key. Unset ⇒ keyless mode (see above); set ⇒ real-time rates and the historical tools. |
+| `ALLRATES_API_KEY` | — | no | Your API key, sent as `Authorization: Bearer`. Unset ⇒ keyless mode (see above); set ⇒ real-time rates and the historical tools. |
 | `ALLRATES_BASE_URL` | `https://allratestoday.com/api` | no | Override for self-hosted or staging deployments. |
 
 Set these in your MCP client's config (in the `env` block) — not in your shell — because MCP servers are launched as subprocesses with isolated environments.
 
 ## 💳 Plans
 
-A free tier and paid plans are available — see [allratestoday.com/pricing](https://allratestoday.com/pricing) for current quotas. All plans include the same currency coverage and historical depth; only the request quotas differ.
+A free tier and paid plans are available — see [allratestoday.com/pricing](https://allratestoday.com/pricing) for current quotas. The free tier is 300 requests, lifetime (it never resets), and covers real-time rates, mid-market history and multi-target lookups. Dated official and reference-rate tables need a paid plan. The Official Rates plan covers official central-bank and tax-authority rates only (no market rates).
 
 ## 🛠️ Troubleshooting
 
 | Symptom | Likely cause | Fix |
 |---|---|---|
 | Client shows "MCP server failed to start" or red dot | Not a missing key — 0.5.0+ starts fine without one. Usually `npx` cannot reach the registry, or Node is older than 18 | Run `npx -y @allratestoday/mcp-server` in a shell and read stderr |
-| Rates look like yesterday's, response mentions "keyless mode" | No key set, so answers come from the ECB daily reference table | Set `ALLRATES_API_KEY` for real-time mid-market rates |
+| Rates look like yesterday's, response mentions "keyless mode" | No key set, so answers come from an official central-bank table (see `bank` and `rate_date`) | Set `ALLRATES_API_KEY` for real-time mid-market rates |
+| `No keyless official source covers X/Y` | Keyless mode, and no single central bank publishes that pair or its inverse | Set `ALLRATES_API_KEY` (free) |
+| `HTTP 403 — Historical central bank rates require a paid plan` | `date` given to `get_official_rates` / `get_reference_rate` on a free key | Omit `date` for the latest table, or upgrade at /pricing |
 | Every call returns "Invalid AllRatesToday API key" | Key is malformed (missing prefix, truncated, or revoked) | Copy a fresh key from the dashboard |
-| Tools return "AllRatesToday API quota exceeded" | Monthly limit hit | Wait until next month or upgrade plan |
+| Tools return "AllRatesToday API quota exceeded" | Quota used up — the free tier is 300 requests lifetime and never resets; paid plans are monthly | Upgrade at [/pricing](https://allratestoday.com/pricing) |
 | Historical tool returns "Bad request" | Invalid period or unknown currency code | Period must be `1d`/`7d`/`30d`/`1y`; codes must be 3 letters |
 | Server starts but tools never appear | Client didn't reload after config change | Fully quit (not just close) and reopen the client |
 | `npx` runs but hangs forever | The server is waiting for an MCP client to connect — normal when run from a shell | Let your MCP client launch it |
@@ -449,13 +473,15 @@ The server maps API errors to clear, actionable messages the assistant can relay
 | 200 | Success | (rate returned) |
 | 400 | Bad request — usually unknown currency code | `Bad request — possibly an unknown currency code` |
 | 401 | Invalid or missing API key | `Invalid AllRatesToday API key` |
+| 403 | Plan does not include it (e.g. a dated official table on a free key) | `HTTP 403 — <upstream message>` |
+| 404 (keyless) | No keyless official source covers the pair | `No keyless official source covers X/Y. …` |
 | 429 | Quota exceeded | `AllRatesToday API quota exceeded` |
 | 5xx | Server-side issue at allratestoday.com | `HTTP 5xx — <upstream message>` |
 
 ## ❓ FAQ
 
 **Is the free plan really enough for normal use?**
-Yes for personal/dev use. Heavy interactive use, multiple chat sessions per day, or production should consider the paid tiers.
+For trying it out and light dev use. It is 300 requests in total (lifetime, no monthly reset); regular use or production needs a paid tier. Keyless mode costs nothing and has no quota.
 
 **Do you store my conversation or query data?**
 No. Only your API key and the request parameters (source, target, period, time) are sent to allratestoday.com — never the LLM's conversation context.
@@ -496,7 +522,8 @@ ALLRATES_BASE_URL=http://localhost:8080/api ALLRATES_API_KEY=test_key node dist/
 ```
 src/
 ├── index.ts      # MCP server, tool registration, request handlers
-└── client.ts     # HTTP client for AllRatesToday API + error mapping
+├── client.ts     # HTTP client for AllRatesToday API + error mapping
+└── home-banks.ts # currency → issuing central bank, for the keyless get_exchange_rate fallback
 dist/             # Compiled JS (gitignored)
 server.json       # MCP registry manifest
 ```
@@ -507,6 +534,7 @@ server.json       # MCP registry manifest
 
 See [GitHub Releases](https://github.com/AllRates-Today/mcp-server/releases) for the full list. Recent highlights:
 
+- **0.7.4** — Keyless `get_exchange_rate` falls back from the ECB table to the central bank that issues the target or source currency (USD/GBP, GBP/JPY, USD/INR now answer keyless), same as the hosted endpoint; response adds `bank`. Dated-table errors say a paid plan is needed. README: real response shapes, tool counts, 300-lifetime free tier
 - **0.7.0** — `get_reference_rate` (Daily Reference Rate, 16:00 London, keyless latest table) and `request_trial_key` (self-issued 100-call trial key adopted for the session)
 - **0.6.1** — README: Claude Code plugin and hosted `/api/mcp` endpoint cross-links; coverage wording refreshed
 - **0.6.0** — Official rates: new keyless `list_central_banks` and `get_official_rates` tools expose the latest table from 121 central banks + 3 tax authorities (dated tables need the key)

package/dist/client.d.ts

@@ -29,7 +29,7 @@ export declare class AllRatesTodayClient {
     /**
      * Daily Reference Rate: one never-revised mid-market table per business day,
      * fixed at 16:00 London (median of samples in a 5-minute window). Latest
-     * table and single pairs are keyless; a dated table needs the key.
+     * table and single pairs are keyless; a dated table needs a paid-plan key.
      */
     getReferenceRate(params?: {
         source?: string;
@@ -48,6 +48,13 @@ export declare class AllRatesTodayClient {
     getRate(source: string, target: string): Promise<{
         rate: number;
         source: string;
+        bank: string;
+        rate_date: string;
+        derived: boolean;
+        note: string;
+    } | {
+        rate: number;
+        source: string;
     }>;
     getHistoricalRates(source: string, target: string, period?: '1d' | '7d' | '30d' | '1y'): Promise<{
         source: string;
@@ -85,7 +92,7 @@ export declare class AllRatesTodayClient {
     /**
      * Latest OFFICIAL table published by a central bank or tax authority, or one
      * pair from it (cross-computed inside the bank's own table when not published
-     * directly, flagged `derived`). Keyless; a dated table needs the key.
+     * directly, flagged `derived`). Keyless; a dated table needs a paid-plan key.
      */
     getOfficialRates(bank: string, params?: {
         date?: string;

package/dist/client.js

@@ -1,4 +1,5 @@
 import { VERSION } from './version.js';
+import { HOME_BANKS } from './home-banks.js';
 const DEFAULT_BASE_URL = 'https://allratestoday.com/api';
 export class AllRatesTodayError extends Error {
     status;
@@ -17,14 +18,16 @@ export class AllRatesTodayError extends Error {
  */
 export class NeedsKeyError extends AllRatesTodayError {
     constructor(what, paid = false) {
-        super((paid
-            ? `${what} needs an AllRatesToday API key on a paid plan (from €4.99/month, ` +
-                'https://allratestoday.com/pricing). Free and trial keys get latest rates only. Get a key at '
-            : `${what} needs an AllRatesToday API key. The free tier covers it — sign up at `) +
-            'https://allratestoday.com/register (no card, under a minute), then set ALLRATES_API_KEY ' +
-            "in this MCP server's config and restart. Without a key the server still answers " +
-            'get_exchange_rate for ~30 major currencies (official ECB daily reference rate), ' +
-            'list_currencies, list_central_banks and get_official_rates (latest tables).');
+        super(paid
+            ? `${what} needs an AllRatesToday API key on a paid plan (from €4.99/month; free and trial ` +
+                'keys get 403 for historical rates and dated tables) — see https://allratestoday.com/pricing, ' +
+                "then set ALLRATES_API_KEY in this MCP server's config and restart. Latest rates and the latest " +
+                'official tables need no paid plan.'
+            : `${what} needs an AllRatesToday API key. The free tier covers it — sign up at ` +
+                'https://allratestoday.com/register (no card, under a minute), then set ALLRATES_API_KEY ' +
+                "in this MCP server's config and restart. Without a key the server still answers " +
+                'get_exchange_rate from official central-bank tables (ECB first, then the issuing bank), ' +
+                'list_currencies, list_central_banks and get_official_rates (latest tables).');
         this.name = 'NeedsKeyError';
     }
 }
@@ -91,7 +94,7 @@ export class AllRatesTodayClient {
     /**
      * Daily Reference Rate: one never-revised mid-market table per business day,
      * fixed at 16:00 London (median of samples in a 5-minute window). Latest
-     * table and single pairs are keyless; a dated table needs the key.
+     * table and single pairs are keyless; a dated table needs a paid-plan key.
      */
     getReferenceRate(params = {}) {
         if (Boolean(params.source) !== Boolean(params.target)) {
@@ -143,21 +146,45 @@ export class AllRatesTodayClient {
                 'at https://allratestoday.com/register (300 calls) or see https://allratestoday.com/pricing.',
         };
     }
-    getRate(source, target) {
-        // Keyless: fall back to the open, edge-cached ECB reference table. It is
-        // the official daily fixing rather than a live mid-market quote and covers
-        // ~30 majors, so the result is labelled for the model to relay honestly.
+    async getRate(source, target) {
+        // Keyless: answer from the open, edge-cached official tables. The ECB
+        // reference table goes first; when it does not cover the pair, the central
+        // bank that issues one of the two currencies almost always does (same
+        // order as the hosted /api/mcp server). Each answer is an official print
+        // with a publication date, not a live quote, so it is labelled for the
+        // model to relay honestly; `derived` is passed through from the API (true
+        // for an inverse or a cross inside that bank's own table).
         if (this.keyless) {
-            return this.request('/open/central-bank/ecb', { source, target }).then((r) => ({
-                rate: r.rate,
-                source: 'ECB official daily reference rate (keyless mode)',
-                rate_date: r.rate_date,
-                derived: r.derived ?? false,
-                note: 'Keyless mode: this is the European Central Bank reference rate published on ' +
-                    `${r.rate_date}, not a live mid-market quote, and covers ~30 major currencies. ` +
-                    'For real-time rates across 160+ currencies set ALLRATES_API_KEY — free tier at ' +
-                    'https://allratestoday.com/register.',
-            }));
+            const candidates = [{ code: 'ecb', name: 'European Central Bank' }];
+            for (const c of [target, source]) {
+                const home = HOME_BANKS[c];
+                if (home && !candidates.some((x) => x.code === home.code))
+                    candidates.push(home);
+            }
+            let lastErr;
+            for (const bank of candidates) {
+                try {
+                    const r = await this.request(`/open/central-bank/${bank.code}`, { source, target });
+                    return {
+                        rate: r.rate,
+                        source: `${bank.name} official rate (keyless mode)`,
+                        bank: bank.code,
+                        rate_date: r.rate_date,
+                        derived: r.derived ?? false,
+                        note: `Keyless mode: this is the ${bank.name} official rate published on ${r.rate_date}, ` +
+                            'not a live mid-market quote. For real-time rates across 160+ currencies set ' +
+                            'ALLRATES_API_KEY — free tier at https://allratestoday.com/register.',
+                    };
+                }
+                catch (err) {
+                    lastErr = err;
+                    if (!(err instanceof AllRatesTodayError && err.status === 404))
+                        throw err;
+                }
+            }
+            throw new AllRatesTodayError(`No keyless official source covers ${source}/${target}. Real-time rates for 160+ currencies ` +
+                'need an API key — set ALLRATES_API_KEY (free tier at https://allratestoday.com/register).' +
+                (lastErr instanceof AllRatesTodayError ? ` Last upstream error: ${lastErr.message}` : ''), 404);
         }
         return this.request('/rate', { source, target });
     }
@@ -178,7 +205,7 @@ export class AllRatesTodayClient {
     /**
      * Latest OFFICIAL table published by a central bank or tax authority, or one
      * pair from it (cross-computed inside the bank's own table when not published
-     * directly, flagged `derived`). Keyless; a dated table needs the key.
+     * directly, flagged `derived`). Keyless; a dated table needs a paid-plan key.
      */
     getOfficialRates(bank, params = {}) {
         const code = bank.trim().toLowerCase();

package/dist/home-banks.d.ts

@@ -0,0 +1,4 @@
+export declare const HOME_BANKS: Readonly<Record<string, {
+    code: string;
+    name: string;
+}>>;

package/dist/home-banks.js

@@ -0,0 +1,123 @@
+// Home currency → the central bank that issues it, for the keyless
+// get_exchange_rate fallback (mirrors the hosted /api/mcp server). Generated
+// from the site's central-banks list: first non-ECB central bank per home
+// currency, tax authorities and composites excluded.
+export const HOME_BANKS = {
+    USD: { code: "fed", name: "US Federal Reserve (H.10)" },
+    GBP: { code: "boe", name: "Bank of England" },
+    CNY: { code: "pboc", name: "People's Bank of China (CFETS)" },
+    AUD: { code: "rba", name: "Reserve Bank of Australia" },
+    RUB: { code: "cbr", name: "Bank of Russia" },
+    TRY: { code: "tcmb", name: "Central Bank of Türkiye" },
+    BRL: { code: "bcb", name: "Banco Central do Brasil (PTAX)" },
+    IDR: { code: "bi", name: "Bank Indonesia" },
+    INR: { code: "rbi", name: "Reserve Bank of India" },
+    CAD: { code: "boc", name: "Bank of Canada" },
+    MYR: { code: "bnm", name: "Bank Negara Malaysia" },
+    LKR: { code: "cbsl", name: "Central Bank of Sri Lanka" },
+    CZK: { code: "cnb", name: "Czech National Bank" },
+    PLN: { code: "nbp", name: "Narodowy Bank Polski" },
+    NOK: { code: "norges", name: "Norges Bank" },
+    SEK: { code: "riksbank", name: "Sveriges Riksbank" },
+    NGN: { code: "cbn", name: "Central Bank of Nigeria" },
+    KWD: { code: "cbk", name: "Central Bank of Kuwait" },
+    BHD: { code: "cbb", name: "Central Bank of Bahrain" },
+    AZN: { code: "cbar", name: "Central Bank of Azerbaijan" },
+    BAM: { code: "cbbh", name: "Central Bank of Bosnia and Herzegovina" },
+    EUR: { code: "bnb", name: "Bulgarian National Bank" },
+    PEN: { code: "bcrp", name: "Central Reserve Bank of Peru" },
+    JPY: { code: "boj", name: "Bank of Japan" },
+    HKD: { code: "hkma", name: "Hong Kong Monetary Authority" },
+    ILS: { code: "boi", name: "Bank of Israel" },
+    ARS: { code: "bcra", name: "Central Bank of Argentina" },
+    ZAR: { code: "sarb", name: "South African Reserve Bank" },
+    CHF: { code: "snb", name: "Swiss National Bank" },
+    NZD: { code: "rbnz", name: "Reserve Bank of New Zealand" },
+    KRW: { code: "bok", name: "Bank of Korea" },
+    RON: { code: "bnr", name: "National Bank of Romania" },
+    UAH: { code: "nbu", name: "National Bank of Ukraine" },
+    MXN: { code: "banxico", name: "Banco de México" },
+    PHP: { code: "bsp", name: "Bangko Sentral ng Pilipinas" },
+    DOP: { code: "bcrd", name: "Banco Central de la República Dominicana" },
+    PYG: { code: "bcp", name: "Banco Central del Paraguay" },
+    KHR: { code: "nbc", name: "National Bank of Cambodia" },
+    GHS: { code: "bog", name: "Bank of Ghana" },
+    EGP: { code: "cbe", name: "Central Bank of Egypt" },
+    ALL: { code: "boa", name: "Bank of Albania" },
+    GTQ: { code: "banguat", name: "Banco de Guatemala" },
+    MNT: { code: "bom", name: "Bank of Mongolia" },
+    SGD: { code: "mas", name: "Monetary Authority of Singapore" },
+    DKK: { code: "dnb", name: "Danmarks Nationalbank" },
+    COP: { code: "sfc", name: "Superintendencia Financiera de Colombia (TRM)" },
+    KZT: { code: "nbk", name: "National Bank of Kazakhstan" },
+    GEL: { code: "nbg", name: "National Bank of Georgia" },
+    UZS: { code: "cbu", name: "Central Bank of Uzbekistan" },
+    HUF: { code: "mnb", name: "Magyar Nemzeti Bank" },
+    ISK: { code: "cbi", name: "Central Bank of Iceland" },
+    AED: { code: "cbuae", name: "Central Bank of the UAE" },
+    PKR: { code: "sbp", name: "State Bank of Pakistan" },
+    NPR: { code: "nrb", name: "Nepal Rastra Bank" },
+    JOD: { code: "cbj", name: "Central Bank of Jordan" },
+    BDT: { code: "bb", name: "Bangladesh Bank" },
+    OMR: { code: "cbo", name: "Central Bank of Oman" },
+    MMK: { code: "cbm", name: "Central Bank of Myanmar" },
+    TWD: { code: "cbc", name: "Central Bank of the Republic of China (Taiwan)" },
+    THB: { code: "bot", name: "Bank of Thailand" },
+    MOP: { code: "amcm", name: "Monetary Authority of Macao" },
+    VND: { code: "sbv", name: "State Bank of Vietnam" },
+    LAK: { code: "bol", name: "Bank of the Lao PDR" },
+    VES: { code: "bcv", name: "Central Bank of Venezuela" },
+    CLP: { code: "bcch", name: "Central Bank of Chile" },
+    UYU: { code: "bcu", name: "Central Bank of Uruguay" },
+    BOB: { code: "bcbol", name: "Banco Central de Bolivia" },
+    SRD: { code: "cbvs", name: "Central Bank of Suriname" },
+    GYD: { code: "bogy", name: "Bank of Guyana" },
+    SAR: { code: "sama", name: "Saudi Central Bank (SAMA)" },
+    MAD: { code: "bam", name: "Bank Al-Maghrib" },
+    RSD: { code: "nbs", name: "National Bank of Serbia" },
+    BYN: { code: "nbrb", name: "National Bank of the Republic of Belarus" },
+    QAR: { code: "qcb", name: "Qatar Central Bank" },
+    IQD: { code: "cbiq", name: "Central Bank of Iraq" },
+    DZD: { code: "bda", name: "Bank of Algeria" },
+    CRC: { code: "bccr", name: "Banco Central de Costa Rica" },
+    XOF: { code: "bceao", name: "Central Bank of West African States (BCEAO)" },
+    ETB: { code: "nbe", name: "National Bank of Ethiopia" },
+    KES: { code: "cbke", name: "Central Bank of Kenya" },
+    MDL: { code: "nbm", name: "National Bank of Moldova" },
+    MKD: { code: "nbrm", name: "National Bank of North Macedonia" },
+    AMD: { code: "cba", name: "Central Bank of Armenia" },
+    XAF: { code: "beac", name: "Bank of Central African States (BEAC)" },
+    TND: { code: "bct", name: "Central Bank of Tunisia" },
+    RWF: { code: "bnrw", name: "National Bank of Rwanda" },
+    AOA: { code: "bna", name: "National Bank of Angola" },
+    TZS: { code: "botz", name: "Bank of Tanzania" },
+    UGX: { code: "bou", name: "Bank of Uganda" },
+    JMD: { code: "bojm", name: "Bank of Jamaica" },
+    NIO: { code: "bcn", name: "Banco Central de Nicaragua" },
+    HNL: { code: "bch", name: "Banco Central de Honduras" },
+    TTD: { code: "cbtt", name: "Central Bank of Trinidad and Tobago" },
+    MUR: { code: "bmu", name: "Bank of Mauritius" },
+    MZN: { code: "bdm", name: "Banco de Moçambique" },
+    BWP: { code: "bob", name: "Bank of Botswana" },
+    ZMW: { code: "boz", name: "Bank of Zambia" },
+    MWK: { code: "rbm", name: "Reserve Bank of Malawi" },
+    KGS: { code: "nbkr", name: "National Bank of the Kyrgyz Republic" },
+    CDF: { code: "bcc", name: "Banque Centrale du Congo" },
+    BBD: { code: "cbbd", name: "Central Bank of Barbados" },
+    LYD: { code: "cbl", name: "Central Bank of Libya" },
+    GMD: { code: "cbg", name: "Central Bank of The Gambia" },
+    HTG: { code: "brh", name: "Banque de la République d'Haïti" },
+    BTN: { code: "rma", name: "Royal Monetary Authority of Bhutan" },
+    TJS: { code: "nbt", name: "National Bank of Tajikistan" },
+    BZD: { code: "cbbz", name: "Central Bank of Belize" },
+    FJD: { code: "rbf", name: "Reserve Bank of Fiji" },
+    MVR: { code: "mma", name: "Maldives Monetary Authority" },
+    MRU: { code: "bcm", name: "Banque Centrale de Mauritanie" },
+    ZWG: { code: "rbz", name: "Reserve Bank of Zimbabwe" },
+    NAD: { code: "bon", name: "Bank of Namibia" },
+    MGA: { code: "bfm", name: "Central Bank of Madagascar (BFM)" },
+    TMT: { code: "cbt", name: "Central Bank of Turkmenistan" },
+    CUP: { code: "bccu", name: "Banco Central de Cuba" },
+    SLE: { code: "bsl", name: "Bank of Sierra Leone" },
+    STN: { code: "bcstp", name: "Banco Central de São Tomé e Príncipe" },
+};

package/dist/index.js

@@ -41,7 +41,7 @@ async function main() {
             '  AllRatesToday MCP — running in KEYLESS mode.',
             '',
             '  Available now, no key needed:',
-            '    • get_exchange_rate  — official ECB daily reference rate, ~30 major currencies',
+            '    • get_exchange_rate  — official central-bank rate (ECB, else the issuing bank)',
             '    • list_currencies    — all supported currency codes',
             '    • list_central_banks — 121 central banks + 3 tax authorities we carry',
             '    • get_official_rates — latest official table (or one pair) from any of them',
@@ -62,13 +62,14 @@ async function main() {
     const server = new McpServer({ name: 'allratestoday-mcp', version: VERSION });
     server.registerTool('get_exchange_rate', {
         title: 'Get live exchange rate',
-        description: "Use this when the user asks 'what is X in Y?', 'convert X to Y', 'current rate of EUR/USD', or any single fiat-to-fiat live exchange rate question. Returns the latest mid-market rate as a JSON object like { rate: 0.9234, source } meaning 1 source = 0.9234 target. Does NOT support cryptocurrencies, commodities, or arithmetic on amounts. For multiple targets in one call use get_rates_authenticated; for a past date or fixed lookback (7d/30d/1y) use get_historical_rates.",
+        description: "Use this when the user asks 'what is X in Y?', 'convert X to Y', 'current rate of EUR/USD', or any single fiat-to-fiat live exchange rate question. Returns the latest mid-market rate as a JSON object like { rate: 0.9234, source } meaning 1 source = 0.9234 target. Without an API key it answers from an official central-bank table instead (ECB first, else the bank that issues one of the two currencies) and says so in `note` — relay the `rate_date`; pairs no single bank publishes (or inverts) need a key. Does NOT support cryptocurrencies, commodities, or arithmetic on amounts. For multiple targets in one call use get_rates_authenticated; for a past date or fixed lookback (7d/30d/1y) use get_historical_rates.",
         inputSchema: { source: ccy, target: ccy },
         outputSchema: {
             rate: z.number().describe('How much 1 unit of source is worth in target'),
             source: z.string().describe('Upstream data provider the rate came from'),
-            // Keyless mode answers from the open ECB reference table and adds the
-            // publication date plus a note the assistant should relay.
+            // Keyless mode answers from an open central-bank table and adds the
+            // bank, publication date plus a note the assistant should relay.
+            bank: z.string().optional(),
             rate_date: z.string().optional(),
             derived: z.boolean().optional(),
             note: z.string().optional(),
@@ -154,7 +155,7 @@ async function main() {
     });
     server.registerTool('list_currencies', {
         title: 'List supported currencies',
-        description: "Call this BEFORE other tools when you are unsure whether a currency code is supported, or when the user asks 'what currencies do you support?', 'is X a valid currency?', or 'what is the symbol for X?'. Returns { currencies: [{ code: 'USD', name: 'US Dollar', symbol: '$' }, ...], count } covering 150+ ISO 4217 fiat currencies. Does NOT include cryptocurrencies. Cheap to call (cached 24h upstream) — use it to validate user input and prevent downstream errors in get_exchange_rate / get_rates_authenticated / get_historical_rates.",
+        description: "Call this BEFORE other tools when you are unsure whether a currency code is supported, or when the user asks 'what currencies do you support?', 'is X a valid currency?', or 'what is the symbol for X?'. Returns { currencies: [{ code: 'USD', name: 'US Dollar', symbol: '$' }, ...], count } covering 160+ ISO 4217 fiat currencies. Does NOT include cryptocurrencies. Cheap to call (cached 24h upstream) — use it to validate user input and prevent downstream errors in get_exchange_rate / get_rates_authenticated / get_historical_rates.",
         inputSchema: {},
         outputSchema: {
             currencies: z.array(z.object({
@@ -198,7 +199,7 @@ async function main() {
     });
     server.registerTool('get_official_rates', {
         title: "Get a bank's official published rates",
-        description: "OFFICIAL rates a named institution published — 'what is the ECB rate for USD?', 'Bank of Japan rate today', 'HMRC rate for invoicing'. These are the fixed, citable rates for compliance, tax, customs and accounting — NOT live market rates (use get_exchange_rate for those). Omit `date` for the newest published table (no API key needed); give `date` (API key) for the table in force that day — weekends/holidays roll back to the last published date and the response's `rate_date` says which. Omit source/target for the full table; give both for one pair — cross-computed inside the bank's own table when not directly published, flagged `derived`. Always cite the returned `rate_date`.",
+        description: "OFFICIAL rates a named institution published — 'what is the ECB rate for USD?', 'Bank of Japan rate today', 'HMRC rate for invoicing'. These are the fixed, citable rates for compliance, tax, customs and accounting — NOT live market rates (use get_exchange_rate for those). Omit `date` for the newest published table (no API key needed); give `date` (API key, paid plan) for the table in force that day — weekends/holidays roll back to the last published date and the response's `rate_date` says which. Omit source/target for the full table; give both for one pair — cross-computed inside the bank's own table when not directly published, flagged `derived`. Always cite the returned `rate_date`.",
         inputSchema: {
             bank: z
                 .string()
@@ -239,7 +240,7 @@ async function main() {
     });
     server.registerTool('get_reference_rate', {
         title: 'Get the Daily Reference Rate (16:00 London)',
-        description: "AllRatesToday's once-a-day, never-revised mid-market rate: the per-currency median of samples in a five-minute window centred on 16:00 London, published each business day. Use it when the user needs ONE reproducible rate per day — index levels, return series, research datasets, month-end reports — rather than a live quote (get_exchange_rate) or an institution's official rate (get_official_rates). Omit source/target for the whole table; give both for one pair (crossed via USD, flagged `derived`). Omit `date` for the latest table (no key needed); give `date` (API key) for a past business day. Not the WM/Refinitiv fix and not a registered benchmark — relay the disclaimer and the `rate_date`.",
+        description: "AllRatesToday's once-a-day, never-revised mid-market rate: the per-currency median of samples in a five-minute window centred on 16:00 London, published each business day. Use it when the user needs ONE reproducible rate per day — index levels, return series, research datasets, month-end reports — rather than a live quote (get_exchange_rate) or an institution's official rate (get_official_rates). Omit source/target for the whole table; give both for one pair (crossed via USD, flagged `derived`). Omit `date` for the latest table (no key needed); give `date` (API key, paid plan) for a past business day. Not the WM/Refinitiv fix and not a registered benchmark — relay the disclaimer and the `rate_date`.",
         inputSchema: {
             source: ccy.optional().describe('Optional. With target, narrows to one pair.'),
             target: ccy.optional().describe('Optional. With source, narrows to one pair.'),
@@ -247,7 +248,7 @@ async function main() {
                 .string()
                 .regex(/^\d{4}-\d{2}-\d{2}$/)
                 .optional()
-                .describe('Optional past business day, YYYY-MM-DD (API key). Omit for the latest table.'),
+                .describe('Optional past business day, YYYY-MM-DD (API key, paid plan). Omit for the latest table.'),
         },
         outputSchema: {
             rate_date: z.string().describe('Business day the table was fixed on — cite this'),
@@ -272,7 +273,7 @@ async function main() {
     });
     server.registerTool('request_trial_key', {
         title: 'Request a trial API key',
-        description: 'Self-issue an AllRatesToday API key with 100 lifetime calls, valid 7 days, with no account and no email. Use it when another tool answered "needs an API key" and the user wants real-time rates, history or dated tables right now. The key is adopted by this server for the rest of the session and returned once — tell the user to put it in the MCP config as ALLRATES_API_KEY to keep it. Capped at 3 keys per IP per day. For a lasting key, register at https://allratestoday.com/register (free, 300 calls) or see https://allratestoday.com/pricing.',
+        description: 'Self-issue an AllRatesToday API key with 100 lifetime calls, valid 7 days, with no account and no email. Use it when another tool answered "needs an API key" and the user wants real-time rates or history right now. The key is adopted by this server for the rest of the session and returned once — tell the user to put it in the MCP config as ALLRATES_API_KEY to keep it. Capped at 3 keys per IP per day. For a lasting key, register at https://allratestoday.com/register (free, 300 calls) or see https://allratestoday.com/pricing.',
         inputSchema: {
             agent: z.string().max(80).optional().describe('Optional: the agent or product requesting the key.'),
             purpose: z.string().max(200).optional().describe('Optional: one line on what the rates are for.'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allratestoday/mcp-server",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "mcpName": "io.github.cahthuranag/mcp-server",
   "description": "MCP server for AllRatesToday — let AI coding tools (Claude Code, Cursor, Claude Desktop) fetch real-time and historical currency exchange rates.",
   "keywords": [