@allratestoday/mcp-server 0.4.1 → 0.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +74 -165
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,17 +1,14 @@
1
- # AllRatesToday MCP Server
1
+ # AllRatesToday MCP Server — @allratestoday/mcp-server
2
2
 
3
- [![Powered by AllRatesToday](https://img.shields.io/badge/Powered%20by-AllRatesToday-orange.svg)](https://allratestoday.com)
4
-
5
- [![npm version](https://img.shields.io/npm/v/@allratestoday/mcp-server.svg?style=flat-square)](https://www.npmjs.com/package/@allratestoday/mcp-server)
6
- [![npm downloads](https://img.shields.io/npm/dm/@allratestoday/mcp-server.svg?style=flat-square)](https://www.npmjs.com/package/@allratestoday/mcp-server)
7
- [![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](./LICENSE)
8
- [![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-1.x-blue.svg?style=flat-square)](https://modelcontextprotocol.io)
3
+ [![npm version](https://img.shields.io/npm/v/@allratestoday/mcp-server.svg)](https://www.npmjs.com/package/@allratestoday/mcp-server)
4
+ [![npm downloads](https://img.shields.io/npm/dm/@allratestoday/mcp-server.svg)](https://www.npmjs.com/package/@allratestoday/mcp-server)
5
+ [![license](https://img.shields.io/npm/l/@allratestoday/mcp-server.svg)](./LICENSE)
6
+ [![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-1.x-blue.svg)](https://modelcontextprotocol.io)
7
+ [![TypeScript](https://img.shields.io/badge/TypeScript-3178C6.svg)](https://www.typescriptlang.org/)
9
8
 
10
9
  English | [简体中文](./README-zh-CN.md)
11
10
 
12
- > Give your AI coding assistant a live window into the foreign-exchange market.
13
-
14
- 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).
11
+ **Give your AI assistant a live window into the foreign-exchange market. A Model Context Protocol server that lets Claude Code, Cursor, Claude Desktop, Windsurf, and any MCP-compatible client fetch real-time currency rates, historical series, and multi-currency lookups from the [AllRatesToday API](https://allratestoday.com).**
15
12
 
16
13
  After installation, your assistant can answer questions like:
17
14
 
@@ -19,50 +16,21 @@ After installation, your assistant can answer questions like:
19
16
  - *"Show me how GBP/JPY moved over the last 30 days."*
20
17
  - *"Convert 250 USD into CAD at a real rate."*
21
18
  - *"Compare USD against EUR, GBP, and JPY simultaneously."*
22
- - *"List every supported currency."*
23
-
24
- ---
25
19
 
26
- ## Table of contents
27
-
28
- - [What you get](#what-you-get)
29
- - [Get an API key (required)](#get-an-api-key-required)
30
- - [Install](#install)
31
- - [Quick setup per client](#quick-setup-per-client)
32
- - [Claude Code](#claude-code)
33
- - [Cursor](#cursor)
34
- - [Claude Desktop](#claude-desktop)
35
- - [Windsurf](#windsurf)
36
- - [Generic stdio MCP client](#generic-stdio-mcp-client)
37
- - [Verify it works](#verify-it-works)
38
- - [Tools reference](#tools-reference)
39
- - [Environment variables](#environment-variables)
40
- - [Plans and limits](#plans-and-limits)
41
- - [Troubleshooting](#troubleshooting)
42
- - [Error reference](#error-reference)
43
- - [FAQ](#faq)
44
- - [Development](#development)
45
- - [Changelog](#changelog)
46
- - [Support](#support)
47
- - [License](#license)
20
+ ## 🚀 Why this server?
48
21
 
49
- ---
50
-
51
- ## What you get
22
+ - 📡 **Live mid-market rates** — 150+ ISO 4217 currencies, refreshed every ~60 seconds from institutional interbank data
23
+ - 📈 **Historical series built in** — `1d` / `7d` / `30d` / `1y` windows with sensible granularity per period
24
+ - 🧰 **Four focused tools** — `get_exchange_rate`, `get_historical_rates`, `get_rates_authenticated`, `list_currencies`; small surface, easy for the model to use correctly
25
+ - 🔌 **Works everywhere MCP does** — stdio transport, MCP 1.x; Claude Code, Cursor, Claude Desktop, Windsurf, or any generic host
26
+ - 🛡️ **Fail-fast and honest** — refuses to start without a key, maps API errors to clear actionable messages the assistant can relay
27
+ - 🔒 **Nothing leaks** — only the request parameters and your API key ever reach allratestoday.com; never conversation context
52
28
 
53
- | Capability | Detail |
54
- |---|---|
55
- | **Currencies** | 150+ ISO 4217 codes, all major and most exotics |
56
- | **Update frequency** | Mid-market rates refresh every ~60 seconds |
57
- | **Data source** | Tier-1 financial data providers (Reuters / Refinitiv-class) |
58
- | **Historical depth** | Up to 1 year via `1d` / `7d` / `30d` / `1y` granularity |
59
- | **Tools exposed** | 4 — `get_exchange_rate`, `get_historical_rates`, `get_rates_authenticated`, `list_currencies` |
60
- | **Transport** | stdio (subprocess), MCP 1.x compatible |
61
- | **Runtime** | Node.js ≥18 |
29
+ ## ⚖️ Mid-market vs official central-bank rates
62
30
 
63
- ---
31
+ 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** (47 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.
64
32
 
65
- ## Get an API key (required)
33
+ ## 🔑 Get your API key
66
34
 
67
35
  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**.
68
36
 
@@ -71,28 +39,26 @@ The server **will not start** without a valid `ALLRATES_API_KEY`. A free key is
71
39
  3. Copy your key from the dashboard (format: `art_live_xxxxx`)
72
40
  4. Use it as `ALLRATES_API_KEY` in the configs below
73
41
 
74
- If you forget, the server prints clear registration instructions on stderr and exits with code 1.
42
+ If you forget, the server prints registration instructions on stderr and exits with code 1.
75
43
 
76
- ---
77
-
78
- ## Install
44
+ ## 📦 Installation
79
45
 
80
- The server is published as an npm package. The simplest install is **zero-install via `npx`**, which is what every config below uses.
46
+ The simplest install is **zero-install via `npx`**, which is what every config below uses:
81
47
 
82
48
  ```bash
83
49
  # Run without installing (recommended)
84
50
  npx -y @allratestoday/mcp-server
51
+ ```
85
52
 
53
+ ```bash
86
54
  # Or install globally
87
55
  npm install -g @allratestoday/mcp-server
88
56
  allratestoday-mcp
89
57
  ```
90
58
 
91
- 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.
59
+ Both commands launch the stdio MCP server and wait for a client to connect — they're not meant to be run interactively from your shell; your MCP client launches them as a subprocess.
92
60
 
93
- ---
94
-
95
- ## Quick setup per client
61
+ ## 🏁 Quick setup per client
96
62
 
97
63
  Each client reads MCP servers from a different config file. Pick yours below.
98
64
 
@@ -155,23 +121,7 @@ Edit the config file (path depends on OS):
155
121
 
156
122
  ### Windsurf
157
123
 
158
- Edit `~/.codeium/windsurf/mcp_config.json`:
159
-
160
- ```json
161
- {
162
- "mcpServers": {
163
- "allratestoday": {
164
- "command": "npx",
165
- "args": ["-y", "@allratestoday/mcp-server"],
166
- "env": {
167
- "ALLRATES_API_KEY": "art_live_xxxxx"
168
- }
169
- }
170
- }
171
- }
172
- ```
173
-
174
- Restart Windsurf.
124
+ Edit `~/.codeium/windsurf/mcp_config.json` with the same `mcpServers` block as above, then restart Windsurf.
175
125
 
176
126
  ### Generic stdio MCP client
177
127
 
@@ -183,32 +133,25 @@ npx -y @allratestoday/mcp-server
183
133
 
184
134
  …with the environment variable `ALLRATES_API_KEY` set. The protocol version is MCP 1.x.
185
135
 
186
- ---
187
-
188
- ## Verify it works
136
+ ## ✅ Verify it works
189
137
 
190
138
  After configuring your client, test in this order:
191
139
 
192
- 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)).
140
+ 1. **Server starts** — open the client. A red dot or "failed to connect" means the API key is missing or wrong (see Troubleshooting below).
141
+ 2. **Tools are listed** — most clients have a "tools" or "MCP" panel showing the four tools.
142
+ 3. **A live call returns a number** — ask: *"What's the current USD to EUR rate?"* The assistant should call `get_exchange_rate(source: "USD", target: "EUR")` and reply with a real rate. If it fabricates a number without a tool call, the server isn't connected.
193
143
 
194
- 2. **Tools are listed** — most clients have a "tools" or "MCP" panel. You should see:
195
- - `get_exchange_rate`
196
- - `get_historical_rates`
197
- - `get_rates_authenticated`
198
- - `list_currencies`
144
+ ## 📚 Tools reference
199
145
 
200
- 3. **A live call returns a number** — ask the assistant:
146
+ - [`get_exchange_rate`](#get_exchange_rate) current rate for one pair
147
+ - [`get_historical_rates`](#get_historical_rates) — time series over a preset period
148
+ - [`get_rates_authenticated`](#get_rates_authenticated) — multiple targets in one call, optional point-in-time
149
+ - [`list_currencies`](#list_currencies) — all supported currency codes, names, symbols
201
150
 
202
- > *What's the current USD to EUR rate?*
203
-
204
- 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.
151
+ All four tools require `ALLRATES_API_KEY`.
205
152
 
206
153
  ---
207
154
 
208
- ## Tools reference
209
-
210
- All four tools require `ALLRATES_API_KEY`.
211
-
212
155
  ### `get_exchange_rate`
213
156
 
214
157
  Current mid-market rate between two currencies.
@@ -226,7 +169,7 @@ Current mid-market rate between two currencies.
226
169
  { "source": "USD", "target": "EUR" }
227
170
  ```
228
171
 
229
- **Example response**
172
+ **Response:**
230
173
 
231
174
  ```json
232
175
  { "rate": 0.92145, "source": "wise" }
@@ -259,7 +202,7 @@ Time-series data points for a currency pair over a fixed period.
259
202
  { "source": "USD", "target": "INR", "period": "30d" }
260
203
  ```
261
204
 
262
- **Example response (truncated)**
205
+ **Response (truncated):**
263
206
 
264
207
  ```json
265
208
  {
@@ -293,7 +236,7 @@ Multiple targets in one call, with optional historical timestamp or grouping win
293
236
  { "source": "USD", "target": "EUR,GBP,JPY" }
294
237
  ```
295
238
 
296
- **Example response**
239
+ **Response:**
297
240
 
298
241
  ```json
299
242
  [
@@ -305,11 +248,11 @@ Multiple targets in one call, with optional historical timestamp or grouping win
305
248
 
306
249
  ### `list_currencies`
307
250
 
308
- All supported currencies with codes, names, and symbols. Cached upstream for 24 hours.
251
+ All supported currencies with codes, names, and symbols. Cached upstream for 24 hours — cheap to call for validating user input before the other tools.
309
252
 
310
253
  **Input** — none.
311
254
 
312
- **Example response (truncated)**
255
+ **Response (truncated):**
313
256
 
314
257
  ```json
315
258
  {
@@ -325,49 +268,41 @@ All supported currencies with codes, names, and symbols. Cached upstream for 24
325
268
 
326
269
  ---
327
270
 
328
- ## Environment variables
271
+ ## ⚙️ Environment variables
329
272
 
330
273
  | Variable | Default | Required | Purpose |
331
274
  |---|---|---|---|
332
275
  | `ALLRATES_API_KEY` | — | **yes** | Your API key. The server exits at startup if unset. |
333
276
  | `ALLRATES_BASE_URL` | `https://allratestoday.com/api` | no | Override for self-hosted or staging deployments. |
334
277
 
335
- 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.
336
-
337
- ---
278
+ 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.
338
279
 
339
- ## Plans
280
+ ## 💳 Plans
340
281
 
341
- A free tier and paid plans are available. See [allratestoday.com/pricing](https://allratestoday.com/pricing) for current quotas. All plans include the same currency coverage and historical depth only the request quotas differ.
282
+ A free tier and paid plans are available see [allratestoday.com/pricing](https://allratestoday.com/pricing) for current quotas. All plans include the same currency coverage and historical depth; only the request quotas differ.
342
283
 
343
- ---
344
-
345
- ## Troubleshooting
284
+ ## 🛠️ Troubleshooting
346
285
 
347
286
  | Symptom | Likely cause | Fix |
348
287
  |---|---|---|
349
288
  | 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 |
350
- | 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 |
351
- | Tools return "AllRatesToday API quota exceeded" | Free-tier monthly limit hit | Wait until next month or upgrade plan |
289
+ | Every call returns "Invalid AllRatesToday API key" | Key is malformed (missing prefix, truncated, or revoked) | Copy a fresh key from the dashboard |
290
+ | Tools return "AllRatesToday API quota exceeded" | Monthly limit hit | Wait until next month or upgrade plan |
352
291
  | Historical tool returns "Bad request" | Invalid period or unknown currency code | Period must be `1d`/`7d`/`30d`/`1y`; codes must be 3 letters |
353
- | Server starts but tools never appear in client | Client didn't reload after config change | Fully quit (not just close) and reopen the client |
354
- | `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 |
355
-
356
- ### Inspect server logs
292
+ | Server starts but tools never appear | Client didn't reload after config change | Fully quit (not just close) and reopen the client |
293
+ | `npx` runs but hangs forever | The server is waiting for an MCP client to connect — normal when run from a shell | Let your MCP client launch it |
357
294
 
358
- To see what the server is doing, run it manually with the API key set:
295
+ To inspect what the server is doing, run it manually with the key set:
359
296
 
360
297
  ```bash
361
298
  ALLRATES_API_KEY=art_live_xxxxx npx -y @allratestoday/mcp-server
362
299
  ```
363
300
 
364
- You should see no output when healthy (stdio is reserved for the MCP protocol). Any errors print to stderr.
365
-
366
- ---
301
+ No output means healthy (stdio is reserved for the MCP protocol); errors print to stderr.
367
302
 
368
- ## Error reference
303
+ ## 🛡️ Error reference
369
304
 
370
- The server maps API errors to clear, actionable messages.
305
+ The server maps API errors to clear, actionable messages the assistant can relay to the user:
371
306
 
372
307
  | HTTP status | Meaning | Tool error message |
373
308
  |---|---|---|
@@ -377,36 +312,30 @@ The server maps API errors to clear, actionable messages.
377
312
  | 429 | Quota exceeded | `AllRatesToday API quota exceeded` |
378
313
  | 5xx | Server-side issue at allratestoday.com | `HTTP 5xx — <upstream message>` |
379
314
 
380
- 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."*
381
-
382
- ---
383
-
384
- ## FAQ
315
+ ## FAQ
385
316
 
386
317
  **Is the free plan really enough for normal use?**
387
- Yes for personal/dev use. The free tier covers a few daily questions. Heavy interactive use, multiple chat sessions per day, or running the server in production should consider the paid tiers.
318
+ Yes for personal/dev use. Heavy interactive use, multiple chat sessions per day, or production should consider the paid tiers.
388
319
 
389
320
  **Do you store my conversation or query data?**
390
- 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.
321
+ No. Only your API key and the request parameters (source, target, period, time) are sent to allratestoday.com — never the LLM's conversation context.
391
322
 
392
323
  **What happens to my API key?**
393
324
  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.
394
325
 
395
- **Why is my historical request slow on first call?**
396
- Cold-start of `npx` (first run downloads the package) plus the initial AllRatesToday cache miss. Subsequent calls are fast (<200ms typically).
326
+ **Why is my first call slow?**
327
+ Cold-start of `npx` (first run downloads the package) plus the initial cache miss. Subsequent calls are typically <200ms.
397
328
 
398
329
  **Can I run this without npm/Node?**
399
- Not currently — Node ≥18 is required. We've considered a standalone binary; if that matters to you, open an issue.
330
+ Not currently — Node ≥18 is required. If a standalone binary matters to you, open an issue.
400
331
 
401
332
  **Is there a self-hosted option?**
402
- Yes, set `ALLRATES_BASE_URL` to your own AllRatesToday instance. Contact support@allratestoday.com for self-hosted licensing.
333
+ Set `ALLRATES_BASE_URL` to your own AllRatesToday instance. Contact support@allratestoday.com for self-hosted licensing.
403
334
 
404
335
  **Does this work with ChatGPT?**
405
- The Anthropic MCP standard works with any MCP-compatible client. ChatGPT Desktop has experimental MCP support; check OpenAI's docs for current status.
336
+ MCP works with any MCP-compatible client. ChatGPT Desktop has experimental MCP support; check OpenAI's docs for current status.
406
337
 
407
- ---
408
-
409
- ## Development
338
+ ## 👩‍💻 Development
410
339
 
411
340
  ```bash
412
341
  git clone https://github.com/cahthuranag/mcp-server.git
@@ -416,21 +345,13 @@ npm run build
416
345
  ALLRATES_API_KEY=art_live_xxxxx node dist/index.js
417
346
  ```
418
347
 
419
- The server runs on stdio and waits for an MCP client to connect. Hit Ctrl+C to exit.
420
-
421
- To watch and rebuild on changes during development:
422
-
423
- ```bash
424
- npm run dev
425
- ```
426
-
427
- To test against a local AllRatesToday instance:
348
+ The server runs on stdio and waits for an MCP client to connect; Ctrl+C to exit. `npm run dev` watches and rebuilds. To test against a local AllRatesToday instance:
428
349
 
429
350
  ```bash
430
351
  ALLRATES_BASE_URL=http://localhost:8080/api ALLRATES_API_KEY=test_key node dist/index.js
431
352
  ```
432
353
 
433
- ### Project structure
354
+ **Project structure**
434
355
 
435
356
  ```
436
357
  src/
@@ -438,39 +359,27 @@ src/
438
359
  └── client.ts # HTTP client for AllRatesToday API + error mapping
439
360
  dist/ # Compiled JS (gitignored)
440
361
  server.json # MCP registry manifest
441
- package.json # npm metadata, dependencies, scripts
442
362
  ```
443
363
 
444
- ### Contributing
445
-
446
- Issues and PRs welcome at [github.com/cahthuranag/mcp-server](https://github.com/cahthuranag/mcp-server). Before opening a PR:
364
+ **Contributing** — issues and PRs welcome at [github.com/cahthuranag/mcp-server](https://github.com/cahthuranag/mcp-server). Before opening a PR: `npm run build` must succeed, test against a real API key, and update the tool descriptions in `src/index.ts` plus this README's tools reference if you change tool behavior.
447
365
 
448
- 1. `npm run build` should succeed with no errors
449
- 2. Test against a real AllRatesToday API key (set in `ALLRATES_API_KEY`)
450
- 3. Update tool descriptions in `src/index.ts` if you change tool behavior
451
- 4. Update this README's "Tools reference" section if you add or rename a tool
452
-
453
- ---
454
-
455
- ## Changelog
366
+ ## 📝 Changelog
456
367
 
457
368
  See [GitHub Releases](https://github.com/cahthuranag/mcp-server/releases) for the full list. Recent highlights:
458
369
 
370
+ - **0.4.x** — README overhaul; registry metadata updates
459
371
  - **0.3.x** — API key required for all tools; fail-fast at startup with clear error
460
372
  - **0.2.x** — Removed news tool, required auth on `get_historical_rates`
461
373
  - **0.1.x** — Initial release with 5 tools
462
374
 
463
- ---
375
+ ## 🔗 Links
464
376
 
465
- ## Support
466
-
467
- - **API issues**: [support@allratestoday.com](mailto:support@allratestoday.com)
468
- - **Bug reports**: [github.com/cahthuranag/mcp-server/issues](https://github.com/cahthuranag/mcp-server/issues)
469
- - **MCP questions**: [modelcontextprotocol.io](https://modelcontextprotocol.io) — protocol docs
470
- - **Status / uptime**: [allratestoday.com](https://allratestoday.com) (status page in development)
471
-
472
- ---
377
+ - [API documentation](https://allratestoday.com/docs/) · [Interactive reference](https://allratestoday.com/api-reference/)
378
+ - [Register (free)](https://allratestoday.com/register) · [Pricing](https://allratestoday.com/pricing)
379
+ - [MCP protocol docs](https://modelcontextprotocol.io)
380
+ - [GitHub](https://github.com/cahthuranag/mcp-server) · [Bug reports](https://github.com/cahthuranag/mcp-server/issues)
381
+ - Support: [support@allratestoday.com](mailto:support@allratestoday.com)
473
382
 
474
- ## License
383
+ ## 📜 License
475
384
 
476
385
  MIT — see [LICENSE](./LICENSE).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@allratestoday/mcp-server",
3
- "version": "0.4.1",
3
+ "version": "0.4.3",
4
4
  "mcpName": "io.github.cahthuranag/mcp-server",
5
5
  "description": "MCP server for AllRatesToday — let AI coding tools (Claude Code, Cursor, Claude Desktop) fetch real-time and historical currency exchange rates.",
6
6
  "keywords": [