@allratestoday/mcp-server 0.7.3 → 0.7.4

package/README.md

@@ -45,7 +45,7 @@ Install it with no configuration at all and it starts, connects, and answers:
 | `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_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`
@@ -53,9 +53,10 @@ endpoint — no upstream cost, no rate limit to trip over, nothing to sign up fo
 
 ## 🔑 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**.
+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.
 
 1. Register at [allratestoday.com/register](https://allratestoday.com/register) — 30 seconds
 2. Verify your email
@@ -205,7 +206,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.
+`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.
 
 ---
 
@@ -234,7 +235,7 @@ Current mid-market rate between two currencies.
 
 ### `get_historical_rates`
 
-Time-series data points for a currency pair over a fixed period.
+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).
 
 **Input**
 
@@ -284,7 +285,7 @@ Multiple targets in one call, with optional historical timestamp or grouping win
 |---|---|---|---|
 | `source` | string | yes | Source currency code |
 | `target` | string | yes | One or more codes, comma-separated (`EUR,GBP,JPY`) |
-| `time` | string (ISO 8601) | no | Historical point in time |
+| `time` | string (ISO 8601) | no | Historical point in time (paid plans) |
 | `group` | string | no | One of `hour`, `day`, `week`, `month` |
 
 **Example call**

package/dist/client.d.ts

@@ -14,7 +14,7 @@ export declare class AllRatesTodayError extends Error {
  * rather than a bare 401.
  */
 export declare class NeedsKeyError extends AllRatesTodayError {
-    constructor(what: string);
+    constructor(what: string, paid?: boolean);
 }
 export declare class AllRatesTodayClient {
     private apiKey?;

package/dist/client.js

@@ -16,8 +16,11 @@ export class AllRatesTodayError extends Error {
  * 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 ` +
+    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), ' +
@@ -97,7 +100,7 @@ export class AllRatesTodayClient {
         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 Promise.reject(new NeedsKeyError(`The reference-rate table for ${params.date}`, true));
             return this.request(`/v1/reference-rate/${encodeURIComponent(params.date)}`, pair);
         }
         return this.request('/open/reference-rate', pair);
@@ -160,7 +163,7 @@ export class AllRatesTodayClient {
     }
     getHistoricalRates(source, target, period = '7d') {
         if (this.keyless)
-            return Promise.reject(new NeedsKeyError('Historical time-series'));
+            return Promise.reject(new NeedsKeyError('Historical time-series', true));
         return this.request('/historical-rates', { source, target, period });
     }
     getAuthenticatedRates(params) {
@@ -188,7 +191,7 @@ export class AllRatesTodayClient {
         const pair = { source: params.source?.toUpperCase(), target: params.target?.toUpperCase() };
         if (this.keyless) {
             if (params.date)
-                return Promise.reject(new NeedsKeyError(`The ${code} table for ${params.date}`));
+                return Promise.reject(new NeedsKeyError(`The ${code} table for ${params.date}`, true));
             return this.request(`/open/central-bank/${encodeURIComponent(code)}`, pair);
         }
         return this.request(`/v1/central-bank/${encodeURIComponent(code)}/${params.date ?? 'latest'}`, pair);

package/dist/index.js

@@ -48,8 +48,8 @@ async function main() {
             '    • 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):',
+            '  Needs a free API key (real-time mid-market rates for 160+ currencies and',
+            '  multi-target lookups). Historical series and point-in-time lookups need a paid plan:',
             '    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_..." }',
             '',
@@ -84,7 +84,7 @@ async function main() {
     });
     server.registerTool('get_historical_rates', {
         title: 'Get historical rate time-series',
-        description: "Use this for fixed-window time-series questions like 'how has EUR/USD moved this week', 'show me the last month of GBP/JPY', or 'chart 1-year history of AUD/USD'. Returns { source, target, period, data: [{ date, rate, timestamp }, ...] } — sampling is fixed per period (1d=hourly, 7d/30d=daily, 1y=weekly) and the window always ends NOW. For a specific past datetime use get_rates_authenticated with `time`. For a single live rate use get_exchange_rate.",
+        description: "Use this for fixed-window time-series questions like 'how has EUR/USD moved this week', 'show me the last month of GBP/JPY', or 'chart 1-year history of AUD/USD'. Returns { source, target, period, data: [{ date, rate, timestamp }, ...] } — sampling is fixed per period (1d=hourly, 7d/30d=daily, 1y=weekly) and the window always ends NOW. Needs an API key on a paid plan; free and trial keys get a 403. For a specific past datetime use get_rates_authenticated with `time`. For a single live rate use get_exchange_rate.",
         inputSchema: {
             source: ccy,
             target: ccy,
@@ -115,7 +115,7 @@ async function main() {
     });
     server.registerTool('get_rates_authenticated', {
         title: 'Get multi-target or point-in-time rates',
-        description: "Use this for (a) one source against multiple targets in a single call ('USD vs EUR, GBP, JPY'), or (b) the rate at a specific past datetime ('EUR/USD at 2025-03-14T12:00Z'), optionally bucketed by hour/day/week/month. Returns { rates: [{ rate, source, target, time }, ...] } — one row per target × time bucket. For a single live pair use get_exchange_rate. For fixed lookback windows (1d/7d/30d/1y ending now) use get_historical_rates.",
+        description: "Use this for (a) one source against multiple targets in a single call ('USD vs EUR, GBP, JPY'), or (b) the rate at a specific past datetime ('EUR/USD at 2025-03-14T12:00Z'), optionally bucketed by hour/day/week/month. Returns { rates: [{ rate, source, target, time }, ...] } — one row per target × time bucket. Multi-target latest rates work on any key; a past datetime (`time`) needs a paid plan. For a single live pair use get_exchange_rate. For fixed lookback windows (1d/7d/30d/1y ending now) use get_historical_rates.",
         inputSchema: {
             source: ccy,
             target: ccyList,

package/package.json

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