@allratestoday/mcp-server 0.3.4 → 0.4.0

package/README.md

@@ -1,5 +1,7 @@
 # AllRatesToday MCP Server
 
+[![Powered by AllRatesToday](https://img.shields.io/badge/Powered%20by-AllRatesToday-orange.svg)](https://allratestoday.com)
+
 [![npm version](https://img.shields.io/npm/v/@allratestoday/mcp-server.svg?style=flat-square)](https://www.npmjs.com/package/@allratestoday/mcp-server)
 [![npm downloads](https://img.shields.io/npm/dm/@allratestoday/mcp-server.svg?style=flat-square)](https://www.npmjs.com/package/@allratestoday/mcp-server)
 [![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](./LICENSE)

package/dist/client.js

@@ -1,5 +1,5 @@
+import { VERSION } from './version.js';
 const DEFAULT_BASE_URL = 'https://allratestoday.com/api';
-const USER_AGENT = `allratestoday-mcp/0.3.1`;
 export class AllRatesTodayError extends Error {
     status;
     body;
@@ -10,6 +10,18 @@ export class AllRatesTodayError extends Error {
         this.name = 'AllRatesTodayError';
     }
 }
+function errorMessage(status, upstream) {
+    switch (status) {
+        case 400:
+            return upstream ?? 'Bad request — possibly an unknown currency code';
+        case 401:
+            return 'Invalid AllRatesToday API key';
+        case 429:
+            return 'AllRatesToday API quota exceeded';
+        default:
+            return upstream ? `HTTP ${status} — ${upstream}` : `HTTP ${status}`;
+    }
+}
 export class AllRatesTodayClient {
     apiKey;
     baseUrl;
@@ -25,14 +37,14 @@ export class AllRatesTodayClient {
             if (value !== undefined && value !== '')
                 url.searchParams.set(key, value);
         }
-        const headers = {
-            'Accept': 'application/json',
-            'User-Agent': USER_AGENT,
-        };
         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.');
         }
-        headers['Authorization'] = `Bearer ${this.apiKey}`;
+        const headers = {
+            'Accept': 'application/json',
+            'User-Agent': `allratestoday-mcp/${VERSION}`,
+            'Authorization': `Bearer ${this.apiKey}`,
+        };
         const res = await this.fetchImpl(url.toString(), { method: 'GET', headers });
         const text = await res.text();
         let body;
@@ -43,10 +55,10 @@ export class AllRatesTodayClient {
             body = text;
         }
         if (!res.ok) {
-            const msg = (body && typeof body === 'object' && 'error' in body && typeof body.error === 'string'
+            const upstream = body && typeof body === 'object' && 'error' in body && typeof body.error === 'string'
                 ? body.error
-                : `HTTP ${res.status}`);
-            throw new AllRatesTodayError(msg, res.status, body);
+                : undefined;
+            throw new AllRatesTodayError(errorMessage(res.status, upstream), res.status, body);
         }
         return body;
     }

package/dist/index.js

@@ -1,82 +1,32 @@
 #!/usr/bin/env node
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
 import { AllRatesTodayClient, AllRatesTodayError } from './client.js';
-const CCY = {
-    type: 'string',
-    description: 'ISO 4217 currency code (e.g. USD, EUR, GBP).',
-    minLength: 3,
-    maxLength: 3,
-};
-const tools = [
-    {
-        name: 'get_exchange_rate',
-        description: 'Get the current mid-market exchange rate between two currencies. Returns a single rate number. Requires a free AllRatesToday API key (ALLRATES_API_KEY) — sign up at https://allratestoday.com/register.',
-        inputSchema: {
-            type: 'object',
-            additionalProperties: false,
-            properties: {
-                source: CCY,
-                target: CCY,
-            },
-            required: ['source', 'target'],
-        },
-    },
-    {
-        name: 'get_historical_rates',
-        description: 'Get historical exchange-rate data points for a currency pair over a period. Periods: 1d (hourly), 7d (daily), 30d (daily), 1y (weekly). Requires an AllRatesToday API key (ALLRATES_API_KEY).',
-        inputSchema: {
-            type: 'object',
-            additionalProperties: false,
-            properties: {
-                source: CCY,
-                target: CCY,
-                period: {
-                    type: 'string',
-                    enum: ['1d', '7d', '30d', '1y'],
-                    default: '7d',
-                    description: 'Time period to fetch history for.',
-                },
-            },
-            required: ['source', 'target'],
-        },
-    },
-    {
-        name: 'get_rates_authenticated',
-        description: 'Get rates with higher limits and multi-target support. Requires an AllRatesToday API key (ALLRATES_API_KEY). Supports comma-separated targets like "EUR,GBP,JPY".',
-        inputSchema: {
-            type: 'object',
-            additionalProperties: false,
-            properties: {
-                source: CCY,
-                target: {
-                    type: 'string',
-                    description: 'One or more target codes, comma-separated.',
-                },
-                time: {
-                    type: 'string',
-                    format: 'date-time',
-                    description: 'Optional historical ISO 8601 timestamp.',
-                },
-                group: {
-                    type: 'string',
-                    enum: ['hour', 'day', 'week', 'month'],
-                    description: 'Optional grouping window.',
-                },
-            },
-            required: ['source', 'target'],
-        },
-    },
-    {
-        name: 'list_currencies',
-        description: 'List all supported currencies with code, name, and symbol. Requires a free AllRatesToday API key (ALLRATES_API_KEY) — sign up at https://allratestoday.com/register. Cached 24h upstream.',
-        inputSchema: { type: 'object', additionalProperties: false, properties: {} },
-    },
-];
-function text(s) {
-    const out = typeof s === 'string' ? s : JSON.stringify(s, null, 2);
-    return { content: [{ type: 'text', text: out }] };
+import { VERSION } from './version.js';
+const CCY_DESC = "ISO 4217 currency code, 3 letters, case-insensitive (e.g. 'USD', 'EUR', 'GBP', 'JPY'). For a source/target pair, the returned rate is how much 1 unit of source is worth in target. Fiat only — no crypto, no commodities. Call list_currencies if unsure whether a code is supported.";
+const ccy = z
+    .string()
+    .regex(/^[A-Za-z]{3}$/, 'must be a 3-letter ISO 4217 currency code')
+    .describe(CCY_DESC);
+const ccyList = z
+    .string()
+    .regex(/^[A-Za-z]{3}(,[A-Za-z]{3})*$/, 'must be one or more 3-letter ISO 4217 codes, comma-separated, no spaces')
+    .describe("One or more ISO 4217 codes, comma-separated, no spaces, case-insensitive. Examples: 'EUR' (single) or 'EUR,GBP,JPY' (multi). Each target becomes a separate row in the response.");
+const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+function ok(structured) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+        structuredContent: structured,
+    };
+}
+function fail(err) {
+    const message = err instanceof AllRatesTodayError
+        ? `AllRatesToday error${err.status ? ` (${err.status})` : ''}: ${err.message}`
+        : err instanceof Error
+            ? err.message
+            : String(err);
+    return { content: [{ type: 'text', text: message }], isError: true };
 }
 async function main() {
     const apiKey = process.env.ALLRATES_API_KEY;
@@ -85,7 +35,7 @@ async function main() {
             '',
             '  AllRatesToday MCP server requires an API key.',
             '',
-            '  1. Sign up free at https://allratestoday.com/register (300 requests/month, no card required)',
+            '  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:',
             '',
@@ -102,45 +52,119 @@ async function main() {
         apiKey,
         baseUrl: process.env.ALLRATES_BASE_URL,
     });
-    const server = new Server({ name: 'allratestoday-mcp', version: '0.3.1' }, { capabilities: { tools: {} } });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
-    server.setRequestHandler(CallToolRequestSchema, async (req) => {
-        const { name, arguments: args = {} } = req.params;
+    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.",
+        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'),
+        },
+        annotations: READ_ONLY,
+    }, async ({ source, target }) => {
+        try {
+            return ok(await client.getRate(source.toUpperCase(), target.toUpperCase()));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    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.",
+        inputSchema: {
+            source: ccy,
+            target: ccy,
+            period: z
+                .enum(['1d', '7d', '30d', '1y'])
+                .default('7d')
+                .describe("Lookback window ending NOW. '1d' returns ~24 hourly points, '7d' returns 7 daily points, '30d' returns 30 daily points, '1y' returns ~52 weekly points. Defaults to '7d' if omitted."),
+        },
+        outputSchema: {
+            source: z.string(),
+            target: z.string(),
+            period: z.string(),
+            source_api: z.string().optional().describe('Upstream data provider'),
+            data: z.array(z.object({
+                date: z.string(),
+                rate: z.number(),
+                timestamp: z.number(),
+            })),
+        },
+        annotations: READ_ONLY,
+    }, async ({ source, target, period }) => {
+        try {
+            return ok(await client.getHistoricalRates(source.toUpperCase(), target.toUpperCase(), period));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    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.",
+        inputSchema: {
+            source: ccy,
+            target: ccyList,
+            time: z
+                .string()
+                .datetime({ offset: true })
+                .optional()
+                .describe("Single point-in-time ISO 8601 UTC timestamp (e.g. '2025-03-14T12:00:00Z'). Omit for the latest rate."),
+            group: z
+                .enum(['hour', 'day', 'week', 'month'])
+                .optional()
+                .describe("Aggregation bucket: 'hour', 'day', 'week', or 'month'. Useful when time is omitted to return rolling averages. Omit for raw single-point output."),
+        },
+        outputSchema: {
+            rates: z.array(z.object({
+                rate: z.number(),
+                source: z.string(),
+                target: z.string(),
+                time: z.string(),
+            })),
+        },
+        annotations: READ_ONLY,
+    }, async ({ source, target, time, group }) => {
+        try {
+            const rates = await client.getAuthenticatedRates({
+                source: source.toUpperCase(),
+                target: target.toUpperCase(),
+                time,
+                group,
+            });
+            return ok({ rates });
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    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.",
+        inputSchema: {},
+        outputSchema: {
+            currencies: z.array(z.object({
+                code: z.string(),
+                name: z.string(),
+                symbol: z.string(),
+            })),
+            count: z.number(),
+        },
+        annotations: READ_ONLY,
+    }, async () => {
         try {
-            switch (name) {
-                case 'get_exchange_rate': {
-                    const { source, target } = args;
-                    return text(await client.getRate(source, target));
-                }
-                case 'get_historical_rates': {
-                    const { source, target, period = '7d' } = args;
-                    return text(await client.getHistoricalRates(source, target, period));
-                }
-                case 'get_rates_authenticated': {
-                    return text(await client.getAuthenticatedRates(args));
-                }
-                case 'list_currencies': {
-                    return text(await client.listSymbols());
-                }
-                default:
-                    return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
-            }
+            return ok(await client.listSymbols());
         }
         catch (err) {
-            const message = err instanceof AllRatesTodayError
-                ? `AllRatesToday error${err.status ? ` (${err.status})` : ''}: ${err.message}`
-                : err instanceof Error
-                    ? err.message
-                    : String(err);
-            return { content: [{ type: 'text', text: message }], isError: true };
+            return fail(err);
         }
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    // Keep process alive; stdio transport handles shutdown.
 }
 main().catch((err) => {
-    // eslint-disable-next-line no-console
     console.error('Fatal:', err);
     process.exit(1);
 });

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,3 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+export const VERSION = require('../package.json').version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allratestoday/mcp-server",
-  "version": "0.3.4",
+  "version": "0.4.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": [
@@ -35,12 +35,13 @@
   },
   "scripts": {
     "build": "tsc",
+    "test": "node --test test/*.test.mjs",
     "prepublishOnly": "npm run build",
     "start": "node dist/index.js",
     "dev": "tsc --watch"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {