@foreverworks/mcp-ecb 0.0.0-stage → 0.1.1

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 (41) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/LICENSE +21 -0
  3. package/README.md +231 -2
  4. package/dist/app/ports.d.ts +20 -0
  5. package/dist/app/ports.js +2 -0
  6. package/dist/app/usecases/convert.d.ts +37 -0
  7. package/dist/app/usecases/convert.js +47 -0
  8. package/dist/app/usecases/fixings.d.ts +22 -0
  9. package/dist/app/usecases/fixings.js +40 -0
  10. package/dist/app/usecases/rates.d.ts +29 -0
  11. package/dist/app/usecases/rates.js +43 -0
  12. package/dist/app/usecases/series.d.ts +33 -0
  13. package/dist/app/usecases/series.js +65 -0
  14. package/dist/composition.d.ts +12 -0
  15. package/dist/composition.js +13 -0
  16. package/dist/domain/convert.d.ts +16 -0
  17. package/dist/domain/convert.js +29 -0
  18. package/dist/domain/dates.d.ts +6 -0
  19. package/dist/domain/dates.js +18 -0
  20. package/dist/domain/errors.d.ts +29 -0
  21. package/dist/domain/errors.js +19 -0
  22. package/dist/domain/rates.d.ts +35 -0
  23. package/dist/domain/rates.js +41 -0
  24. package/dist/index.d.ts +2 -0
  25. package/dist/index.js +22 -0
  26. package/dist/infra/ecb.d.ts +28 -0
  27. package/dist/infra/ecb.js +67 -0
  28. package/dist/infra/xml.d.ts +2 -0
  29. package/dist/infra/xml.js +47 -0
  30. package/dist/mcp/envelope.d.ts +4 -0
  31. package/dist/mcp/envelope.js +5 -0
  32. package/dist/mcp/outputs.d.ts +55 -0
  33. package/dist/mcp/outputs.js +65 -0
  34. package/dist/mcp/policy.d.ts +3 -0
  35. package/dist/mcp/policy.js +8 -0
  36. package/dist/mcp/register.d.ts +4 -0
  37. package/dist/mcp/register.js +63 -0
  38. package/icons/icon-48.png +0 -0
  39. package/icons/icon-512.png +0 -0
  40. package/icons/icon.svg +1 -0
  41. package/package.json +57 -4
package/CHANGELOG.md ADDED
@@ -0,0 +1,15 @@
1
+ # @foreverworks/mcp-ecb
2
+
3
+ ## 0.1.1
4
+
5
+ ### Patch Changes
6
+
7
+ - Published through npm's trusted publishing: from this version on, each release names GitHub Actions as its publisher, with a provenance statement that ties the package to the commit it was built from.
8
+
9
+ ## 0.1.0
10
+
11
+ The first release. The European Central Bank's euro foreign exchange reference rates: the rate in force on any day since 1999 with the date of the fixing it is, every currency on a day or a window of fixings, and amounts converted between any two currencies, cross rates through the euro included. Rates are the ECB's exact value, and every conversion is computed in exact decimals, rounded once by the rule you name, and answers the rate or rates and the fixing it used. A weekend, a holiday or the hours before the ECB publishes (around 16:00 CET) take the last working day's fixing, and the answer says so.
12
+
13
+ Every tool is `read`, and it needs no account or key. Nothing here moves money: no tool is `money`.
14
+
15
+ It speaks MCP protocol revisions 2026-07-28 and 2025-11-25, over stdio and loopback HTTP, and lists the same tools to both.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Forever Works
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,232 @@
1
- # Temporary Holding Version
1
+ # <img src="icons/icon.svg" width="36" height="36" alt="ECB exchange rates icon"> ECB exchange rates MCP server
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Look up the [European Central Bank](https://www.ecb.europa.eu)'s euro foreign
4
+ exchange reference rates from your AI assistant: the rate in force on any day
5
+ since 1999, with the date of the fixing it is; every currency on a day, or a
6
+ window of fixings; and exact conversions between any two currencies, cross
7
+ rates through the euro included. It only reads: no tool writes or is `money`.
8
+ Rates stay the ECB's exact value (`1.1052`, never `1.105`), and every answer
9
+ says which fixing it used, so a weekend or a holiday is never a silent guess.
10
+
11
+ **You need** nothing: no account and no key. The server reads the ECB's public
12
+ XML files at `www.ecb.europa.eu`. The ECB publishes these rates "for
13
+ information purposes only" and discourages using them for transactions, so a
14
+ bank or a card will not give you exactly this rate; they are the standard
15
+ reference for statements, bookkeeping and comparisons.
16
+
17
+ ## What you can ask
18
+
19
+ - "What was the ECB's euro to dollar rate on 14 March 2025?"
20
+ - "Convert an invoice of 1,250.50 GBP dated 3 October 2025 to US dollars at the
21
+ ECB's rate for that day, and show me the rates you used."
22
+ - "How many euros was 10,000 Hungarian forint worth today?"
23
+ - "Give me the ECB's USD and JPY rates for every working day of September 2025."
24
+ - "Which rate did the ECB publish for the Croatian kuna on its last day?"
25
+
26
+ ## Install
27
+
28
+ <!-- install:begin -->
29
+ [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=ecb&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40foreverworks%2Fmcp-ecb%22%5D%7D) [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_Server-000000?style=flat-square&logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=ecb&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBmb3JldmVyd29ya3MvbWNwLWVjYiJdfQ%3D%3D) [![Download for Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Download_Bundle-D97757?style=flat-square&logo=claude&logoColor=white)](https://github.com/foreverworks/mcps/releases/latest/download/mcp-ecb.mcpb)
30
+
31
+ With Claude Code:
32
+
33
+ ```bash
34
+ claude mcp add ecb -- npx -y @foreverworks/mcp-ecb
35
+ ```
36
+
37
+ Claude Desktop (Settings, Developer, Edit Config) and most other clients read the same command as JSON:
38
+
39
+ ```json
40
+ {
41
+ "mcpServers": {
42
+ "ecb": {
43
+ "command": "npx",
44
+ "args": ["-y", "@foreverworks/mcp-ecb"]
45
+ }
46
+ }
47
+ }
48
+ ```
49
+
50
+ Each runs the published package on Node 22.19 or newer. It needs no settings.
51
+
52
+ ### From a clone
53
+
54
+ ```bash
55
+ git clone https://github.com/foreverworks/mcps.git && cd mcps
56
+ npm ci && npm run build
57
+ claude mcp add ecb -- node "$PWD/servers/ecb/dist/index.js"
58
+ ```
59
+
60
+ In a JSON configuration, the command is `node` and its one argument the full path of `servers/ecb/dist/index.js`. To share one running copy between several clients over HTTP, see [docs/deploying.md](../../docs/deploying.md).
61
+ <!-- install:end -->
62
+
63
+ ## Configuration
64
+
65
+ None of its own. The variables every server shares are in
66
+ [docs/configuration.md](../../docs/configuration.md); a process limited by
67
+ `MCP_EGRESS_ALLOW` must allow `www.ecb.europa.eu`. Dates are Frankfurt dates
68
+ (CET and CEST) whatever the host's time zone, so "today" is today in Frankfurt.
69
+
70
+ ## Tools
71
+
72
+ Every tool is **read**: it changes nothing.
73
+
74
+ | Tool | Access | What it does |
75
+ |---|---|---|
76
+ | `health` | read | Whether the ECB answers: the date of its latest fixing and how many currencies it carries, with a warning when that fixing is more than five days old. |
77
+ | `rate` | read | The rate in force on a day (default today): the ECB's fixing of that day or of the last working day before it, as units of the currency per 1 EUR, with the fixing's date (`fixing_date`). |
78
+ | `convert` | read | An amount (a decimal string) between any two currencies, the euro included, at the fixing in force on a day, rounded once by the rule you name, with the rate or rates and the fixing's date. |
79
+ | `rates` | read | Every currency (or the ones you name) as of one day, or every fixing the ECB published in a window, oldest first, up to 2,000 rates a call. |
80
+
81
+ ## Troubleshooting
82
+
83
+ **`input`.** The question cannot be answered as asked, and nothing was
84
+ fetched: a date after today or before 1999-01-04, a window holding more than
85
+ 2,000 rates (name fewer currencies or a shorter window), `from` after `to`, or
86
+ the same currency on both sides of a conversion. The message names which.
87
+
88
+ **`not_found`: "the ECB's fixing of ... carries no ... rate; it carries ..."**.
89
+ The fixing in force that day has no rate for the currency, and the message lists
90
+ the ones it has. The ECB's list changes over time: the Bulgarian lev has no
91
+ rate after 2025-12-31, the Croatian kuna after 2022-12-30 and the Russian rouble
92
+ after 2022-03-01. No older rate stands in for a missing one, since that would
93
+ be a rate from another day under a new date: ask for a day the ECB published
94
+ that currency, and use `rates` over a window to see which days those are.
95
+
96
+ **`api`.** The ECB's server did not answer, even after retries (status 0 is no
97
+ connection). Try again in a few minutes.
98
+
99
+ **`drift`.** The ECB answered with something that is not its rates XML, such as
100
+ an HTML page, or the format changed. The server refuses to guess; please report
101
+ it.
102
+
103
+ ## How it works
104
+
105
+ ### The source
106
+
107
+ The ECB publishes three static XML files under
108
+ `https://www.ecb.europa.eu/stats/eurofxref/` (read 2026-11-16), each a slice of
109
+ one series that changes once per TARGET working day, around 16:00 CET:
110
+
111
+ | File | Holds | Size |
112
+ |---|---|---|
113
+ | `eurofxref-daily.xml` | the latest fixing | 1.5 KB |
114
+ | `eurofxref-hist-90d.xml` | the last 90 days, 65 fixings | 70 KB |
115
+ | `eurofxref-hist.xml` | everything since 1999-01-04, 7,136 fixings | 8.2 MB, 960 KB compressed |
116
+
117
+ The server reads the smallest file that reaches the day you ask about: the
118
+ daily one for today, the 90 days for a recent day, and the history only for a
119
+ day older than that. When it does read the history it lays the two small files
120
+ over its tail, so a copy cached before today's fixing is never why a window
121
+ ends a day early. The two small files are kept five minutes (the ECB serves
122
+ them for five) and the history a day. Parsing the history takes about a
123
+ quarter of a second and 18 MB of memory, measured on the 2026-11-13 file.
124
+
125
+ **The files do not agree on style.** The daily file is indented, quotes with
126
+ `'` and writes `365.60` for the forint; the other two are one line, quote with
127
+ `"` and write `365.6`; and the history lists the newest fixing first. The
128
+ server reads both quote styles and drops trailing zeros, so a fixing reads the
129
+ same whichever file it came from: the value is the ECB's, digit for digit.
130
+ Any answer that is not this document fails as `drift`, never as an empty
131
+ period, and so does a rate that is not a positive plain decimal.
132
+
133
+ **Fetching.** A request is tried up to three times on a 5xx, a 429 or a
134
+ dropped connection.
135
+
136
+ ### The rate in force on a day
137
+
138
+ A day's rate is that day's fixing. A weekend, a TARGET holiday, or today before
139
+ the 16:00 CET publication takes the fixing of the last working day before it
140
+ (`2026-01-01` takes `2025-12-31`). Every answer carries `fixing_date`, so you
141
+ can say which publication you used; today's rate asked before the fixing also
142
+ carries a `note` saying so. The rate is whole-fixing: if the fixing in force
143
+ does not carry the currency, that is `not_found`, and no older rate stands in.
144
+
145
+ The euro itself answers `1` in `rate`, so every currency of a fixing has an
146
+ answer. A rate is units of the currency per 1 EUR, as the ECB quotes it: `1 EUR
147
+ = 1.1052 USD`. The server gives no inverse, because `1 / 1.1052` has no exact
148
+ decimal form; `convert` computes it exactly instead.
149
+
150
+ ### Converting an amount
151
+
152
+ `convert` takes the amount as a decimal string, so `1250.50` reaches the
153
+ arithmetic as written. Every conversion is one formula over the rates of one
154
+ fixing, where the euro's rate is 1:
155
+
156
+ - the euro to a currency: amount x rate;
157
+ - a currency to the euro: amount / rate;
158
+ - two currencies, through the euro: amount x rate(to) / rate(from).
159
+
160
+ The exact result is rounded once, to `places` (0 to 8, default 2), half up
161
+ (halves away from zero, as invoices round) unless `rounding` is `half-even`.
162
+ No rate is rounded on the way: a cross rate such as GBP to USD is not a
163
+ rounded GBP-to-EUR step followed by a rounded EUR-to-USD one. The answer
164
+ carries the rate or rates, their fixing's date, the rule, and a `meaning` line
165
+ to paste into a document: "100 GBP = 132.27 USD at the ECB fixing of
166
+ 2026-11-13: 1 EUR = 0.83559 GBP and 1 EUR = 1.1052 USD; 100 x 1.1052 /
167
+ 0.83559, a cross rate through the euro, rounded half-up to 2 places".
168
+
169
+ ### Several rates at once
170
+
171
+ `rates` answers fixings, oldest first, each with its date and a `rates` object
172
+ of currency to units per 1 EUR. With `date` (or nothing, for today), it holds
173
+ the one fixing in force that day, all currencies from it, dated by
174
+ `fixing_date`. With `from` and `to` (default today), it holds every fixing in
175
+ the window, both ends included, or none and a note saying so. Name currencies to
176
+ narrow either answer. A window is limited by size, not by length: 2,000 rates
177
+ a call (about a year of seven currencies, or every currency for about three
178
+ months), so the answer stays readable. A currency you named that the ECB did not
179
+ publish anywhere in the window is listed in `absent`; one missing from a day's
180
+ fixing is missing from that fixing's `rates`.
181
+
182
+ ## Limitations
183
+
184
+ - **The ECB's reference rates only**, once per working day and for information:
185
+ no intraday rates, no buy and sell spread, and not the rate a bank or card
186
+ gives.
187
+ - **About thirty currencies**, the ones the ECB publishes: 29 on 2026-11-13,
188
+ and 41 codes over the series, the ones that left (the lev, the kuna, the
189
+ rouble, the old lira, leu and tolar among them) only on the days they were
190
+ published.
191
+ - **From 1999-01-04**, the euro's first working day.
192
+ - **No inverse or percentage change fields**, which would not be exact
193
+ decimals; `convert` and your own arithmetic on the exact rates are.
194
+ - **The history is kept a day**, which only matters if the ECB corrects a rate
195
+ older than 90 days; the next day's read then has it.
196
+
197
+ ## Other servers for the ECB
198
+
199
+ Searched 2026-11-16 on the MCP Registry, npm and GitHub. The ECB publishes no
200
+ server of its own that we found. Community servers exist, most reading the same
201
+ data through a third party:
202
+
203
+ - **`@mrfentmen/ecb-mcp`** on npm (1.0.1, 2026-10): three tools, the latest
204
+ rate of one currency, its recent history and the ECB policy rate, from the
205
+ ECB's SDMX Data Portal. Its inverse rate goes through a JavaScript number and
206
+ `toFixed(6)`; it has no conversion and no date lookup.
207
+ - **`frankfurter-mcp`** on npm (1.0.2, 2026-10) and several others
208
+ (`@pipeworx/mcp-frankfurter`, `lineofflight/frankfurter-mcp`, ...) wrap
209
+ Frankfurter, a hosted service that republishes exchange rates. The one read
210
+ here converts with a JavaScript number and rounds through `toLocaleString`.
211
+ - **`@cyanheads/exchange-rates-mcp-server`** on npm (0.6.0, 2026-11), the most
212
+ complete: Frankfurter v1 rates from 1999, cross rates through the euro with no
213
+ intermediate rounding, and SQL over staged series. It returns the converted
214
+ amount as an unrounded JavaScript number and applies no rounding rule.
215
+ - **`@pipeworx/mcp-ecb`** on npm (0.2.1, 2026-11), through the Pipeworx
216
+ gateway, and `scka-de/ecb-mcp` and `mohammad-abbasi-sh/ecb-mcp` on GitHub:
217
+ the ECB Data Portal's statistics (exchange rates, interest rates, inflation
218
+ and more), by their own descriptions, not converters.
219
+ - **`@allratestoday/central-bank-mcp`** on npm (0.3.18, 2026-11): 130 central
220
+ banks through AllRatesToday's hosted API; dated tables and history need a
221
+ paid plan.
222
+
223
+ Libraries on npm, such as `ecb-euro-exchange-rates` and `ecb-exchange-rate`,
224
+ give the same rates without MCP.
225
+
226
+ This one exists for what none of them does together: it reads the ECB's own
227
+ files, from where its caller runs, with no third party in between and no key; it
228
+ keeps every rate as the ECB wrote it; it answers the rate in force on any day
229
+ since 1999, weekends, holidays and the hours before 16:00 CET included, and
230
+ always says which fixing it used; and it converts between any two currencies,
231
+ cross rates included, in exact decimals, by a named rounding rule, saying every
232
+ rate it used.
@@ -0,0 +1,20 @@
1
+ import type { Fixing } from "../domain/rates.js";
2
+ /** A rates document: its fixings, oldest first, at least one. */
3
+ export type RatesDocument = {
4
+ readonly fixings: readonly [Fixing, ...Fixing[]];
5
+ };
6
+ /** The ECB's three published files of reference rates, each a different slice of the same series. */
7
+ export type RatesPort = {
8
+ /** The latest fixing alone: a file of one working day, kept briefly. */
9
+ readonly latest: () => Promise<RatesDocument>;
10
+ /** The last 90 calendar days of fixings. */
11
+ readonly recent: () => Promise<RatesDocument>;
12
+ /** Every fixing since 1999-01-04. Large, so read only for a day older than `recent` reaches. */
13
+ readonly history: () => Promise<RatesDocument>;
14
+ };
15
+ export type Deps = {
16
+ readonly rates: RatesPort;
17
+ readonly now: () => number;
18
+ /** The ECB's calendar: dates are Frankfurt dates. */
19
+ readonly timeZone: string;
20
+ };
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=ports.js.map
@@ -0,0 +1,37 @@
1
+ import { type Rounding } from "@foreverworks/mcp-kit";
2
+ import type { Deps } from "../ports.js";
3
+ export type ConvertArgs = {
4
+ /** A plain decimal, already checked against DECIMAL_TEXT. */
5
+ readonly amount: string;
6
+ readonly from: string;
7
+ readonly to: string;
8
+ readonly date: string | undefined;
9
+ readonly rounding: Rounding;
10
+ readonly places: number | undefined;
11
+ };
12
+ /**
13
+ * An amount converted between two currencies at the ECB's fixing in force on a
14
+ * day, computed exactly from the fixing's rates and rounded once by the named
15
+ * rule. Any pair works: the euro to a currency or back, or two currencies
16
+ * through the euro, both rates from the same fixing. Answers the rates, the
17
+ * fixing's date and the rule beside the result, so the conversion can be
18
+ * stated and checked.
19
+ */
20
+ export declare const convert: (deps: Deps, args: ConvertArgs) => Promise<{
21
+ note?: string;
22
+ ok: true;
23
+ amount: string;
24
+ from: string;
25
+ to: string;
26
+ result: string;
27
+ date: string;
28
+ fixing_date: string;
29
+ rates: {
30
+ currency: string;
31
+ rate: string;
32
+ }[];
33
+ rounding: Rounding;
34
+ places: number;
35
+ meaning: string;
36
+ source: string;
37
+ }>;
@@ -0,0 +1,47 @@
1
+ import { formatDecimal, toDecimal } from "@foreverworks/mcp-kit";
2
+ import { checkedDate } from "../../domain/dates.js";
3
+ import { converted, DEFAULT_PLACES, perEuro } from "../../domain/convert.js";
4
+ import { fail, inputError } from "../../domain/errors.js";
5
+ import { BASE } from "../../domain/rates.js";
6
+ import { currencyOf, inForceOn, pendingNote, rateIn, SOURCE, today } from "./fixings.js";
7
+ /** The arithmetic, as text: the euro to a currency multiplies by its rate, a currency to the euro divides by it, two currencies go through the euro. */
8
+ const formulaOf = (amount, from, to, rateOf) => from === BASE ? `${amount} x ${rateOf(to)}` : to === BASE ? `${amount} / ${rateOf(from)}` : `${amount} x ${rateOf(to)} / ${rateOf(from)}`;
9
+ /**
10
+ * An amount converted between two currencies at the ECB's fixing in force on a
11
+ * day, computed exactly from the fixing's rates and rounded once by the named
12
+ * rule. Any pair works: the euro to a currency or back, or two currencies
13
+ * through the euro, both rates from the same fixing. Answers the rates, the
14
+ * fixing's date and the rule beside the result, so the conversion can be
15
+ * stated and checked.
16
+ */
17
+ export const convert = async (deps, args) => {
18
+ const from = currencyOf(args.from);
19
+ const to = currencyOf(args.to);
20
+ if (from === to)
21
+ fail(inputError(`from and to are both ${from}; there is nothing to convert`));
22
+ const now = today(deps);
23
+ const date = args.date === undefined ? now : checkedDate(args.date, now);
24
+ const fixing = await inForceOn(deps, date);
25
+ const places = args.places ?? DEFAULT_PLACES;
26
+ const legs = [from, to].filter((c) => c !== BASE).map((currency) => ({ currency, rate: rateIn(fixing, currency) }));
27
+ const rateOf = (currency) => legs.find((l) => l.currency === currency)?.rate;
28
+ const result = formatDecimal(converted(toDecimal(args.amount), perEuro(from, rateOf(from)), perEuro(to, rateOf(to)), places, args.rounding));
29
+ return {
30
+ ok: true,
31
+ amount: args.amount,
32
+ from,
33
+ to,
34
+ result,
35
+ date,
36
+ fixing_date: fixing.date,
37
+ rates: legs,
38
+ rounding: args.rounding,
39
+ places,
40
+ meaning: `${args.amount} ${from} = ${result} ${to} at the ECB fixing of ${fixing.date}${fixing.date === date ? "" : ` (the last fixing before ${date})`}: ` +
41
+ `${legs.map((l) => `1 EUR = ${l.rate} ${l.currency}`).join(" and ")}; ${formulaOf(args.amount, from, to, rateOf)}${legs.length === 2 ? ", a cross rate through the euro" : ""}, ` +
42
+ `rounded ${args.rounding} to ${places} places`,
43
+ ...pendingNote(date, now, fixing.date),
44
+ source: SOURCE,
45
+ };
46
+ };
47
+ //# sourceMappingURL=convert.js.map
@@ -0,0 +1,22 @@
1
+ import { type Fixing } from "../../domain/rates.js";
2
+ import type { Deps } from "../ports.js";
3
+ /** What every rate tool shares: the currency code, today in Frankfurt, the fixing in force on a day, the rate a fixing holds. */
4
+ export declare const SOURCE = "https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html";
5
+ export declare const currencyOf: (text: string) => string;
6
+ export declare const today: (deps: Deps) => string;
7
+ /**
8
+ * Fixings that include the one in force on `from` and every later one, oldest
9
+ * first. The small files answer when they reach back to `from` (the latest
10
+ * fixing alone, then the 90 days); only an older day reads the whole history,
11
+ * and then the small files are laid over its tail, so a day cached in the
12
+ * history before today's fixing was published is still answered.
13
+ */
14
+ export declare const fixingsFrom: (deps: Deps, from: string) => Promise<readonly Fixing[]>;
15
+ /** The fixing in force on `date`: that day's, or the last working day's before it. */
16
+ export declare const inForceOn: (deps: Deps, date: string) => Promise<Fixing>;
17
+ /** `currency`'s units per 1 EUR in `fixing`; the euro itself is 1. */
18
+ export declare const rateIn: (fixing: Fixing, currency: string) => string;
19
+ /** Said when today's rate was asked for and the ECB's fixing of the day is not out. */
20
+ export declare const pendingNote: (date: string, now: string, fixingDate: string) => {
21
+ readonly note?: string;
22
+ };
@@ -0,0 +1,40 @@
1
+ import { dateIn, FIRST_FIXING } from "../../domain/dates.js";
2
+ import { fail, inputError, notFound } from "../../domain/errors.js";
3
+ import { BASE, currenciesOf, fixingOn, merged } from "../../domain/rates.js";
4
+ /** What every rate tool shares: the currency code, today in Frankfurt, the fixing in force on a day, the rate a fixing holds. */
5
+ export const SOURCE = "https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html";
6
+ export const currencyOf = (text) => {
7
+ const c = text.trim().toUpperCase();
8
+ return /^[A-Z]{3}$/.test(c) ? c : fail(inputError(`currency is an ISO 4217 code like USD or GBP, or EUR, not "${text}"`));
9
+ };
10
+ export const today = (deps) => dateIn(deps.timeZone, deps.now());
11
+ /**
12
+ * Fixings that include the one in force on `from` and every later one, oldest
13
+ * first. The small files answer when they reach back to `from` (the latest
14
+ * fixing alone, then the 90 days); only an older day reads the whole history,
15
+ * and then the small files are laid over its tail, so a day cached in the
16
+ * history before today's fixing was published is still answered.
17
+ */
18
+ export const fixingsFrom = async (deps, from) => {
19
+ const latest = await deps.rates.latest();
20
+ if (from >= latest.fixings[0].date)
21
+ return latest.fixings;
22
+ const recent = await deps.rates.recent();
23
+ if (from >= recent.fixings[0].date)
24
+ return merged(recent.fixings, latest.fixings);
25
+ const history = await deps.rates.history();
26
+ return merged(history.fixings, recent.fixings, latest.fixings);
27
+ };
28
+ /** The fixing in force on `date`: that day's, or the last working day's before it. */
29
+ export const inForceOn = async (deps, date) => fixingOn(await fixingsFrom(deps, date), date) ?? fail(notFound(`the ECB published no fixing on or before ${date}; its series starts ${FIRST_FIXING}`));
30
+ /** `currency`'s units per 1 EUR in `fixing`; the euro itself is 1. */
31
+ export const rateIn = (fixing, currency) => {
32
+ if (currency === BASE)
33
+ return "1";
34
+ return fixing.rates[currency] ?? fail(notFound(`the ECB's fixing of ${fixing.date} carries no ${currency} rate; it carries ${currenciesOf(fixing).join(", ")}`));
35
+ };
36
+ /** Said when today's rate was asked for and the ECB's fixing of the day is not out. */
37
+ export const pendingNote = (date, now, fixingDate) => date === now && fixingDate !== now
38
+ ? { note: `the ECB publishes the day's rates around 16:00 CET; ${now}'s are not out yet or there are none (a weekend or TARGET holiday)` }
39
+ : {};
40
+ //# sourceMappingURL=fixings.js.map
@@ -0,0 +1,29 @@
1
+ import type { Deps } from "../ports.js";
2
+ /**
3
+ * The rate in force on `date`: the ECB's fixing of that day, or of the last
4
+ * working day before it (a weekend, a TARGET holiday, or a day whose fixing is
5
+ * not out yet: the ECB publishes around 16:00 CET). Answers the fixing's own
6
+ * date, so a caller sees which publication it got.
7
+ */
8
+ export declare const rate: (deps: Deps, args: {
9
+ readonly currency: string;
10
+ readonly date: string | undefined;
11
+ }) => Promise<{
12
+ note?: string;
13
+ ok: true;
14
+ currency: string;
15
+ date: string;
16
+ rate: string;
17
+ fixing_date: string;
18
+ meaning: string;
19
+ source: string;
20
+ }>;
21
+ /** Whether the ECB answers: its latest fixing, its date and how many currencies it carries. */
22
+ export declare const health: (deps: Deps) => Promise<{
23
+ ok: true;
24
+ source: string;
25
+ latest_fixing: string | undefined;
26
+ currencies: number;
27
+ today: string;
28
+ warning?: string;
29
+ }>;
@@ -0,0 +1,43 @@
1
+ import { addDays } from "@foreverworks/mcp-kit";
2
+ import { checkedDate } from "../../domain/dates.js";
3
+ import { BASE } from "../../domain/rates.js";
4
+ import { currencyOf, inForceOn, pendingNote, rateIn, SOURCE, today } from "./fixings.js";
5
+ /**
6
+ * The rate in force on `date`: the ECB's fixing of that day, or of the last
7
+ * working day before it (a weekend, a TARGET holiday, or a day whose fixing is
8
+ * not out yet: the ECB publishes around 16:00 CET). Answers the fixing's own
9
+ * date, so a caller sees which publication it got.
10
+ */
11
+ export const rate = async (deps, args) => {
12
+ const currency = currencyOf(args.currency);
13
+ const now = today(deps);
14
+ const date = args.date === undefined ? now : checkedDate(args.date, now);
15
+ const fixing = await inForceOn(deps, date);
16
+ const value = rateIn(fixing, currency);
17
+ return {
18
+ ok: true,
19
+ currency,
20
+ date,
21
+ rate: value,
22
+ fixing_date: fixing.date,
23
+ meaning: currency === BASE
24
+ ? `1 EUR is 1 EUR: the euro is the base every ECB rate is quoted against; the fixing in force on ${date} is the one of ${fixing.date}`
25
+ : `1 EUR = ${value} ${currency}, the ECB's euro foreign exchange reference rate of ${fixing.date}${fixing.date === date ? "" : `, the last fixing before ${date}`}`,
26
+ ...pendingNote(date, now, fixing.date),
27
+ source: SOURCE,
28
+ };
29
+ };
30
+ /** Whether the ECB answers: its latest fixing, its date and how many currencies it carries. */
31
+ export const health = async (deps) => {
32
+ const fixing = (await deps.rates.latest()).fixings.at(-1);
33
+ const now = today(deps);
34
+ return {
35
+ ok: true,
36
+ source: SOURCE,
37
+ latest_fixing: fixing?.date,
38
+ currencies: fixing === undefined ? 0 : Object.keys(fixing.rates).length,
39
+ today: now,
40
+ ...(fixing !== undefined && fixing.date < addDays(now, -5) ? { warning: `the latest fixing is from ${fixing.date}, more than five days ago` } : {}),
41
+ };
42
+ };
43
+ //# sourceMappingURL=rates.js.map
@@ -0,0 +1,33 @@
1
+ import { type Fixing } from "../../domain/rates.js";
2
+ import type { Deps } from "../ports.js";
3
+ /** About 40 KB of answer: a year of seven currencies, or every currency for two months. */
4
+ export declare const MAX_RATES = 2000;
5
+ export type RatesArgs = {
6
+ readonly currencies: readonly string[] | undefined;
7
+ readonly date: string | undefined;
8
+ readonly from: string | undefined;
9
+ readonly to: string | undefined;
10
+ };
11
+ /**
12
+ * The ECB's rates as fixings, oldest first: several currencies (or all) on one
13
+ * day, each from the fixing in force then, or every fixing in a window. Rates
14
+ * are the ECB's exact text.
15
+ */
16
+ export declare const rates: (deps: Deps, args: RatesArgs) => Promise<{
17
+ note?: string;
18
+ ok: true;
19
+ date: string;
20
+ fixing_date: string;
21
+ fixings: readonly Fixing[];
22
+ count: number;
23
+ source: string;
24
+ } | {
25
+ ok: true;
26
+ from: string;
27
+ to: string;
28
+ fixings: readonly Fixing[];
29
+ count: number;
30
+ absent?: string[];
31
+ note?: string;
32
+ source: string;
33
+ }>;
@@ -0,0 +1,65 @@
1
+ import { checkedDate } from "../../domain/dates.js";
2
+ import { fail, inputError, notFound } from "../../domain/errors.js";
3
+ import { BASE, countOf, currenciesOf, windowOf } from "../../domain/rates.js";
4
+ import { currencyOf, fixingsFrom, inForceOn, pendingNote, SOURCE, today } from "./fixings.js";
5
+ /** About 40 KB of answer: a year of seven currencies, or every currency for two months. */
6
+ export const MAX_RATES = 2000;
7
+ /** The currencies asked for, checked and without repeats; the euro is the base, not a rate. */
8
+ const currenciesAsked = (asked) => {
9
+ const codes = asked === undefined ? undefined : [...new Set(asked.map(currencyOf))];
10
+ if (codes?.includes(BASE))
11
+ fail(inputError("EUR is the base every rate is quoted against, so it has no rate of its own; name the other currencies"));
12
+ return codes;
13
+ };
14
+ /** Every currency (or those asked for) in the fixing in force on one day, all from that one fixing. */
15
+ const onDay = async (deps, asked, date, now) => {
16
+ const fixing = await inForceOn(deps, date);
17
+ const unknown = (asked ?? []).filter((c) => fixing.rates[c] === undefined);
18
+ if (unknown.length > 0)
19
+ fail(notFound(`the ECB's fixing of ${fixing.date} carries no ${unknown.join(", ")} rate; it carries ${currenciesOf(fixing).join(", ")}`));
20
+ const [row] = windowOf([fixing], fixing.date, fixing.date, asked);
21
+ const fixings = row === undefined ? [] : [row];
22
+ return { ok: true, date, fixing_date: fixing.date, fixings, count: countOf(fixings), ...pendingNote(date, now, fixing.date), source: SOURCE };
23
+ };
24
+ /** Every fixing the ECB published from `from` to `to`, both included. */
25
+ const inWindow = async (deps, asked, from, to) => {
26
+ const fixings = windowOf(await fixingsFrom(deps, from), from, to, asked);
27
+ const count = countOf(fixings);
28
+ if (count > MAX_RATES)
29
+ fail(inputError(`${from} to ${to} holds ${count} rates, more than the ${MAX_RATES} a call answers: name fewer currencies or a shorter window`));
30
+ const absent = (asked ?? []).filter((c) => !fixings.some((f) => f.rates[c] !== undefined));
31
+ return {
32
+ ok: true,
33
+ from,
34
+ to,
35
+ fixings,
36
+ count,
37
+ ...(absent.length > 0 && fixings.length > 0 ? { absent } : {}),
38
+ ...(fixings.length === 0
39
+ ? { note: `the ECB published no ${asked === undefined ? "fixing" : `${asked.join(", ")} rate`} from ${from} to ${to} (a weekend, TARGET holidays, a currency it does not carry then, or not out yet); give date instead for the rates in force then` }
40
+ : {}),
41
+ source: SOURCE,
42
+ };
43
+ };
44
+ /**
45
+ * The ECB's rates as fixings, oldest first: several currencies (or all) on one
46
+ * day, each from the fixing in force then, or every fixing in a window. Rates
47
+ * are the ECB's exact text.
48
+ */
49
+ export const rates = async (deps, args) => {
50
+ const now = today(deps);
51
+ const asked = currenciesAsked(args.currencies);
52
+ if (args.from === undefined) {
53
+ if (args.to !== undefined)
54
+ fail(inputError("to ends the window from starts: give from too, or date alone for one day"));
55
+ return onDay(deps, asked, args.date === undefined ? now : checkedDate(args.date, now), now);
56
+ }
57
+ if (args.date !== undefined)
58
+ fail(inputError("give date for the rates in force on one day, or from (and to) for every fixing in a window, not both"));
59
+ const from = checkedDate(args.from, now);
60
+ const to = args.to === undefined ? now : checkedDate(args.to, now);
61
+ if (from > to)
62
+ fail(inputError(`from (${from}) is after to (${to})`));
63
+ return inWindow(deps, asked, from, to);
64
+ };
65
+ //# sourceMappingURL=series.js.map
@@ -0,0 +1,12 @@
1
+ import type { Deps } from "./app/ports.js";
2
+ import { type EcbOptions } from "./infra/ecb.js";
3
+ /** The ECB's calendar: a fixing's date and "today" are Frankfurt dates (CET and CEST), whatever the host's zone. */
4
+ export declare const ECB_TIME_ZONE = "Europe/Berlin";
5
+ /**
6
+ * The composition root: the only module naming both a port and what
7
+ * implements it. Nothing here touches the network; the ECB is read when a tool
8
+ * asks.
9
+ */
10
+ export declare const buildDeps: (options?: EcbOptions & {
11
+ readonly now?: () => number;
12
+ }) => Deps;
@@ -0,0 +1,13 @@
1
+ import { makeEcb } from "./infra/ecb.js";
2
+ /** The ECB's calendar: a fixing's date and "today" are Frankfurt dates (CET and CEST), whatever the host's zone. */
3
+ export const ECB_TIME_ZONE = "Europe/Berlin";
4
+ /**
5
+ * The composition root: the only module naming both a port and what
6
+ * implements it. Nothing here touches the network; the ECB is read when a tool
7
+ * asks.
8
+ */
9
+ export const buildDeps = (options = {}) => {
10
+ const { now = Date.now, ...ecb } = options;
11
+ return { rates: makeEcb(now, ecb), now, timeZone: ECB_TIME_ZONE };
12
+ };
13
+ //# sourceMappingURL=composition.js.map