easybill-mcp 1.0.2 → 1.2.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 (72) hide show
  1. package/README.md +123 -15
  2. package/dist/constants.d.ts +2 -1
  3. package/dist/constants.js +18 -1
  4. package/dist/constants.js.map +1 -1
  5. package/dist/hosted/accounts.d.ts +13 -0
  6. package/dist/hosted/accounts.js +70 -0
  7. package/dist/hosted/accounts.js.map +1 -0
  8. package/dist/hosted/config.d.ts +73 -0
  9. package/dist/hosted/config.js +200 -0
  10. package/dist/hosted/config.js.map +1 -0
  11. package/dist/hosted/http.d.ts +23 -0
  12. package/dist/hosted/http.js +524 -0
  13. package/dist/hosted/http.js.map +1 -0
  14. package/dist/hosted/pages.d.ts +22 -0
  15. package/dist/hosted/pages.js +130 -0
  16. package/dist/hosted/pages.js.map +1 -0
  17. package/dist/hosted/provider.d.ts +54 -0
  18. package/dist/hosted/provider.js +190 -0
  19. package/dist/hosted/provider.js.map +1 -0
  20. package/dist/hosted/store.d.ts +119 -0
  21. package/dist/hosted/store.js +254 -0
  22. package/dist/hosted/store.js.map +1 -0
  23. package/dist/hosted/upstream.d.ts +68 -0
  24. package/dist/hosted/upstream.js +280 -0
  25. package/dist/hosted/upstream.js.map +1 -0
  26. package/dist/index.d.ts +5 -1
  27. package/dist/index.js +19 -24
  28. package/dist/index.js.map +1 -1
  29. package/dist/instructions.d.ts +1 -1
  30. package/dist/instructions.js +16 -1
  31. package/dist/instructions.js.map +1 -1
  32. package/dist/server.d.ts +26 -0
  33. package/dist/server.js +47 -0
  34. package/dist/server.js.map +1 -0
  35. package/dist/services/client.d.ts +43 -4
  36. package/dist/services/client.js +35 -9
  37. package/dist/services/client.js.map +1 -1
  38. package/dist/services/format.d.ts +17 -4
  39. package/dist/services/format.js.map +1 -1
  40. package/dist/tools/catalog.d.ts +2 -2
  41. package/dist/tools/catalog.js.map +1 -1
  42. package/dist/tools/crud.d.ts +2 -2
  43. package/dist/tools/crud.js.map +1 -1
  44. package/dist/tools/customers.d.ts +2 -2
  45. package/dist/tools/customers.js +12 -4
  46. package/dist/tools/customers.js.map +1 -1
  47. package/dist/tools/documents.d.ts +2 -2
  48. package/dist/tools/documents.js +73 -43
  49. package/dist/tools/documents.js.map +1 -1
  50. package/dist/tools/files-io.d.ts +44 -0
  51. package/dist/tools/files-io.js +173 -0
  52. package/dist/tools/files-io.js.map +1 -0
  53. package/dist/tools/files.d.ts +2 -2
  54. package/dist/tools/files.js +9 -27
  55. package/dist/tools/files.js.map +1 -1
  56. package/dist/tools/finance.d.ts +2 -2
  57. package/dist/tools/finance.js.map +1 -1
  58. package/dist/tools/incoming.d.ts +11 -0
  59. package/dist/tools/incoming.js +222 -0
  60. package/dist/tools/incoming.js.map +1 -0
  61. package/dist/tools/meta.d.ts +2 -2
  62. package/dist/tools/meta.js +14 -6
  63. package/dist/tools/meta.js.map +1 -1
  64. package/dist/tools/registry.d.ts +40 -9
  65. package/dist/tools/registry.js +75 -12
  66. package/dist/tools/registry.js.map +1 -1
  67. package/dist/tools/search.d.ts +9 -8
  68. package/dist/tools/search.js +49 -17
  69. package/dist/tools/search.js.map +1 -1
  70. package/dist/tools/work.d.ts +2 -2
  71. package/dist/tools/work.js.map +1 -1
  72. 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
- - **54 tools** across 12 easybill resources
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 PLUS plan or **60** on BUSINESS.
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
- Some clients (ChatGPT connectors, hosted agent platforms) accept only HTTP/SSE endpoints, not
147
- stdio. Bridge it locally:
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 PLUS, `60` for BUSINESS. |
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**: fuzzy search by name, email or number |
378
+ | `easybill_find_customer` | read — **start here**: search customers or suppliers by name, email or number |
288
379
 
289
- The easybill API has no full-text search, so this tool tries exact filters first, then pages
290
- the customer list and scores candidates locally. It tolerates legal forms (`GmbH & Co. KG`),
291
- punctuation (`M.B. MUSTERMANN` vs `MB Mustermann`), umlauts and word order.
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
- | `easybill_download_document` | read — saves PDF / ZUGFeRD / XRechnung to disk |
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 PLUS** and **60 on BUSINESS**. The server throttles
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
- ### No fuzzy customer search
519
+ ### Full-text search vs. filters
412
520
 
413
- The easybill API has no full-text search. Customer filters match **exact** values (each
414
- accepts several comma-separated). To find a customer by partial name, either use the exact
415
- spelling or page through and match locally.
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
 
@@ -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 (PLUS) and 60 req/min (BUSINESS).
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 (PLUS) and 60 req/min (BUSINESS).
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
@@ -1 +1 @@
1
- {"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"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"}
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