easybill-mcp 1.0.2 → 1.2.0
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.
- package/README.md +123 -15
- package/dist/constants.d.ts +2 -1
- package/dist/constants.js +18 -1
- package/dist/constants.js.map +1 -1
- package/dist/hosted/accounts.d.ts +13 -0
- package/dist/hosted/accounts.js +70 -0
- package/dist/hosted/accounts.js.map +1 -0
- package/dist/hosted/config.d.ts +73 -0
- package/dist/hosted/config.js +200 -0
- package/dist/hosted/config.js.map +1 -0
- package/dist/hosted/http.d.ts +23 -0
- package/dist/hosted/http.js +524 -0
- package/dist/hosted/http.js.map +1 -0
- package/dist/hosted/pages.d.ts +22 -0
- package/dist/hosted/pages.js +130 -0
- package/dist/hosted/pages.js.map +1 -0
- package/dist/hosted/provider.d.ts +54 -0
- package/dist/hosted/provider.js +190 -0
- package/dist/hosted/provider.js.map +1 -0
- package/dist/hosted/store.d.ts +119 -0
- package/dist/hosted/store.js +254 -0
- package/dist/hosted/store.js.map +1 -0
- package/dist/hosted/upstream.d.ts +68 -0
- package/dist/hosted/upstream.js +280 -0
- package/dist/hosted/upstream.js.map +1 -0
- package/dist/index.d.ts +5 -1
- package/dist/index.js +19 -24
- package/dist/index.js.map +1 -1
- package/dist/instructions.d.ts +1 -1
- package/dist/instructions.js +16 -1
- package/dist/instructions.js.map +1 -1
- package/dist/server.d.ts +26 -0
- package/dist/server.js +47 -0
- package/dist/server.js.map +1 -0
- package/dist/services/client.d.ts +43 -4
- package/dist/services/client.js +35 -9
- package/dist/services/client.js.map +1 -1
- package/dist/services/format.d.ts +17 -4
- package/dist/services/format.js.map +1 -1
- package/dist/tools/catalog.d.ts +2 -2
- package/dist/tools/catalog.js.map +1 -1
- package/dist/tools/crud.d.ts +2 -2
- package/dist/tools/crud.js.map +1 -1
- package/dist/tools/customers.d.ts +2 -2
- package/dist/tools/customers.js +12 -4
- package/dist/tools/customers.js.map +1 -1
- package/dist/tools/documents.d.ts +2 -2
- package/dist/tools/documents.js +73 -43
- package/dist/tools/documents.js.map +1 -1
- package/dist/tools/files-io.d.ts +44 -0
- package/dist/tools/files-io.js +173 -0
- package/dist/tools/files-io.js.map +1 -0
- package/dist/tools/files.d.ts +2 -2
- package/dist/tools/files.js +9 -27
- package/dist/tools/files.js.map +1 -1
- package/dist/tools/finance.d.ts +2 -2
- package/dist/tools/finance.js.map +1 -1
- package/dist/tools/incoming.d.ts +11 -0
- package/dist/tools/incoming.js +222 -0
- package/dist/tools/incoming.js.map +1 -0
- package/dist/tools/meta.d.ts +2 -2
- package/dist/tools/meta.js +14 -6
- package/dist/tools/meta.js.map +1 -1
- package/dist/tools/registry.d.ts +40 -9
- package/dist/tools/registry.js +75 -12
- package/dist/tools/registry.js.map +1 -1
- package/dist/tools/search.d.ts +9 -8
- package/dist/tools/search.js +49 -17
- package/dist/tools/search.js.map +1 -1
- package/dist/tools/work.d.ts +2 -2
- package/dist/tools/work.js.map +1 -1
- package/package.json +5 -2
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@ projects and tracked time.
|
|
|
8
8
|
Built on the official [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk)
|
|
9
9
|
(TypeScript), talking stdio.
|
|
10
10
|
|
|
11
|
-
- **
|
|
11
|
+
- **64 tools** across 13 easybill resources (65 in hosted mode)
|
|
12
12
|
- **Read-only by default** — create/update/delete tools stay unregistered unless you opt in
|
|
13
13
|
- **Workflow-aware** — ships server instructions so the agent resolves the customer before
|
|
14
14
|
writing a document, instead of guessing where to start
|
|
@@ -37,7 +37,7 @@ Configuration is entirely through environment variables (full list under
|
|
|
37
37
|
[Configuration](#configuration)). Two matter now:
|
|
38
38
|
|
|
39
39
|
- Leave `EASYBILL_ENABLE_WRITES` unset to start **read-only**.
|
|
40
|
-
- Set `EASYBILL_RATE_LIMIT_PER_MINUTE` to **10** on easybill's
|
|
40
|
+
- Set `EASYBILL_RATE_LIMIT_PER_MINUTE` to **10** on easybill's Professional plan or **60** on Premium (Free and Starter have no API access).
|
|
41
41
|
|
|
42
42
|
Most clients use the same JSON shape under an `mcpServers` key:
|
|
43
43
|
|
|
@@ -143,8 +143,11 @@ env = { EASYBILL_API_KEY = "your_api_key_here", EASYBILL_RATE_LIMIT_PER_MINUTE =
|
|
|
143
143
|
|
|
144
144
|
#### Hosted clients that only speak remote MCP
|
|
145
145
|
|
|
146
|
-
|
|
147
|
-
|
|
146
|
+
For claude.ai and other remote-only clients, run the server in **hosted mode** (see
|
|
147
|
+
"Hosted mode" below): one connector for the whole company, each person connects the easybill
|
|
148
|
+
accounts they use with their personal API key.
|
|
149
|
+
|
|
150
|
+
For a quick single-user experiment you can instead bridge the stdio server locally:
|
|
148
151
|
|
|
149
152
|
```bash
|
|
150
153
|
npx -y supergateway --stdio "npx -y easybill-mcp"
|
|
@@ -264,13 +267,101 @@ creates a git tag. npm does not allow republishing an existing version.
|
|
|
264
267
|
|
|
265
268
|
---
|
|
266
269
|
|
|
270
|
+
## Hosted mode (claude.ai connector, several easybill accounts)
|
|
271
|
+
|
|
272
|
+
`easybill-mcp --http` runs the server as a remote MCP endpoint (Streamable HTTP) for a whole
|
|
273
|
+
company:
|
|
274
|
+
|
|
275
|
+
1. Someone adds the connector in claude.ai (or any OAuth-capable MCP client).
|
|
276
|
+
2. The client opens this server's **connect page**. It lists the easybill accounts from your
|
|
277
|
+
tenant configuration; the person clicks *Verbinden* on each account they have access to and
|
|
278
|
+
pastes **their personal easybill API key** (easybill: user icon → *Profil und Einstellungen*
|
|
279
|
+
→ *API Key*). The server checks it against easybill before storing it.
|
|
280
|
+
3. *Fertig – zurück zu Claude* completes the client's OAuth flow.
|
|
281
|
+
|
|
282
|
+
Every tool then takes an `account` argument (`easybill_list_accounts` shows the status and
|
|
283
|
+
hands out a link to connect more accounts or replace a key). Keys are stored AES-GCM encrypted
|
|
284
|
+
in SQLite. A key easybill rejects later (regenerated, login removed) is marked and the model
|
|
285
|
+
hands out the link to replace it.
|
|
286
|
+
|
|
287
|
+
This server is the OAuth authorization server for the MCP client (claude.ai); easybill itself
|
|
288
|
+
only sees API-key requests. An API key does not say which easybill account it belongs to, so on
|
|
289
|
+
the first connection of a tenant the server remembers the account's login IDs (from `/logins`)
|
|
290
|
+
and refuses later keys from a different account, including a key that already belongs to another
|
|
291
|
+
configured tenant.
|
|
292
|
+
|
|
293
|
+
**easybill OAuth instead of API keys** (`EASYBILL_CONNECT_MODE=oauth`): people log in at easybill
|
|
294
|
+
instead of pasting a key. easybill only allows dynamic client registration for an allowlist of
|
|
295
|
+
redirect URIs (claude.ai and similar), so this mode needs an OAuth client issued by easybill for
|
|
296
|
+
`<EASYBILL_PUBLIC_URL>/connect/callback` (`EASYBILL_OAUTH_CLIENT_ID` / `_SECRET`).
|
|
297
|
+
|
|
298
|
+
### Tenant configuration
|
|
299
|
+
|
|
300
|
+
```json
|
|
301
|
+
{
|
|
302
|
+
"tenants": [
|
|
303
|
+
{ "id": "firma-a", "name": "Firma A GmbH", "plan": "PREMIUM", "writes": true },
|
|
304
|
+
{ "id": "firma-b", "name": "Firma B GmbH", "plan": "PROFESSIONAL", "writes": false }
|
|
305
|
+
]
|
|
306
|
+
}
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
| Field | Meaning |
|
|
310
|
+
|---|---|
|
|
311
|
+
| `id` | Slug the model passes as `account`. |
|
|
312
|
+
| `name` | Shown on the connect page and to the model. |
|
|
313
|
+
| `plan` | `PROFESSIONAL` (10 req/min) or `PREMIUM` (60 req/min); the former names `PLUS` / `BUSINESS` work too. Free and Starter have no API access. Throttle shared by everyone on the account. Or set `rate_limit_per_minute`. |
|
|
314
|
+
| `writes` | `true` registers create/update/delete for this account and requests write scopes from easybill. Default read-only scopes. |
|
|
315
|
+
| `scopes` | Optional override of the easybill OAuth scopes. |
|
|
316
|
+
| `match` | OAuth mode only: `{ "<claim>": "<value>" }` checked against easybill's access-token claims, so a login of the wrong company is refused. The server logs the claims of every new connection. |
|
|
317
|
+
|
|
318
|
+
### Environment
|
|
319
|
+
|
|
320
|
+
| Variable | Default | Purpose |
|
|
321
|
+
|---|---|---|
|
|
322
|
+
| `EASYBILL_PUBLIC_URL` | — | **Required.** Public https base URL. The connector URL is `<this>/mcp`. |
|
|
323
|
+
| `EASYBILL_MCP_SECRET` | — | **Required.** ≥ 32 characters; encrypts stored tokens and signs the browser cookie. Changing it invalidates all connections. |
|
|
324
|
+
| `EASYBILL_TENANTS_FILE` / `EASYBILL_TENANTS` | — | **Required.** Path to the tenant JSON, or the JSON inline. |
|
|
325
|
+
| `EASYBILL_DB_PATH` | `./data/easybill-mcp.sqlite` | SQLite file. Put it on a persistent volume. |
|
|
326
|
+
| `PORT` / `HOST` | `3000` / `0.0.0.0` | Listen address. |
|
|
327
|
+
| `EASYBILL_CF_ACCESS_TEAM_DOMAIN` / `EASYBILL_CF_ACCESS_AUD` | — | Put the connect pages behind Cloudflare Access: team domain (e.g. `acme` or `acme.cloudflareaccess.com`) and the Access application's AUD tag. `/connect/*` then requires a valid Access token, checked by the server itself. |
|
|
328
|
+
| `EASYBILL_ICON_PATH` | — | Path to an `.svg`, `.png` or `.ico` file (e.g. a file mount in your hosting platform). Served as `/favicon.ico` and `/favicon.<ext>`, linked from the pages and announced as the MCP server icon. claude.ai shows the domain's favicon next to a custom connector. |
|
|
329
|
+
| `EASYBILL_CONNECT_MODE` | `apikey` (`oauth` if a client ID is set) | How people connect easybill accounts. |
|
|
330
|
+
| `EASYBILL_OAUTH_CLIENT_ID` / `_SECRET` | — | OAuth mode: the client easybill issued for this server. |
|
|
331
|
+
| `EASYBILL_OAUTH_ISSUER` | `https://api.easybill.de` | OAuth mode: easybill's OAuth issuer. |
|
|
332
|
+
| `EASYBILL_MCP_ACCESS_TOKEN_TTL` | `3600` | Lifetime (s) of access tokens issued to MCP clients. |
|
|
333
|
+
| `EASYBILL_MCP_REFRESH_TOKEN_TTL` | `7776000` | Lifetime (s) of refresh tokens issued to MCP clients (90 days). |
|
|
334
|
+
|
|
335
|
+
Needs Node.js ≥ 22.13 (built-in `node:sqlite`). The `Dockerfile` builds a ready image:
|
|
336
|
+
|
|
337
|
+
```bash
|
|
338
|
+
docker build -t easybill-mcp .
|
|
339
|
+
docker run -p 3000:3000 -v easybill-mcp-data:/data \
|
|
340
|
+
-v $PWD/tenants.json:/config/tenants.json:ro \
|
|
341
|
+
-e EASYBILL_TENANTS_FILE=/config/tenants.json \
|
|
342
|
+
-e EASYBILL_PUBLIC_URL=https://easybill-mcp.example.com \
|
|
343
|
+
-e EASYBILL_MCP_SECRET="$(openssl rand -base64 48)" \
|
|
344
|
+
easybill-mcp
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
**Cloudflare Zero Trust:** protect only the path `/connect` with an Access application (the
|
|
348
|
+
connect pages are opened in a browser). Leave `/mcp`, `/token`, `/register`, `/authorize` and
|
|
349
|
+
`/.well-known/*` outside Access — claude.ai calls them from its servers and cannot pass an Access
|
|
350
|
+
login. Without the connect pages nobody can complete the authorization, so tokens stay out of
|
|
351
|
+
reach. Set the two `EASYBILL_CF_ACCESS_*` variables so the server rejects requests that bypass
|
|
352
|
+
Cloudflare (e.g. via the origin IP).
|
|
353
|
+
|
|
354
|
+
Run it behind TLS (reverse proxy). Then in claude.ai: *Settings → Connectors → Add custom
|
|
355
|
+
connector* with `https://easybill-mcp.example.com/mcp` (organization admins can add it once for
|
|
356
|
+
everyone; each person still connects their own easybill logins).
|
|
357
|
+
|
|
267
358
|
## Configuration
|
|
268
359
|
|
|
269
360
|
| Variable | Default | Purpose |
|
|
270
361
|
|---|---|---|
|
|
271
362
|
| `EASYBILL_API_KEY` | — | **Required.** Your easybill API key. |
|
|
272
363
|
| `EASYBILL_ENABLE_WRITES` | *unset* | Set to `true` to register create/update/delete tools. Otherwise read-only. |
|
|
273
|
-
| `EASYBILL_RATE_LIMIT_PER_MINUTE` | `60` | Client-side throttle. Use `10` for
|
|
364
|
+
| `EASYBILL_RATE_LIMIT_PER_MINUTE` | `60` | Client-side throttle. Use `10` for Professional, `60` for Premium. |
|
|
274
365
|
| `EASYBILL_CHARACTER_LIMIT` | `25000` | Max characters per response before truncation. |
|
|
275
366
|
| `EASYBILL_TIMEOUT_MS` | `30000` | HTTP request timeout. |
|
|
276
367
|
| `EASYBILL_MAX_RETRIES` | `3` | Retries on HTTP 429 / 5xx. |
|
|
@@ -284,11 +375,12 @@ creates a git tag. npm does not allow republishing an existing version.
|
|
|
284
375
|
|
|
285
376
|
| Tool | Access |
|
|
286
377
|
|---|---|
|
|
287
|
-
| `easybill_find_customer` | read — **start here**:
|
|
378
|
+
| `easybill_find_customer` | read — **start here**: search customers or suppliers by name, email or number |
|
|
288
379
|
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
380
|
+
Uses easybill's full-text search (one request, archived contacts included) and ranks the hits
|
|
381
|
+
locally, tolerating legal forms (`GmbH & Co. KG`), punctuation (`M.B. MUSTERMANN` vs
|
|
382
|
+
`MB Mustermann`), umlauts and word order. If the search endpoint is unavailable it falls back to
|
|
383
|
+
exact filters plus a local scan of the customer list.
|
|
292
384
|
|
|
293
385
|
### Documents — invoices, offers, credit notes, deliveries, orders
|
|
294
386
|
|
|
@@ -296,7 +388,8 @@ punctuation (`M.B. MUSTERMANN` vs `MB Mustermann`), umlauts and word order.
|
|
|
296
388
|
|---|---|
|
|
297
389
|
| `easybill_list_documents` | read |
|
|
298
390
|
| `easybill_get_document` | read |
|
|
299
|
-
| `
|
|
391
|
+
| `easybill_search_documents` | read — full-text search by word, name or number |
|
|
392
|
+
| `easybill_download_document` | read — PDF, image, ZUGFeRD 1.0–2.5, XRechnung (to disk locally, inline when hosted) |
|
|
300
393
|
| `easybill_list_document_versions` | read — audit trail |
|
|
301
394
|
| `easybill_create_document` | write |
|
|
302
395
|
| `easybill_update_document` | write |
|
|
@@ -338,9 +431,24 @@ punctuation (`M.B. MUSTERMANN` vs `MB Mustermann`), umlauts and word order.
|
|
|
338
431
|
`easybill_delete_attachment`, `easybill_list_text_templates`, `easybill_get_text_template`,
|
|
339
432
|
`easybill_list_pdf_templates`
|
|
340
433
|
|
|
434
|
+
### Incoming documents (Eingangsbelege)
|
|
435
|
+
|
|
436
|
+
`easybill_list_incoming_documents`, `easybill_search_incoming_documents`,
|
|
437
|
+
`easybill_get_incoming_document`, `easybill_list_incoming_document_files`,
|
|
438
|
+
`easybill_download_incoming_document_file` (read);
|
|
439
|
+
`easybill_upload_incoming_document`, `easybill_update_incoming_document`,
|
|
440
|
+
`easybill_complete_incoming_document`, `easybill_delete_incoming_document` (write).
|
|
441
|
+
|
|
442
|
+
Uploads are extracted by easybill in the background; the tools guide the agent through
|
|
443
|
+
review → correction → completion.
|
|
444
|
+
|
|
341
445
|
### Server
|
|
342
446
|
|
|
343
447
|
`easybill_get_server_info` — reports mode, limits and whether the credentials work.
|
|
448
|
+
In hosted mode also `easybill_list_accounts` — connected accounts and the link to connect more.
|
|
449
|
+
|
|
450
|
+
Files in hosted mode: downloads come back inside the tool result and uploads take base64 —
|
|
451
|
+
the server never reads or writes caller-chosen paths on its own disk.
|
|
344
452
|
|
|
345
453
|
---
|
|
346
454
|
|
|
@@ -388,7 +496,7 @@ legal reasons.
|
|
|
388
496
|
|
|
389
497
|
### Rate limits are low
|
|
390
498
|
|
|
391
|
-
easybill allows **10 requests/minute on
|
|
499
|
+
easybill allows **10 requests/minute on Professional** and **60 on Premium** (formerly PLUS and BUSINESS). The server throttles
|
|
392
500
|
itself to `EASYBILL_RATE_LIMIT_PER_MINUTE` and, if a 429 slips through, retries while honouring
|
|
393
501
|
`Retry-After`. Set the variable to match your plan — otherwise a broad question that pages
|
|
394
502
|
through many documents will stall.
|
|
@@ -408,11 +516,11 @@ field set**, and single-record lookups return everything. Both accept `fields`:
|
|
|
408
516
|
Responses over `EASYBILL_CHARACTER_LIMIT` are truncated, halving the item count until they
|
|
409
517
|
fit, and say so in `truncation_message`.
|
|
410
518
|
|
|
411
|
-
###
|
|
519
|
+
### Full-text search vs. filters
|
|
412
520
|
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
521
|
+
List filters match **exact** values (each accepts several comma-separated). For a partial name,
|
|
522
|
+
a word or a topic use the full-text tools (API 1.102+): `easybill_find_customer`,
|
|
523
|
+
`easybill_search_documents`, `easybill_search_incoming_documents`. Each costs one request.
|
|
416
524
|
|
|
417
525
|
### Useful filter recipes
|
|
418
526
|
|
package/dist/constants.d.ts
CHANGED
|
@@ -12,7 +12,7 @@ export declare const CHARACTER_LIMIT: number;
|
|
|
12
12
|
/** HTTP request timeout. */
|
|
13
13
|
export declare const TIMEOUT_MS: number;
|
|
14
14
|
/**
|
|
15
|
-
* Client-side throttle. easybill allows 10 req/min (
|
|
15
|
+
* Client-side throttle. easybill allows 10 req/min (Professional) and 60 req/min (Premium).
|
|
16
16
|
* Throttling locally is cheaper than burning retries on HTTP 429.
|
|
17
17
|
*/
|
|
18
18
|
export declare const RATE_LIMIT_PER_MINUTE: number;
|
|
@@ -51,4 +51,5 @@ export declare const SUMMARY_FIELDS: {
|
|
|
51
51
|
readonly customerGroup: readonly ["id", "number", "name", "display_name", "description"];
|
|
52
52
|
readonly serialNumber: readonly ["id", "serial_number", "position_id", "document_id", "used_at", "created_at"];
|
|
53
53
|
readonly pdfTemplate: readonly ["id", "name", "pdf_template", "document_type"];
|
|
54
|
+
readonly incomingDocument: readonly ["id", "status", "document_type", "document_number", "external_number", "issue_date", "due_date", "total_gross_amount", "total_net_amount", "currency_code", "is_paid", "supplier_id", "supplier", "interface", "created_at"];
|
|
54
55
|
};
|
package/dist/constants.js
CHANGED
|
@@ -32,7 +32,7 @@ export const CHARACTER_LIMIT = intFromEnv("EASYBILL_CHARACTER_LIMIT", 25_000, 1_
|
|
|
32
32
|
/** HTTP request timeout. */
|
|
33
33
|
export const TIMEOUT_MS = intFromEnv("EASYBILL_TIMEOUT_MS", 30_000, 1_000);
|
|
34
34
|
/**
|
|
35
|
-
* Client-side throttle. easybill allows 10 req/min (
|
|
35
|
+
* Client-side throttle. easybill allows 10 req/min (Professional) and 60 req/min (Premium).
|
|
36
36
|
* Throttling locally is cheaper than burning retries on HTTP 429.
|
|
37
37
|
*/
|
|
38
38
|
export const RATE_LIMIT_PER_MINUTE = intFromEnv("EASYBILL_RATE_LIMIT_PER_MINUTE", 60, 1);
|
|
@@ -215,5 +215,22 @@ export const SUMMARY_FIELDS = {
|
|
|
215
215
|
customerGroup: ["id", "number", "name", "display_name", "description"],
|
|
216
216
|
serialNumber: ["id", "serial_number", "position_id", "document_id", "used_at", "created_at"],
|
|
217
217
|
pdfTemplate: ["id", "name", "pdf_template", "document_type"],
|
|
218
|
+
incomingDocument: [
|
|
219
|
+
"id",
|
|
220
|
+
"status",
|
|
221
|
+
"document_type",
|
|
222
|
+
"document_number",
|
|
223
|
+
"external_number",
|
|
224
|
+
"issue_date",
|
|
225
|
+
"due_date",
|
|
226
|
+
"total_gross_amount",
|
|
227
|
+
"total_net_amount",
|
|
228
|
+
"currency_code",
|
|
229
|
+
"is_paid",
|
|
230
|
+
"supplier_id",
|
|
231
|
+
"supplier",
|
|
232
|
+
"interface",
|
|
233
|
+
"created_at",
|
|
234
|
+
],
|
|
218
235
|
};
|
|
219
236
|
//# sourceMappingURL=constants.js.map
|
package/dist/constants.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAE9E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,4EAA4E;AAC5E,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,IAAI,EAAE,IAAI,iCAAiC,CAC3E,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAEtB,MAAM,CAAC,MAAM,WAAW,GAAG,qBAAqB,CAAC;AAEjD;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAW,CAAC,GAAG,EAAE;IAC1C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/C,uCAAuC;QACvC,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAyB,CAAC;QAC/D,OAAO,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC,CAAC,EAAE,CAAC;AAEL,SAAS,UAAU,CAAC,IAAY,EAAE,QAAgB,EAAE,GAAW;IAC7D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACxC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1D,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,6EAA6E;AAC7E,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAC,0BAA0B,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;AAErF,4BAA4B;AAC5B,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAC,qBAAqB,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;AAE3E;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,UAAU,CAAC,gCAAgC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;AAEzF,qDAAqD;AACrD,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC,sBAAsB,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAEpE,sFAAsF;AACtF,MAAM,CAAC,MAAM,cAAc,GAAG,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC;AAE/F;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,4CAA4C,CAAC;AACtE,MAAM,CAAC,MAAM,eAAe,GAC1B,wEAAwE,CAAC;AAE3E,oDAAoD;AACpD,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,SAAS;IACT,WAAW;IACX,QAAQ;IACR,OAAO;IACP,UAAU;IACV,SAAS;IACT,QAAQ;IACR,eAAe;IACf,UAAU;IACV,KAAK;IACL,QAAQ;IACR,gBAAgB;IAChB,QAAQ;IACR,OAAO;IACP,kBAAkB;IAClB,yBAAyB;CACjB,CAAC;AAEX,wDAAwD;AACxD,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,SAAS;IACT,UAAU;IACV,gBAAgB;IAChB,QAAQ;IACR,QAAQ;IACR,UAAU;IACV,SAAS;IACT,OAAO;CACC,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,QAAQ,EAAE;QACR,IAAI;QACJ,QAAQ;QACR,MAAM;QACN,QAAQ;QACR,OAAO;QACP,eAAe;QACf,UAAU;QACV,aAAa;QACb,YAAY;QACZ,QAAQ;QACR,YAAY;QACZ,UAAU;QACV,aAAa;QACb,SAAS;QACT,UAAU;QACV,YAAY;QACZ,WAAW;KACZ;IACD,QAAQ,EAAE;QACR,IAAI;QACJ,QAAQ;QACR,cAAc;QACd,cAAc;QACd,YAAY;QACZ,WAAW;QACX,QAAQ;QACR,SAAS;QACT,QAAQ;QACR,UAAU;QACV,MAAM;QACN,SAAS;QACT,UAAU;QACV,gBAAgB;QAChB,UAAU;KACX;IACD,QAAQ,EAAE;QACR,IAAI;QACJ,QAAQ;QACR,MAAM;QACN,aAAa;QACb,MAAM;QACN,YAAY;QACZ,YAAY;QACZ,aAAa;QACb,YAAY;QACZ,UAAU;QACV,OAAO;QACP,aAAa;QACb,UAAU;KACX;IACD,OAAO,EAAE;QACP,IAAI;QACJ,cAAc;QACd,YAAY;QACZ,YAAY;QACZ,WAAW;QACX,YAAY;QACZ,QAAQ;QACR,SAAS;QACT,QAAQ;QACR,QAAQ;QACR,UAAU;QACV,MAAM;QACN,SAAS;KACV;IACD,OAAO,EAAE;QACP,IAAI;QACJ,MAAM;QACN,aAAa;QACb,QAAQ;QACR,QAAQ;QACR,aAAa;QACb,eAAe;QACf,aAAa;QACb,iBAAiB;QACjB,eAAe;KAChB;IACD,OAAO,EAAE;QACP,IAAI;QACJ,aAAa;QACb,QAAQ;QACR,YAAY;QACZ,MAAM;QACN,UAAU;QACV,WAAW;QACX,QAAQ;QACR,gBAAgB;QAChB,UAAU;KACX;IACD,YAAY,EAAE;QACZ,IAAI;QACJ,QAAQ;QACR,aAAa;QACb,cAAc;QACd,cAAc;QACd,aAAa;QACb,aAAa;QACb,aAAa;QACb,YAAY;QACZ,YAAY;QACZ,UAAU;KACX;IACD,UAAU,EAAE,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,CAAC;IACjG,IAAI,EAAE;QACJ,IAAI;QACJ,MAAM;QACN,QAAQ;QACR,gBAAgB;QAChB,UAAU;QACV,UAAU;QACV,UAAU;QACV,QAAQ;QACR,WAAW;QACX,aAAa;QACb,YAAY;QACZ,UAAU;KACX;IACD,KAAK,EAAE;QACL,IAAI;QACJ,aAAa;QACb,aAAa;QACb,MAAM;QACN,WAAW;QACX,YAAY;QACZ,aAAa;QACb,sBAAsB;KACvB;IACD,YAAY,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC;IACnD,aAAa,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,aAAa,CAAC;IACtE,YAAY,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,CAAC;IAC5F,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,CAAC;
|
|
1
|
+
{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Hosted mode: the account overview tool and the instructions that explain
|
|
3
|
+
* accounts to the model.
|
|
4
|
+
*/
|
|
5
|
+
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
6
|
+
import type { TenantConfig } from "./config.js";
|
|
7
|
+
import type { ConnectionRow } from "./store.js";
|
|
8
|
+
export declare function accountInstructions(tenants: TenantConfig[], connections: ConnectionRow[]): string;
|
|
9
|
+
export declare function registerAccountTools(server: McpServer, deps: {
|
|
10
|
+
tenants: TenantConfig[];
|
|
11
|
+
connections: ConnectionRow[];
|
|
12
|
+
manageLink: () => string;
|
|
13
|
+
}): void;
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Hosted mode: the account overview tool and the instructions that explain
|
|
3
|
+
* accounts to the model.
|
|
4
|
+
*/
|
|
5
|
+
import { registerRead } from "../tools/registry.js";
|
|
6
|
+
function statusOf(connection) {
|
|
7
|
+
if (!connection)
|
|
8
|
+
return "not_connected";
|
|
9
|
+
return connection.broken_reason ? "expired" : "connected";
|
|
10
|
+
}
|
|
11
|
+
export function accountInstructions(tenants, connections) {
|
|
12
|
+
const usable = tenants.filter((t) => statusOf(connections.find((c) => c.tenant_id === t.id)) === "connected");
|
|
13
|
+
const lines = [
|
|
14
|
+
"# Accounts",
|
|
15
|
+
"",
|
|
16
|
+
"This server reaches several easybill accounts (companies). Every tool takes an `account` argument.",
|
|
17
|
+
];
|
|
18
|
+
if (usable.length === 0) {
|
|
19
|
+
lines.push("", "No account is connected for this user yet. Call `easybill_list_accounts` and give the user the link to connect one.");
|
|
20
|
+
}
|
|
21
|
+
else {
|
|
22
|
+
lines.push("", "Connected for this user:", ...usable.map((t) => `- \`${t.id}\` = ${t.name} (${t.writes ? "read & write" : "read-only"})`), "", "- Customers, documents, IDs and numbers belong to ONE account. Never reuse an ID from one account in a call on another.", "- If the request does not make clear which account is meant and more than one is connected, ask the user.", "- If the user needs an account that is not connected, or a call reports an expired connection, call " +
|
|
23
|
+
"`easybill_list_accounts` and give them the link.");
|
|
24
|
+
}
|
|
25
|
+
return lines.join("\n");
|
|
26
|
+
}
|
|
27
|
+
export function registerAccountTools(server, deps) {
|
|
28
|
+
registerRead(server, {
|
|
29
|
+
name: "easybill_list_accounts",
|
|
30
|
+
title: "List easybill accounts and connection status",
|
|
31
|
+
description: "List the easybill accounts (companies) this server can reach, which of them the user has connected, " +
|
|
32
|
+
"and whether each allows writes. Also returns a link where the user connects more accounts or " +
|
|
33
|
+
"reconnects an expired one with their own easybill login.\n\n" +
|
|
34
|
+
"Call this when the user asks which accounts are available, names an account that is not connected, " +
|
|
35
|
+
"or a tool reports an expired connection. Give the user the link — it is valid for 30 minutes. " +
|
|
36
|
+
"Costs no easybill request.",
|
|
37
|
+
inputSchema: {},
|
|
38
|
+
accountless: true,
|
|
39
|
+
}, async () => {
|
|
40
|
+
const byTenant = new Map(deps.connections.map((c) => [c.tenant_id, c]));
|
|
41
|
+
const accounts = deps.tenants.map((t) => {
|
|
42
|
+
const connection = byTenant.get(t.id);
|
|
43
|
+
return {
|
|
44
|
+
account: t.id,
|
|
45
|
+
name: t.name,
|
|
46
|
+
status: statusOf(connection),
|
|
47
|
+
writes: t.writes,
|
|
48
|
+
...(connection?.login_label ? { connected_as: connection.login_label } : {}),
|
|
49
|
+
};
|
|
50
|
+
});
|
|
51
|
+
const link = deps.manageLink();
|
|
52
|
+
const label = {
|
|
53
|
+
connected: "connected",
|
|
54
|
+
expired: "EXPIRED — reconnect via the link",
|
|
55
|
+
not_connected: "not connected",
|
|
56
|
+
};
|
|
57
|
+
const text = [
|
|
58
|
+
"# easybill accounts",
|
|
59
|
+
"",
|
|
60
|
+
...accounts.map((a) => `- **${a.name}** (\`${a.account}\`): ${label[a.status]}` +
|
|
61
|
+
`${a.connected_as ? ` as ${a.connected_as}` : ""}, ${a.writes ? "read & write" : "read-only"}`),
|
|
62
|
+
"",
|
|
63
|
+
`Connect or reconnect accounts here (valid 30 minutes): ${link}`,
|
|
64
|
+
"A newly connected account works from the next tool call on — pass its id as `account` even if an " +
|
|
65
|
+
"older tool list does not show it yet.",
|
|
66
|
+
].join("\n");
|
|
67
|
+
return { content: [{ type: "text", text }], structuredContent: { accounts, connect_url: link } };
|
|
68
|
+
});
|
|
69
|
+
}
|
|
70
|
+
//# sourceMappingURL=accounts.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"accounts.js","sourceRoot":"","sources":["../../src/hosted/accounts.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Configuration for hosted (HTTP + OAuth) mode.
|
|
3
|
+
*
|
|
4
|
+
* Hosted mode serves one MCP endpoint for a whole company. Each person connects
|
|
5
|
+
* the easybill accounts listed in the tenant file with their own easybill login
|
|
6
|
+
* (easybill's OAuth); nobody handles API keys.
|
|
7
|
+
*/
|
|
8
|
+
export declare function defaultScopes(writes: boolean): string[];
|
|
9
|
+
export interface TenantConfig {
|
|
10
|
+
/** Slug used as the `account` argument, e.g. "acme". */
|
|
11
|
+
id: string;
|
|
12
|
+
/** Shown on the connect page and to the model. */
|
|
13
|
+
name: string;
|
|
14
|
+
/** Allow create/update/delete tools against this account. */
|
|
15
|
+
writes: boolean;
|
|
16
|
+
/** Client-side throttle, shared by everyone using this account. */
|
|
17
|
+
rateLimitPerMinute: number;
|
|
18
|
+
/** OAuth scopes requested from easybill. */
|
|
19
|
+
scopes: string[];
|
|
20
|
+
/**
|
|
21
|
+
* Optional check that the person logged into the right easybill account:
|
|
22
|
+
* every listed access-token claim must equal (or be one of) the given value(s).
|
|
23
|
+
* Without it, any easybill login is accepted for this tenant.
|
|
24
|
+
*/
|
|
25
|
+
match?: Record<string, string | number | (string | number)[]>;
|
|
26
|
+
}
|
|
27
|
+
export interface HostedConfig {
|
|
28
|
+
/** Public base URL, e.g. https://easybill-mcp.example.com. The MCP endpoint is <publicUrl>/mcp. */
|
|
29
|
+
publicUrl: URL;
|
|
30
|
+
mcpUrl: URL;
|
|
31
|
+
host: string;
|
|
32
|
+
port: number;
|
|
33
|
+
/** Encrypts stored easybill tokens and signs the browser cookie. */
|
|
34
|
+
secret: string;
|
|
35
|
+
dbPath: string;
|
|
36
|
+
tenants: TenantConfig[];
|
|
37
|
+
/**
|
|
38
|
+
* How people connect an easybill account:
|
|
39
|
+
* - "apikey" (default): they paste their personal easybill API key.
|
|
40
|
+
* - "oauth": they log in through easybill's OAuth. easybill only allows this
|
|
41
|
+
* for OAuth clients it has issued (dynamic registration is allowlisted).
|
|
42
|
+
*/
|
|
43
|
+
connectMode: "apikey" | "oauth";
|
|
44
|
+
upstream: {
|
|
45
|
+
/** easybill's OAuth issuer; endpoints are discovered from its metadata. */
|
|
46
|
+
issuer: string;
|
|
47
|
+
clientId?: string;
|
|
48
|
+
clientSecret?: string;
|
|
49
|
+
};
|
|
50
|
+
/**
|
|
51
|
+
* Cloudflare Access in front of the connect pages: when set, /connect/* only
|
|
52
|
+
* answers requests carrying a valid Access token for this application.
|
|
53
|
+
*/
|
|
54
|
+
cloudflareAccess?: {
|
|
55
|
+
issuer: string;
|
|
56
|
+
audience: string;
|
|
57
|
+
};
|
|
58
|
+
/**
|
|
59
|
+
* Icon served as favicon and announced in the MCP server info, read from a
|
|
60
|
+
* file outside the image (e.g. a Coolify file mount). claude.ai shows the
|
|
61
|
+
* domain's favicon next to a custom connector.
|
|
62
|
+
*/
|
|
63
|
+
icon?: {
|
|
64
|
+
path: string;
|
|
65
|
+
mimeType: string;
|
|
66
|
+
extension: "svg" | "png" | "ico";
|
|
67
|
+
};
|
|
68
|
+
/** Lifetime of the access tokens this server issues to MCP clients. */
|
|
69
|
+
accessTokenTtlSeconds: number;
|
|
70
|
+
/** Lifetime of the refresh tokens this server issues to MCP clients. */
|
|
71
|
+
refreshTokenTtlSeconds: number;
|
|
72
|
+
}
|
|
73
|
+
export declare function loadHostedConfig(env?: NodeJS.ProcessEnv): HostedConfig;
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Configuration for hosted (HTTP + OAuth) mode.
|
|
3
|
+
*
|
|
4
|
+
* Hosted mode serves one MCP endpoint for a whole company. Each person connects
|
|
5
|
+
* the easybill accounts listed in the tenant file with their own easybill login
|
|
6
|
+
* (easybill's OAuth); nobody handles API keys.
|
|
7
|
+
*/
|
|
8
|
+
import { readFileSync } from "node:fs";
|
|
9
|
+
/**
|
|
10
|
+
* easybill plans with REST API access and their request limits (easybill.de/preise).
|
|
11
|
+
* PLUS and BUSINESS are the former names, still named in easybill's API docs.
|
|
12
|
+
*/
|
|
13
|
+
const PLAN_LIMITS = { PROFESSIONAL: 10, PREMIUM: 60, PLUS: 10, BUSINESS: 60 };
|
|
14
|
+
/** Plans without REST API access. */
|
|
15
|
+
const PLANS_WITHOUT_API = new Set(["FREE", "STARTER"]);
|
|
16
|
+
/**
|
|
17
|
+
* Scopes requested from easybill, per resource the tools use. `stocks` has no
|
|
18
|
+
* scope of its own in easybill's list; it travels with `position`.
|
|
19
|
+
*/
|
|
20
|
+
const RESOURCE_SCOPES = [
|
|
21
|
+
"customer",
|
|
22
|
+
"contact",
|
|
23
|
+
"customer-group",
|
|
24
|
+
"document",
|
|
25
|
+
"document-payment",
|
|
26
|
+
"position",
|
|
27
|
+
"project",
|
|
28
|
+
"time-tracking",
|
|
29
|
+
"attachment",
|
|
30
|
+
"text-template",
|
|
31
|
+
"incoming-document",
|
|
32
|
+
];
|
|
33
|
+
/** Read-only resources: no write scope exists or none is needed. */
|
|
34
|
+
const READ_ONLY_SCOPES = ["pdf-templates.readonly", "login.readonly"];
|
|
35
|
+
export function defaultScopes(writes) {
|
|
36
|
+
const resource = RESOURCE_SCOPES.map((r) => (writes ? r : `${r}.readonly`));
|
|
37
|
+
return [...resource, ...READ_ONLY_SCOPES];
|
|
38
|
+
}
|
|
39
|
+
const SLUG = /^[a-z0-9][a-z0-9_-]{0,39}$/;
|
|
40
|
+
function fail(message) {
|
|
41
|
+
throw new Error(`Hosted mode configuration: ${message}`);
|
|
42
|
+
}
|
|
43
|
+
function parseTenants(raw, source) {
|
|
44
|
+
let parsed;
|
|
45
|
+
try {
|
|
46
|
+
parsed = JSON.parse(raw);
|
|
47
|
+
}
|
|
48
|
+
catch (error) {
|
|
49
|
+
fail(`${source} is not valid JSON (${error instanceof Error ? error.message : String(error)})`);
|
|
50
|
+
}
|
|
51
|
+
const list = Array.isArray(parsed)
|
|
52
|
+
? parsed
|
|
53
|
+
: parsed?.tenants;
|
|
54
|
+
if (!Array.isArray(list) || list.length === 0) {
|
|
55
|
+
fail(`${source} must contain a non-empty "tenants" array`);
|
|
56
|
+
}
|
|
57
|
+
const seen = new Set();
|
|
58
|
+
return list.map((entry, index) => {
|
|
59
|
+
const t = (entry ?? {});
|
|
60
|
+
const where = `${source} tenants[${index}]`;
|
|
61
|
+
// Case-insensitive: "HMD" becomes "hmd", the value the model passes as `account`.
|
|
62
|
+
const id = typeof t.id === "string" ? t.id.trim().toLowerCase() : "";
|
|
63
|
+
if (!SLUG.test(id))
|
|
64
|
+
fail(`${where}.id must be a slug (letters, digits, - and _), got ${JSON.stringify(t.id)}`);
|
|
65
|
+
if (seen.has(id))
|
|
66
|
+
fail(`${where}.id "${id}" is used twice`);
|
|
67
|
+
seen.add(id);
|
|
68
|
+
const name = typeof t.name === "string" && t.name.trim() ? t.name.trim() : id;
|
|
69
|
+
const writes = t.writes === true;
|
|
70
|
+
let rateLimitPerMinute = 10;
|
|
71
|
+
if (typeof t.rate_limit_per_minute === "number" && t.rate_limit_per_minute >= 1) {
|
|
72
|
+
rateLimitPerMinute = Math.floor(t.rate_limit_per_minute);
|
|
73
|
+
}
|
|
74
|
+
else if (t.plan !== undefined) {
|
|
75
|
+
const plan = String(t.plan).toUpperCase();
|
|
76
|
+
if (PLANS_WITHOUT_API.has(plan)) {
|
|
77
|
+
fail(`${where}: easybill's ${t.plan} plan has no REST API access — Professional or Premium is required`);
|
|
78
|
+
}
|
|
79
|
+
const limit = PLAN_LIMITS[plan];
|
|
80
|
+
if (limit === undefined)
|
|
81
|
+
fail(`${where}.plan must be PROFESSIONAL or PREMIUM, got ${JSON.stringify(t.plan)}`);
|
|
82
|
+
rateLimitPerMinute = limit;
|
|
83
|
+
}
|
|
84
|
+
let scopes = defaultScopes(writes);
|
|
85
|
+
if (t.scopes !== undefined) {
|
|
86
|
+
if (!Array.isArray(t.scopes) || !t.scopes.every((s) => typeof s === "string")) {
|
|
87
|
+
fail(`${where}.scopes must be an array of strings`);
|
|
88
|
+
}
|
|
89
|
+
scopes = t.scopes;
|
|
90
|
+
}
|
|
91
|
+
let match;
|
|
92
|
+
if (t.match !== undefined) {
|
|
93
|
+
if (!t.match || typeof t.match !== "object" || Array.isArray(t.match)) {
|
|
94
|
+
fail(`${where}.match must be an object of claim -> value`);
|
|
95
|
+
}
|
|
96
|
+
match = t.match;
|
|
97
|
+
}
|
|
98
|
+
return { id, name, writes, rateLimitPerMinute, scopes, ...(match ? { match } : {}) };
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
function intEnv(env, name, fallback) {
|
|
102
|
+
const raw = env[name];
|
|
103
|
+
if (!raw)
|
|
104
|
+
return fallback;
|
|
105
|
+
const value = Number.parseInt(raw, 10);
|
|
106
|
+
if (Number.isNaN(value) || value < 1)
|
|
107
|
+
fail(`${name} must be a positive integer`);
|
|
108
|
+
return value;
|
|
109
|
+
}
|
|
110
|
+
export function loadHostedConfig(env = process.env) {
|
|
111
|
+
const rawUrl = env.EASYBILL_PUBLIC_URL?.trim();
|
|
112
|
+
if (!rawUrl)
|
|
113
|
+
fail("EASYBILL_PUBLIC_URL is required, e.g. https://easybill-mcp.example.com");
|
|
114
|
+
let publicUrl;
|
|
115
|
+
try {
|
|
116
|
+
publicUrl = new URL(rawUrl.replace(/\/+$/, ""));
|
|
117
|
+
}
|
|
118
|
+
catch {
|
|
119
|
+
fail(`EASYBILL_PUBLIC_URL is not a valid URL: ${rawUrl}`);
|
|
120
|
+
}
|
|
121
|
+
const localhost = ["localhost", "127.0.0.1", "[::1]"].includes(publicUrl.hostname);
|
|
122
|
+
// Same escape hatch the MCP SDK uses for its issuer check — for LAN tests only:
|
|
123
|
+
// API keys and tokens then travel unencrypted.
|
|
124
|
+
const insecureAllowed = /^(1|true)$/.test(env.MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL ?? "");
|
|
125
|
+
if (publicUrl.protocol !== "https:" && !localhost && !insecureAllowed) {
|
|
126
|
+
fail("EASYBILL_PUBLIC_URL must use https (http is only allowed for localhost; for a test in a " +
|
|
127
|
+
"trusted local network set MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL=true)");
|
|
128
|
+
}
|
|
129
|
+
const secret = env.EASYBILL_MCP_SECRET ?? "";
|
|
130
|
+
if (secret.length < 32) {
|
|
131
|
+
fail("EASYBILL_MCP_SECRET must be at least 32 characters (e.g. `openssl rand -base64 48`)");
|
|
132
|
+
}
|
|
133
|
+
let tenants;
|
|
134
|
+
if (env.EASYBILL_TENANTS?.trim()) {
|
|
135
|
+
tenants = parseTenants(env.EASYBILL_TENANTS, "EASYBILL_TENANTS");
|
|
136
|
+
}
|
|
137
|
+
else if (env.EASYBILL_TENANTS_FILE?.trim()) {
|
|
138
|
+
const file = env.EASYBILL_TENANTS_FILE.trim();
|
|
139
|
+
let raw;
|
|
140
|
+
try {
|
|
141
|
+
raw = readFileSync(file, "utf8");
|
|
142
|
+
}
|
|
143
|
+
catch (error) {
|
|
144
|
+
fail(`cannot read EASYBILL_TENANTS_FILE ${file} (${error instanceof Error ? error.message : String(error)})`);
|
|
145
|
+
}
|
|
146
|
+
tenants = parseTenants(raw, file);
|
|
147
|
+
}
|
|
148
|
+
else {
|
|
149
|
+
fail("set EASYBILL_TENANTS_FILE (path to a JSON file) or EASYBILL_TENANTS (inline JSON)");
|
|
150
|
+
}
|
|
151
|
+
const clientId = env.EASYBILL_OAUTH_CLIENT_ID?.trim();
|
|
152
|
+
const clientSecret = env.EASYBILL_OAUTH_CLIENT_SECRET?.trim();
|
|
153
|
+
const rawMode = env.EASYBILL_CONNECT_MODE?.trim().toLowerCase();
|
|
154
|
+
if (rawMode && rawMode !== "apikey" && rawMode !== "oauth") {
|
|
155
|
+
fail(`EASYBILL_CONNECT_MODE must be "apikey" or "oauth", got ${JSON.stringify(rawMode)}`);
|
|
156
|
+
}
|
|
157
|
+
const connectMode = rawMode || (clientId ? "oauth" : "apikey");
|
|
158
|
+
const teamDomain = env.EASYBILL_CF_ACCESS_TEAM_DOMAIN?.trim();
|
|
159
|
+
const accessAud = env.EASYBILL_CF_ACCESS_AUD?.trim();
|
|
160
|
+
if (Boolean(teamDomain) !== Boolean(accessAud)) {
|
|
161
|
+
fail("set both EASYBILL_CF_ACCESS_TEAM_DOMAIN and EASYBILL_CF_ACCESS_AUD, or neither");
|
|
162
|
+
}
|
|
163
|
+
let cloudflareAccess;
|
|
164
|
+
if (teamDomain && accessAud) {
|
|
165
|
+
// Accepts "team", "team.cloudflareaccess.com" or a full URL.
|
|
166
|
+
const issuer = teamDomain.includes("://")
|
|
167
|
+
? teamDomain
|
|
168
|
+
: `https://${teamDomain.includes(".") ? teamDomain : `${teamDomain}.cloudflareaccess.com`}`;
|
|
169
|
+
cloudflareAccess = { issuer: issuer.replace(/\/+$/, ""), audience: accessAud };
|
|
170
|
+
}
|
|
171
|
+
let icon;
|
|
172
|
+
const iconPath = env.EASYBILL_ICON_PATH?.trim();
|
|
173
|
+
if (iconPath) {
|
|
174
|
+
const extension = /\.(svg|png|ico)$/i.exec(iconPath)?.[1]?.toLowerCase();
|
|
175
|
+
if (!extension)
|
|
176
|
+
fail(`EASYBILL_ICON_PATH must end in .svg, .png or .ico, got ${JSON.stringify(iconPath)}`);
|
|
177
|
+
const mimeType = { svg: "image/svg+xml", png: "image/png", ico: "image/x-icon" }[extension];
|
|
178
|
+
icon = { path: iconPath, mimeType, extension };
|
|
179
|
+
}
|
|
180
|
+
return {
|
|
181
|
+
publicUrl,
|
|
182
|
+
mcpUrl: new URL(`${publicUrl.href.replace(/\/+$/, "")}/mcp`),
|
|
183
|
+
host: env.HOST?.trim() || "0.0.0.0",
|
|
184
|
+
port: intEnv(env, "PORT", 3000),
|
|
185
|
+
secret,
|
|
186
|
+
dbPath: env.EASYBILL_DB_PATH?.trim() || "./data/easybill-mcp.sqlite",
|
|
187
|
+
tenants,
|
|
188
|
+
connectMode,
|
|
189
|
+
upstream: {
|
|
190
|
+
issuer: (env.EASYBILL_OAUTH_ISSUER?.trim() || "https://api.easybill.de").replace(/\/+$/, ""),
|
|
191
|
+
...(clientId ? { clientId } : {}),
|
|
192
|
+
...(clientSecret ? { clientSecret } : {}),
|
|
193
|
+
},
|
|
194
|
+
...(cloudflareAccess ? { cloudflareAccess } : {}),
|
|
195
|
+
...(icon ? { icon } : {}),
|
|
196
|
+
accessTokenTtlSeconds: intEnv(env, "EASYBILL_MCP_ACCESS_TOKEN_TTL", 3600),
|
|
197
|
+
refreshTokenTtlSeconds: intEnv(env, "EASYBILL_MCP_REFRESH_TOKEN_TTL", 90 * 24 * 3600),
|
|
198
|
+
};
|
|
199
|
+
}
|
|
200
|
+
//# sourceMappingURL=config.js.map
|