@allratestoday/mcp-server 0.4.2 → 0.5.0

package/README.md

@@ -23,19 +23,56 @@ After installation, your assistant can answer questions like:
 - 📈 **Historical series built in** — `1d` / `7d` / `30d` / `1y` windows with sensible granularity per period
 - 🧰 **Four focused tools** — `get_exchange_rate`, `get_historical_rates`, `get_rates_authenticated`, `list_currencies`; 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
-- 🛡️ **Fail-fast and honest** — refuses to start without a key, maps API errors to clear actionable messages the assistant can relay
+- 🔓 **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
+- 🛡️ **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
 
-## 🔑 Get your API key
+## ⚖️ Mid-market vs official central-bank rates
 
-The server **will not start** without a valid `ALLRATES_API_KEY`. A free key is enough for development and personal use — **no credit card required**.
+Everything this server returns is a **mid-market rate**: the live interbank midpoint, 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, AllRatesToday also serves **published central-bank and tax-authority rates** (100+ sources — ECB, Fed, HMRC, US Treasury, …) that are fixed once published and carry the institution's own publication date — via 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
+
+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. |
+| `list_currencies` | ✅ | All 160+ supported ISO 4217 codes. |
+| `get_historical_rates` | 🔑 | Returns one sentence explaining how to get a free key. |
+| `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.
+
+## 🔑 Get your API key (free)
+
+A key unlocks **real-time mid-market rates across 160+ currencies**, historical
+series, and multi-target / point-in-time lookups. The free tier is enough for
+development and personal use — **no credit card required**.
 
 1. Register at [allratestoday.com/register](https://allratestoday.com/register) — 30 seconds
 2. Verify your email
 3. Copy your key from the dashboard (format: `art_live_xxxxx`)
 4. Use it as `ALLRATES_API_KEY` in the configs below
 
-If you forget, the server prints registration instructions on stderr and exits with code 1.
+Without one the server prints a short summary of keyless mode on stderr and
+keeps running — it never exits, because an MCP server that exits breaks the
+host client's whole configuration.
+
+## 🧩 Easiest install: the Claude Code plugin
+
+If you use Claude Code, install the plugin instead of configuring this server by
+hand — it bundles both AllRatesToday MCP servers, two skills, and five slash
+commands (`/rate`, `/convert`, `/official-rate`, `/fx-history`,
+`/add-currency-support`):
+
+```
+/plugin marketplace add AllRates-Today/claude-code-plugin
+/plugin install allratestoday@allratestoday
+```
+
+Everything below still applies for other MCP clients.
 
 ## 📦 Installation
 
@@ -268,7 +305,7 @@ All supported currencies with codes, names, and symbols. Cached upstream for 24
 
 | Variable | Default | Required | Purpose |
 |---|---|---|---|
-| `ALLRATES_API_KEY` | — | **yes** | Your API key. The server exits at startup if unset. |
+| `ALLRATES_API_KEY` | — | no | Your API key. 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.
@@ -281,7 +318,8 @@ A free tier and paid plans are available — see [allratestoday.com/pricing](htt
 
 | Symptom | Likely cause | Fix |
 |---|---|---|
-| Client shows "MCP server failed to start" or red dot | `ALLRATES_API_KEY` not set or invalid | Verify the key in your client config; check it matches the dashboard |
+| 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 |
 | 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 |
 | Historical tool returns "Bad request" | Invalid period or unknown currency code | Period must be `1d`/`7d`/`30d`/`1y`; codes must be 3 letters |
@@ -363,6 +401,7 @@ server.json       # MCP registry manifest
 
 See [GitHub Releases](https://github.com/cahthuranag/mcp-server/releases) for the full list. Recent highlights:
 
+- **0.5.0** — Keyless mode: the server starts and answers without an API key (`get_exchange_rate` via the open ECB reference table, `list_currencies` unchanged); metered tools return actionable sign-up guidance instead of the process exiting
 - **0.4.x** — README overhaul; registry metadata updates
 - **0.3.x** — API key required for all tools; fail-fast at startup with clear error
 - **0.2.x** — Removed news tool, required auth on `get_historical_rates`

package/dist/client.d.ts

@@ -8,12 +8,22 @@ export declare class AllRatesTodayError extends Error {
     readonly body?: unknown;
     constructor(message: string, status?: number | undefined, body?: unknown);
 }
+/**
+ * Thrown when a tool needs an endpoint that sits behind the API key. Carries
+ * the sign-up instructions so the assistant relays one actionable sentence
+ * rather than a bare 401.
+ */
+export declare class NeedsKeyError extends AllRatesTodayError {
+    constructor(what: string);
+}
 export declare class AllRatesTodayClient {
     private readonly apiKey?;
     private readonly baseUrl;
     private readonly fetchImpl;
     constructor(options?: ClientOptions);
     private request;
+    /** True when no API key is configured: only the open endpoints are reachable. */
+    get keyless(): boolean;
     getRate(source: string, target: string): Promise<{
         rate: number;
         source: string;

package/dist/client.js

@@ -10,6 +10,21 @@ export class AllRatesTodayError extends Error {
         this.name = 'AllRatesTodayError';
     }
 }
+/**
+ * Thrown when a tool needs an endpoint that sits behind the API key. Carries
+ * the sign-up instructions so the assistant relays one actionable sentence
+ * rather than a bare 401.
+ */
+export class NeedsKeyError extends AllRatesTodayError {
+    constructor(what) {
+        super(`${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) and ' +
+            'list_currencies.');
+        this.name = 'NeedsKeyError';
+    }
+}
 function errorMessage(status, upstream) {
     switch (status) {
         case 400:
@@ -37,14 +52,14 @@ export class AllRatesTodayClient {
             if (value !== undefined && value !== '')
                 url.searchParams.set(key, value);
         }
-        if (!this.apiKey) {
-            throw new AllRatesTodayError('AllRatesToday API key is required. Sign up free at https://allratestoday.com/register to get a key, then set ALLRATES_API_KEY in your MCP config.');
-        }
         const headers = {
             'Accept': 'application/json',
-            'User-Agent': `allratestoday-mcp/${VERSION}`,
-            'Authorization': `Bearer ${this.apiKey}`,
+            'User-Agent': this.apiKey
+                ? `allratestoday-mcp/${VERSION}`
+                : `allratestoday-mcp/${VERSION} (keyless)`,
         };
+        if (this.apiKey)
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
         const res = await this.fetchImpl(url.toString(), { method: 'GET', headers });
         const text = await res.text();
         let body;
@@ -62,13 +77,36 @@ export class AllRatesTodayClient {
         }
         return body;
     }
+    /** True when no API key is configured: only the open endpoints are reachable. */
+    get keyless() {
+        return !this.apiKey;
+    }
     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.
+        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.',
+            }));
+        }
         return this.request('/rate', { source, target });
     }
     getHistoricalRates(source, target, period = '7d') {
+        if (this.keyless)
+            return Promise.reject(new NeedsKeyError('Historical time-series'));
         return this.request('/historical-rates', { source, target, period });
     }
     getAuthenticatedRates(params) {
+        if (this.keyless)
+            return Promise.reject(new NeedsKeyError('Multi-target and point-in-time rates'));
         return this.request('/v1/rates', params);
     }
     listSymbols() {

package/dist/index.js

@@ -30,23 +30,26 @@ function fail(err) {
 }
 async function main() {
     const apiKey = process.env.ALLRATES_API_KEY;
+    // No key is NOT a fatal error. get_exchange_rate falls back to the open,
+    // edge-cached ECB reference table and list_currencies is already keyless, so
+    // the server is useful the moment it is installed; the metered tools explain
+    // how to get a free key when they are called. Exiting here instead would
+    // break the whole MCP config in the host client.
     if (!apiKey) {
         console.error([
             '',
-            '  AllRatesToday MCP server requires an API key.',
+            '  AllRatesToday MCP — running in KEYLESS mode.',
             '',
-            '  1. Sign up free at https://allratestoday.com/register (free tier — no card required)',
-            '  2. Copy your API key from the dashboard',
-            '  3. Set ALLRATES_API_KEY in your MCP client config:',
+            '  Available now, no key needed:',
+            '    • get_exchange_rate  — official ECB daily reference rate, ~30 major currencies',
+            '    • list_currencies    — all supported currency codes',
             '',
-            '     "allratestoday": {',
-            '       "command": "npx",',
-            '       "args": ["-y", "@allratestoday/mcp-server"],',
-            '       "env": { "ALLRATES_API_KEY": "art_live_..." }',
-            '     }',
+            '  Needs a free API key (real-time mid-market rates for 160+ currencies,',
+            '  historical series, multi-target and point-in-time lookups):',
+            '    1. https://allratestoday.com/register — free tier, no card, under a minute',
+            '    2. Add to this server\'s MCP config:  "env": { "ALLRATES_API_KEY": "art_live_..." }',
             '',
         ].join('\n'));
-        process.exit(1);
     }
     const client = new AllRatesTodayClient({
         apiKey,
@@ -60,6 +63,11 @@ async function main() {
         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.
+            rate_date: z.string().optional(),
+            derived: z.boolean().optional(),
+            note: z.string().optional(),
         },
         annotations: READ_ONLY,
     }, async ({ source, target }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allratestoday/mcp-server",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "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": [