@allratestoday/mcp-server 0.3.0 → 0.3.2

package/README.md

@@ -1,52 +1,113 @@
 # AllRatesToday MCP Server
 
+[![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)
+[![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-1.x-blue.svg?style=flat-square)](https://modelcontextprotocol.io)
+
 English | [简体中文](./README-zh-CN.md)
 
-MCP server that gives AI coding tools — **Claude Code**, **Cursor**, **Claude Desktop**, and any other Model Context Protocol client — real-time currency exchange rates, historical data, and financial news from [AllRatesToday](https://allratestoday.com).
+> Give your AI coding assistant a live window into the foreign-exchange market.
+
+A Model Context Protocol server that lets **Claude Code**, **Cursor**, **Claude Desktop**, **Windsurf**, and any other MCP-compatible client fetch real-time currency rates, historical data, and multi-currency lookups from the [AllRatesToday API](https://allratestoday.com).
 
-Ask your assistant things like:
+After installation, your assistant can answer questions like:
 
 - *"What's the current USD to EUR rate?"*
-- *"Show me the GBP/JPY rate over the last 30 days."*
-- *"Convert 250 USD into CAD using a real rate."*
+- *"Show me how GBP/JPY moved over the last 30 days."*
+- *"Convert 250 USD into CAD at a real rate."*
+- *"Compare USD against EUR, GBP, and JPY simultaneously."*
 - *"List every supported currency."*
 
-## Get an API key first (required)
+---
+
+## Table of contents
+
+- [What you get](#what-you-get)
+- [Get an API key (required)](#get-an-api-key-required)
+- [Install](#install)
+- [Quick setup per client](#quick-setup-per-client)
+  - [Claude Code](#claude-code)
+  - [Cursor](#cursor)
+  - [Claude Desktop](#claude-desktop)
+  - [Windsurf](#windsurf)
+  - [Generic stdio MCP client](#generic-stdio-mcp-client)
+- [Verify it works](#verify-it-works)
+- [Tools reference](#tools-reference)
+- [Environment variables](#environment-variables)
+- [Plans and limits](#plans-and-limits)
+- [Troubleshooting](#troubleshooting)
+- [Error reference](#error-reference)
+- [FAQ](#faq)
+- [Development](#development)
+- [Changelog](#changelog)
+- [Support](#support)
+- [License](#license)
+
+---
+
+## What you get
+
+| Capability | Detail |
+|---|---|
+| **Currencies** | 150+ ISO 4217 codes, all major and most exotics |
+| **Update frequency** | Mid-market rates refresh every ~60 seconds |
+| **Data source** | Tier-1 financial data providers (Reuters / Refinitiv-class) |
+| **Historical depth** | Up to 1 year via `1d` / `7d` / `30d` / `1y` granularity |
+| **Tools exposed** | 4 — `get_exchange_rate`, `get_historical_rates`, `get_rates_authenticated`, `list_currencies` |
+| **Transport** | stdio (subprocess), MCP 1.x compatible |
+| **Runtime** | Node.js ≥18 |
+
+---
+
+## Get an API key (required)
 
-The MCP server needs an AllRatesToday API key to start. **The free plan is enough** — 300 requests/month, no card required.
+The server **will not start** without a valid `ALLRATES_API_KEY`. The free plan is enough for development and personal use — **300 requests/month, no credit card**.
 
-1. Register at [allratestoday.com/register](https://allratestoday.com/register) — takes 30 seconds
+1. Register at [allratestoday.com/register](https://allratestoday.com/register) — 30 seconds
 2. Verify your email
-3. Copy your key from the dashboard — it looks like `art_live_xxxxx`
-4. Set it as `ALLRATES_API_KEY` in your MCP client config (examples below)
+3. Copy your key from the dashboard (format: `art_live_xxxxx`)
+4. Use it as `ALLRATES_API_KEY` in the configs below
 
-The server will refuse to start without a key and print registration instructions in the console.
+If you forget, the server prints clear registration instructions on stderr and exits with code 1.
+
+---
 
 ## Install
 
+The server is published as an npm package. The simplest install is **zero-install via `npx`**, which is what every config below uses.
+
 ```bash
+# Run without installing (recommended)
+npx -y @allratestoday/mcp-server
+
+# Or install globally
 npm install -g @allratestoday/mcp-server
+allratestoday-mcp
 ```
 
-Or run without installing via `npx @allratestoday/mcp-server`.
+Both commands launch the stdio MCP server and wait for a client to connect. They're not meant to be run directly from your shell — your MCP client launches them as a subprocess.
 
-## Quick setup
+---
 
-### Claude Code
+## Quick setup per client
 
-```bash
-claude mcp add allratestoday -- npx -y @allratestoday/mcp-server
-```
+Each client reads MCP servers from a different config file. Pick yours below.
 
-Then set your API key:
+### Claude Code
+
+The fastest path uses the built-in CLI:
 
 ```bash
+claude mcp add allratestoday -- npx -y @allratestoday/mcp-server
 claude mcp env allratestoday ALLRATES_API_KEY=art_live_xxxxx
 ```
 
+Restart Claude Code. Verify by asking it: *"What's the current USD to EUR rate?"*
+
 ### Cursor
 
-Edit `~/.cursor/mcp.json` (or your project `.cursor/mcp.json`):
+Edit `~/.cursor/mcp.json` (or `.cursor/mcp.json` inside your project for project-scoped servers):
 
 ```json
 {
@@ -62,9 +123,17 @@ Edit `~/.cursor/mcp.json` (or your project `.cursor/mcp.json`):
 }
 ```
 
+Restart Cursor. The four tools should appear in the MCP tool picker.
+
 ### Claude Desktop
 
-Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+Edit the config file (path depends on OS):
+
+| OS | Path |
+|---|---|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
 
 ```json
 {
@@ -80,40 +149,333 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
 }
 ```
 
-Restart the app after editing.
+**Fully quit and reopen Claude Desktop** (Cmd+Q on macOS, right-click tray icon → Exit on Windows). Closing the window alone keeps the old config loaded.
+
+### Windsurf
 
-## Plans
+Edit `~/.codeium/windsurf/mcp_config.json`:
 
-The free plan includes 300 requests/month. Paid plans start at €4.99/mo for higher limits and historical data going back years. See [allratestoday.com/pricing](https://allratestoday.com/pricing).
+```json
+{
+  "mcpServers": {
+    "allratestoday": {
+      "command": "npx",
+      "args": ["-y", "@allratestoday/mcp-server"],
+      "env": {
+        "ALLRATES_API_KEY": "art_live_xxxxx"
+      }
+    }
+  }
+}
+```
+
+Restart Windsurf.
+
+### Generic stdio MCP client
+
+Any MCP host that supports stdio transport works. The launch command is:
+
+```
+npx -y @allratestoday/mcp-server
+```
 
-## Tools exposed
+…with the environment variable `ALLRATES_API_KEY` set. The protocol version is MCP 1.x.
 
-All four tools require an `ALLRATES_API_KEY`.
+---
 
-| Tool | Description |
+## Verify it works
+
+After configuring your client, test in this order:
+
+1. **Server starts** — open the client. If the MCP integration shows a red dot or "failed to connect", the API key is missing or wrong (see [Troubleshooting](#troubleshooting)).
+
+2. **Tools are listed** — most clients have a "tools" or "MCP" panel. You should see:
+   - `get_exchange_rate`
+   - `get_historical_rates`
+   - `get_rates_authenticated`
+   - `list_currencies`
+
+3. **A live call returns a number** — ask the assistant:
+
+   > *What's the current USD to EUR rate?*
+
+   The assistant will call `get_exchange_rate(source: "USD", target: "EUR")` and reply with a real rate (e.g. `"USD to EUR is currently 0.9214."`). If it fabricates a number without making a tool call, the server isn't connected.
+
+---
+
+## Tools reference
+
+All four tools require `ALLRATES_API_KEY`.
+
+### `get_exchange_rate`
+
+Current mid-market rate between two currencies.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `source` | string | yes | 3-letter ISO 4217 code, e.g. `USD` |
+| `target` | string | yes | 3-letter ISO 4217 code, e.g. `EUR` |
+
+**Example call**
+
+```json
+{ "source": "USD", "target": "EUR" }
+```
+
+**Example response**
+
+```json
+{ "rate": 0.92145, "source": "wise" }
+```
+
+### `get_historical_rates`
+
+Time-series data points for a currency pair over a fixed period.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `source` | string | yes | Source currency code |
+| `target` | string | yes | Target currency code |
+| `period` | string | no (default `7d`) | One of `1d`, `7d`, `30d`, `1y` |
+
+**Granularity by period**
+
+| `period` | Data points |
 |---|---|
-| `get_exchange_rate` | Current mid-market rate between two currencies. |
-| `get_historical_rates` | Historical data points over `1d`, `7d`, `30d`, or `1y`. |
-| `get_rates_authenticated` | Multi-target rates and higher limits. |
-| `list_currencies` | All supported currencies with codes, names, symbols. |
+| `1d` | Hourly (24 points) |
+| `7d` | Daily (7 points) |
+| `30d` | Daily (30 points) |
+| `1y` | Weekly (52 points) |
+
+**Example call**
+
+```json
+{ "source": "USD", "target": "INR", "period": "30d" }
+```
+
+**Example response (truncated)**
+
+```json
+{
+  "source": "USD",
+  "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 },
+    "..."
+  ]
+}
+```
+
+### `get_rates_authenticated`
+
+Multiple targets in one call, with optional historical timestamp or grouping window.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `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 |
+| `group` | string | no | One of `hour`, `day`, `week`, `month` |
+
+**Example call**
+
+```json
+{ "source": "USD", "target": "EUR,GBP,JPY" }
+```
+
+**Example 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" }
+]
+```
+
+### `list_currencies`
+
+All supported currencies with codes, names, and symbols. Cached upstream for 24 hours.
+
+**Input** — none.
+
+**Example response (truncated)**
+
+```json
+{
+  "currencies": [
+    { "code": "USD", "name": "US Dollar", "symbol": "$" },
+    { "code": "EUR", "name": "Euro", "symbol": "€" },
+    { "code": "GBP", "name": "British Pound", "symbol": "£" },
+    "..."
+  ],
+  "count": 162
+}
+```
+
+---
 
 ## Environment variables
 
-| Variable | Default | Purpose |
+| Variable | Default | Required | Purpose |
+|---|---|---|---|
+| `ALLRATES_API_KEY` | — | **yes** | Your API key. The server exits at startup if unset. |
+| `ALLRATES_BASE_URL` | `https://allratestoday.com/api` | no | Override for self-hosted or staging deployments. |
+
+You 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 and limits
+
+| Plan | Monthly requests | Price |
+|---|---|---|
+| **Free** | 300 | €0 |
+| **Small** | 5,000 | €4.99/mo |
+| **Medium** | 10,000 | €9.99/mo |
+| **Large** | 100,000 | €49.99/mo |
+
+Full pricing at [allratestoday.com/pricing](https://allratestoday.com/pricing). All plans include the same currency coverage and historical depth — only the request quotas differ.
+
+---
+
+## Troubleshooting
+
+| 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 |
+| Tools show but 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" | Free-tier 300 req/month 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 |
+| Server starts but tools never appear in client | 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 — this is normal when run from a shell | Don't run from a shell; let your MCP client launch it |
+
+### Inspect server logs
+
+To see what the server is doing, run it manually with the API key set:
+
+```bash
+ALLRATES_API_KEY=art_live_xxxxx npx -y @allratestoday/mcp-server
+```
+
+You should see no output when healthy (stdio is reserved for the MCP protocol). Any errors print to stderr.
+
+---
+
+## Error reference
+
+The server maps API errors to clear, actionable messages.
+
+| HTTP status | Meaning | Tool error message |
 |---|---|---|
-| `ALLRATES_API_KEY` | *(required)* | Your AllRatesToday API key. Server will not start without it. |
-| `ALLRATES_BASE_URL` | `https://allratestoday.com/api` | Override for self-hosted or staging environments. |
+| 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` |
+| 429 | Quota exceeded | `AllRatesToday API quota exceeded` |
+| 5xx | Server-side issue at allratestoday.com | `HTTP 5xx — <upstream message>` |
+
+The LLM will surface these messages in its response, so a user prompt that hits a 429 results in the assistant saying *"the API quota has been exceeded — please try again next month or upgrade your plan."*
+
+---
+
+## FAQ
+
+**Is the free plan really enough for normal use?**
+Yes for personal/dev use. 300 requests/month covers ~10 questions per day. Heavy interactive use, multiple chat sessions per day, or running the server in production should consider the paid tiers.
+
+**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, sheet contents, or anything else.
+
+**What happens to my API key?**
+It's only sent as a `Bearer` token in the `Authorization` header on requests to the AllRatesToday API. It's never logged or transmitted elsewhere.
+
+**Why is my historical request slow on first call?**
+Cold-start of `npx` (first run downloads the package) plus the initial AllRatesToday cache miss. Subsequent calls are fast (<200ms typically).
+
+**Can I run this without npm/Node?**
+Not currently — Node ≥18 is required. We've considered a standalone binary; if that matters to you, open an issue.
+
+**Is there a self-hosted option?**
+Yes, set `ALLRATES_BASE_URL` to your own AllRatesToday instance. Contact support@allratestoday.com for self-hosted licensing.
+
+**Does this work with ChatGPT?**
+The Anthropic MCP standard works with any MCP-compatible client. ChatGPT Desktop has experimental MCP support; check OpenAI's docs for current status.
+
+---
 
 ## Development
 
 ```bash
-git clone https://github.com/cahthuranag/mcp-server.git
-cd mcp-server
+git clone https://github.com/cahthuranag/realtime-exchange-rate-mcp.git
+cd realtime-exchange-rate-mcp
 npm install
 npm run build
-node dist/index.js    # server runs on stdio — hit Ctrl+C to exit
+ALLRATES_API_KEY=art_live_xxxxx node dist/index.js
+```
+
+The server runs on stdio and waits for an MCP client to connect. Hit Ctrl+C to exit.
+
+To watch and rebuild on changes during development:
+
+```bash
+npm run dev
 ```
 
+To test against a local AllRatesToday instance:
+
+```bash
+ALLRATES_BASE_URL=http://localhost:8080/api ALLRATES_API_KEY=test_key node dist/index.js
+```
+
+### Project structure
+
+```
+src/
+├── index.ts      # MCP server, tool registration, request handlers
+└── client.ts     # HTTP client for AllRatesToday API + error mapping
+dist/             # Compiled JS (gitignored)
+server.json       # MCP registry manifest
+package.json      # npm metadata, dependencies, scripts
+```
+
+### Contributing
+
+Issues and PRs welcome at [github.com/cahthuranag/realtime-exchange-rate-mcp](https://github.com/cahthuranag/realtime-exchange-rate-mcp). Before opening a PR:
+
+1. `npm run build` should succeed with no errors
+2. Test against a real AllRatesToday API key (set in `ALLRATES_API_KEY`)
+3. Update tool descriptions in `src/index.ts` if you change tool behavior
+4. Update this README's "Tools reference" section if you add or rename a tool
+
+---
+
+## Changelog
+
+See [GitHub Releases](https://github.com/cahthuranag/realtime-exchange-rate-mcp/releases) for the full list. Recent highlights:
+
+- **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`
+- **0.1.x** — Initial release with 5 tools
+
+---
+
+## Support
+
+- **API issues**: [support@allratestoday.com](mailto:support@allratestoday.com)
+- **Bug reports**: [github.com/cahthuranag/realtime-exchange-rate-mcp/issues](https://github.com/cahthuranag/realtime-exchange-rate-mcp/issues)
+- **MCP questions**: [modelcontextprotocol.io](https://modelcontextprotocol.io) — protocol docs
+- **Status / uptime**: [allratestoday.com](https://allratestoday.com) (status page in development)
+
+---
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/dist/client.js

@@ -1,5 +1,5 @@
 const DEFAULT_BASE_URL = 'https://allratestoday.com/api';
-const USER_AGENT = `allratestoday-mcp/0.3.0`;
+const USER_AGENT = `allratestoday-mcp/0.3.1`;
 export class AllRatesTodayError extends Error {
     status;
     body;

package/dist/index.js

@@ -102,7 +102,7 @@ async function main() {
         apiKey,
         baseUrl: process.env.ALLRATES_BASE_URL,
     });
-    const server = new Server({ name: 'allratestoday-mcp', version: '0.3.0' }, { capabilities: { tools: {} } });
+    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;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@allratestoday/mcp-server",
-  "version": "0.3.0",
-  "mcpName": "io.github.cahthuranag/mcp-server",
+  "version": "0.3.2",
+  "mcpName": "io.github.cahthuranag/realtime-exchange-rate-mcp",
   "description": "MCP server for AllRatesToday — let AI coding tools (Claude Code, Cursor, Claude Desktop) fetch real-time and historical currency exchange rates.",
   "keywords": [
     "mcp",
@@ -17,9 +17,9 @@
   "homepage": "https://allratestoday.com",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cahthuranag/mcp-server.git"
+    "url": "git+https://github.com/cahthuranag/realtime-exchange-rate-mcp.git"
   },
-  "bugs": "https://github.com/cahthuranag/mcp-server/issues",
+  "bugs": "https://github.com/cahthuranag/realtime-exchange-rate-mcp/issues",
   "type": "module",
   "main": "dist/index.js",
   "bin": {