@allratestoday/mcp-server 0.6.1 → 0.7.0

package/README.md

@@ -1,5 +1,7 @@
 # AllRatesToday MCP Server — @allratestoday/mcp-server
 
+Website: https://allratestoday.com · Hosted endpoint (no install): https://allratestoday.com/api/mcp · Docs: https://allratestoday.com/mcp/
+
 [![npm version](https://img.shields.io/npm/v/@allratestoday/mcp-server.svg)](https://www.npmjs.com/package/@allratestoday/mcp-server)
 [![npm downloads](https://img.shields.io/npm/dm/@allratestoday/mcp-server.svg)](https://www.npmjs.com/package/@allratestoday/mcp-server)
 [![license](https://img.shields.io/npm/l/@allratestoday/mcp-server.svg)](./LICENSE)
@@ -21,7 +23,7 @@ After installation, your assistant can answer questions like:
 
 - 📡 **Live mid-market rates** — 150+ ISO 4217 currencies, refreshed every ~60 seconds
 - 📈 **Historical series built in** — `1d` / `7d` / `30d` / `1y` windows with sensible granularity per period
-- 🧰 **Six focused tools** — `get_exchange_rate`, `get_historical_rates`, `get_rates_authenticated`, `list_currencies`, `list_central_banks`, `get_official_rates`; small surface, easy for the model to use correctly
+- 🧰 **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
 - 🛡️ **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
@@ -41,6 +43,8 @@ Install it with no configuration at all and it starts, connects, and answers:
 | `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. |
+| `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 free key. |
 | `get_rates_authenticated` | 🔑 | Same. |
 
@@ -198,8 +202,10 @@ After configuring your client, test in this order:
 - [`list_currencies`](#list_currencies) — all supported currency codes, names, symbols
 - [`list_central_banks`](#list_central_banks) — every covered central bank / tax authority with its code and latest publication date
 - [`get_official_rates`](#get_official_rates) — the official table (or one pair) a named institution published
+- [`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 four work keyless.
+`get_historical_rates` and `get_rates_authenticated` require `ALLRATES_API_KEY`; the other six work keyless.
 
 ---
 
@@ -374,6 +380,32 @@ Omit `source`/`target` for the whole table as `rates: [{ base, quote, type, valu
 
 ---
 
+### `get_reference_rate`
+
+AllRatesToday's **Daily Reference Rate**: the per-currency median of samples taken in a five-minute window centred on 16:00 London, published once per business day and never revised. Use it when a report, index or research series needs *one* reproducible rate per day. It is not the WM/Refinitiv fix and not a registered benchmark; every response carries a disclaimer and the `rate_date`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `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 |
+
+**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/
+
+---
+
+### `request_trial_key`
+
+Self-issues an API key with 100 lifetime calls, valid 7 days, with no account and no email, and switches this server to it for the rest of the session. The reply tells the user to copy the key into the MCP config as `ALLRATES_API_KEY` to keep it across restarts. Capped at 3 keys per IP per day.
+
+**Input** — `agent` (string, optional), `purpose` (string, optional).
+
+**Output** — `{ key, calls, expires_at, adopted, note }`.
+
+---
+
 ## ⚙️ Environment variables
 
 | Variable | Default | Required | Purpose |
@@ -474,6 +506,7 @@ server.json       # MCP registry manifest
 
 See [GitHub Releases](https://github.com/cahthuranag/mcp-server/releases) for the full list. Recent highlights:
 
+- **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)
 - **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

package/dist/client.d.ts

@@ -17,13 +17,34 @@ export declare class NeedsKeyError extends AllRatesTodayError {
     constructor(what: string);
 }
 export declare class AllRatesTodayClient {
-    private readonly apiKey?;
+    private 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;
+    /** Adopt a key at runtime (used after request_trial_key) so the rest of the session is keyed. */
+    setApiKey(key: string | undefined): void;
+    /**
+     * 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.
+     */
+    getReferenceRate(params?: {
+        source?: string;
+        target?: string;
+        date?: string;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Self-issue a trial key (100 calls, 7 days, no account) and adopt it for the
+     * rest of this process. POST with a JSON body: the site rejects bodiless
+     * POSTs as cross-site form submissions.
+     */
+    requestTrialKey(params?: {
+        agent?: string;
+        purpose?: string;
+    }): Promise<any>;
     getRate(source: string, target: string): Promise<{
         rate: number;
         source: string;

package/dist/client.js

@@ -81,6 +81,65 @@ export class AllRatesTodayClient {
     get keyless() {
         return !this.apiKey;
     }
+    /** Adopt a key at runtime (used after request_trial_key) so the rest of the session is keyed. */
+    setApiKey(key) {
+        this.apiKey = key || undefined;
+    }
+    /**
+     * 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.
+     */
+    getReferenceRate(params = {}) {
+        if (Boolean(params.source) !== Boolean(params.target)) {
+            return Promise.reject(new AllRatesTodayError('Provide both source and target, or neither.'));
+        }
+        const pair = { source: params.source?.toUpperCase(), target: params.target?.toUpperCase() };
+        if (params.date) {
+            if (this.keyless)
+                return Promise.reject(new NeedsKeyError(`The reference-rate table for ${params.date}`));
+            return this.request(`/v1/reference-rate/${encodeURIComponent(params.date)}`, pair);
+        }
+        return this.request('/open/reference-rate', pair);
+    }
+    /**
+     * Self-issue a trial key (100 calls, 7 days, no account) and adopt it for the
+     * rest of this process. POST with a JSON body: the site rejects bodiless
+     * POSTs as cross-site form submissions.
+     */
+    async requestTrialKey(params = {}) {
+        const res = await this.fetchImpl(`${this.baseUrl}/agent/keys`, {
+            method: 'POST',
+            headers: {
+                'Accept': 'application/json',
+                'Content-Type': 'application/json',
+                'User-Agent': `allratestoday-mcp/${VERSION}`,
+            },
+            body: JSON.stringify({ agent: params.agent, purpose: params.purpose }),
+        });
+        const text = await res.text();
+        let body;
+        try {
+            body = text ? JSON.parse(text) : null;
+        }
+        catch {
+            body = text;
+        }
+        if (!res.ok) {
+            const upstream = body && typeof body === 'object' && typeof body.error === 'string' ? body.error : undefined;
+            throw new AllRatesTodayError(upstream ?? `HTTP ${res.status}`, res.status, body);
+        }
+        const key = body && typeof body === 'object' && typeof body.key === 'string' ? body.key : undefined;
+        if (key)
+            this.setApiKey(key);
+        return {
+            ...(body ?? {}),
+            adopted: Boolean(key),
+            note: 'This server now uses the trial key for the rest of this session. To keep it after a restart, ' +
+                'put it in the MCP config: "env": { "ALLRATES_API_KEY": "<key>" }. For a lasting key register free ' +
+                '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

package/dist/index.js

@@ -45,6 +45,8 @@ async function main() {
             '    • 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',
+            '    • get_reference_rate — Daily Reference Rate, one fixed table per business day (16:00 London)',
+            '    • request_trial_key  — self-issue a 100-call, 7-day key without an account',
             '',
             '  Needs a free API key (real-time mid-market rates for 160+ currencies,',
             '  historical series, multi-target and point-in-time lookups):',
@@ -235,6 +237,62 @@ async function main() {
             return fail(err);
         }
     });
+    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`.",
+        inputSchema: {
+            source: ccy.optional().describe('Optional. With target, narrows to one pair.'),
+            target: ccy.optional().describe('Optional. With source, narrows to one pair.'),
+            date: z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .optional()
+                .describe('Optional past business day, YYYY-MM-DD (API key). Omit for the latest table.'),
+        },
+        outputSchema: {
+            rate_date: z.string().describe('Business day the table was fixed on — cite this'),
+            base: z.string().optional(),
+            time: z.string().optional().describe('Fixing time, e.g. 16:00 Europe/London'),
+            rates: z.record(z.string(), z.unknown()).optional().describe('Full table keyed by currency code'),
+            source: z.string().optional(),
+            target: z.string().optional(),
+            rate: z.number().optional(),
+            derived: z.boolean().optional(),
+            method: z.string().optional(),
+            disclaimer: z.string().optional(),
+        },
+        annotations: READ_ONLY,
+    }, async ({ source, target, date }) => {
+        try {
+            return ok(await client.getReferenceRate({ source, target, date }));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    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.',
+        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.'),
+        },
+        outputSchema: {
+            key: z.string().optional(),
+            calls: z.number().optional(),
+            expires_at: z.string().optional(),
+            adopted: z.boolean().describe('True when this server switched to the new key'),
+            note: z.string(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async ({ agent, purpose }) => {
+        try {
+            return ok(await client.requestTrialKey({ agent, purpose }));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/package.json

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