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.
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
@@ -0,0 +1,222 @@
1
+ /**
2
+ * Incoming documents (Eingangsbelege): supplier invoices and credit notes that
3
+ * arrive by upload or e-mail, are extracted by easybill in the background, and
4
+ * are then reviewed and completed. API 1.100-1.102.
5
+ *
6
+ * Unlike every other easybill resource these use UUIDs, not numeric IDs, so
7
+ * they are written out here instead of going through the CRUD factory.
8
+ */
9
+ import { z } from "zod";
10
+ import { DATE_RANGE_HINT, SUMMARY_FIELDS } from "../constants.js";
11
+ import { dataSchema, fieldsSchema, listBaseShape, responseFormatSchema } from "../schemas/common.js";
12
+ import { buildListResponse, buildMutationResponse, buildRecordResponse, textResult, } from "../services/format.js";
13
+ import { deliverFile, downloadNote, downloadShape, multipartFile, readUpload, uploadShape } from "./files-io.js";
14
+ import { registerRead, registerWrite } from "./registry.js";
15
+ /** Validated before it goes into a URL path. */
16
+ const uuid = (what) => z
17
+ .string()
18
+ .regex(/^[0-9a-fA-F-]{8,64}$/, "must be a UUID")
19
+ .describe(`UUID of the ${what} (incoming documents use UUIDs, not numbers).`);
20
+ const MONEY = "Amounts are INTEGERS IN CENTS (11900 = 119.00 EUR).";
21
+ const UPDATE_HINT = `${MONEY}
22
+
23
+ Editable fields:
24
+ - document_type: 'INVOICE' or 'CREDIT_NOTE' (required before completing)
25
+ - supplier_id (integer): the easybill contact (contactType SUPPLIER) this document is from
26
+ - external_number (string): the supplier's own document number
27
+ - issue_date, due_date, delivery_date (YYYY-MM-DD)
28
+ - currency_code (string), total_net_amount, total_gross_amount (integer, cents)
29
+ - accounting_positions (array, REPLACES all positions): each { net_amount (cents, required),
30
+ tax_amount (cents), tax_rate (decimal string, e.g. "19.00"), financial_accounting_account (string),
31
+ id (to modify an existing position) }
32
+ - supplier (object): name, email, vat_id, iban, bic, address_line_1..3, address_post_code,
33
+ address_city_name, address_country_id
34
+
35
+ Read-only (ignored): status, document_number, is_paid, payments, interface.
36
+ Allowed while status is DRAFT or DONE.`;
37
+ const format = (args) => args.response_format ?? "markdown";
38
+ const path = (id) => `/incoming-documents/${encodeURIComponent(String(id))}`;
39
+ export function registerIncomingDocumentTools(server, client) {
40
+ registerRead(server, {
41
+ name: "easybill_list_incoming_documents",
42
+ title: "List incoming documents (Eingangsbelege)",
43
+ description: "List incoming documents — supplier invoices and credit notes received by upload or e-mail.\n\n" +
44
+ "Status: PREPARING/PROCESSING (easybill is still extracting the data), DRAFT (extracted, to be " +
45
+ "reviewed), DONE (completed, has an internal 'document_number'), ERROR or VIRUS.\n\n" +
46
+ "To find one by supplier name, number or a word, use easybill_search_incoming_documents. " +
47
+ `${MONEY}\n\n` +
48
+ "Returns: { total, count, page, pages, has_more, next_page, items[] }.",
49
+ inputSchema: {
50
+ ...listBaseShape,
51
+ created_at: z.string().optional().describe(`Filter by creation date. ${DATE_RANGE_HINT}`),
52
+ sort: z.enum(["ASC", "DESC"]).optional().describe("Sort by creation date; 'DESC' = newest first."),
53
+ },
54
+ }, async (args) => {
55
+ const filters = {};
56
+ if (args.created_at)
57
+ filters.created_at = args.created_at;
58
+ if (args.sort)
59
+ filters.sort = args.sort;
60
+ const list = await client.request("/incoming-documents", {
61
+ query: {
62
+ limit: args.limit,
63
+ page: args.page,
64
+ ...filters,
65
+ },
66
+ });
67
+ const fields = args.fields;
68
+ return buildListResponse({
69
+ list,
70
+ resource: "incoming documents",
71
+ defaultFields: SUMMARY_FIELDS.incomingDocument,
72
+ ...(fields ? { fields } : {}),
73
+ format: format(args),
74
+ filters,
75
+ });
76
+ });
77
+ registerRead(server, {
78
+ name: "easybill_search_incoming_documents",
79
+ title: "Search incoming documents (full text)",
80
+ description: "Full-text search over incoming documents (supplier invoices/credit notes): supplier name, " +
81
+ "the supplier's document number, amounts or other extracted text. One request.\n\n" +
82
+ "Returns: { total, count, page, pages, has_more, next_page, items[] }.",
83
+ inputSchema: {
84
+ query: z.string().min(2).max(200).describe("Search text, e.g. a supplier name or invoice number."),
85
+ limit: z.number().int().min(1).max(100).default(25).describe("Items per page (default 25)."),
86
+ page: z.number().int().min(1).default(1).describe("Page number, starting at 1."),
87
+ fields: fieldsSchema,
88
+ response_format: responseFormatSchema,
89
+ },
90
+ }, async (args) => {
91
+ const list = await client.request("/incoming-documents/search", {
92
+ query: { query: args.query, limit: args.limit, page: args.page },
93
+ });
94
+ const fields = args.fields;
95
+ return buildListResponse({
96
+ list,
97
+ resource: "incoming documents",
98
+ defaultFields: SUMMARY_FIELDS.incomingDocument,
99
+ ...(fields ? { fields } : {}),
100
+ format: format(args),
101
+ filters: { query: args.query },
102
+ });
103
+ });
104
+ registerRead(server, {
105
+ name: "easybill_get_incoming_document",
106
+ title: "Get incoming document",
107
+ description: "Fetch one incoming document with all fields: supplier, amounts, accounting positions (tax split) " +
108
+ `and recorded payments. ${MONEY}`,
109
+ inputSchema: { id: uuid("incoming document"), fields: fieldsSchema, response_format: responseFormatSchema },
110
+ }, async (args) => {
111
+ const record = await client.request(path(args.id));
112
+ const fields = args.fields;
113
+ return buildRecordResponse({
114
+ record,
115
+ resource: "incoming document",
116
+ defaultFields: SUMMARY_FIELDS.incomingDocument,
117
+ fields: fields ?? ["all"],
118
+ format: format(args),
119
+ });
120
+ });
121
+ registerRead(server, {
122
+ name: "easybill_list_incoming_document_files",
123
+ title: "List files of an incoming document",
124
+ description: "List the files (the original PDF/image and any others) attached to an incoming document. " +
125
+ "Use a file's 'id' with easybill_download_incoming_document_file.",
126
+ inputSchema: {
127
+ id: uuid("incoming document"),
128
+ limit: z.number().int().min(1).max(1000).default(25).describe("Items per page."),
129
+ page: z.number().int().min(1).default(1).describe("Page number, starting at 1."),
130
+ response_format: responseFormatSchema,
131
+ },
132
+ }, async (args) => {
133
+ const list = await client.request(`${path(args.id)}/files`, {
134
+ query: { limit: args.limit, page: args.page },
135
+ });
136
+ return buildListResponse({
137
+ list,
138
+ resource: "files",
139
+ defaultFields: ["id", "name", "extension", "size", "created_at"],
140
+ format: format(args),
141
+ });
142
+ });
143
+ registerRead(server, {
144
+ name: "easybill_download_incoming_document_file",
145
+ title: "Download a file of an incoming document",
146
+ description: "Download one file of an incoming document (find its id with easybill_list_incoming_document_files).\n\n" +
147
+ downloadNote(server),
148
+ inputSchema: {
149
+ id: uuid("incoming document"),
150
+ file_id: uuid("file"),
151
+ ...downloadShape(server, "/Users/me/Desktop/supplier-invoice.pdf"),
152
+ },
153
+ }, async (args) => {
154
+ const binary = await client.requestBinary(`${path(args.id)}/files/${encodeURIComponent(String(args.file_id))}/download`, { accept: "*/*" });
155
+ return deliverFile(server, args, binary, {
156
+ label: `File ${String(args.file_id)} of incoming document ${String(args.id)}`,
157
+ fileName: `incoming-${String(args.file_id)}`,
158
+ meta: { incoming_document_id: args.id, file_id: args.file_id },
159
+ });
160
+ });
161
+ registerWrite(server, {
162
+ name: "easybill_upload_incoming_document",
163
+ title: "Upload an incoming document",
164
+ description: "Upload a supplier invoice or credit note (PDF or image) as a new incoming document.\n\n" +
165
+ "easybill extracts supplier, amounts and dates in the background: the returned document has status " +
166
+ "PREPARING or PROCESSING. Fetch it again with easybill_get_incoming_document after a short while " +
167
+ "to see the extracted data (status DRAFT), review it, correct it with " +
168
+ "easybill_update_incoming_document and finish with easybill_complete_incoming_document.\n\n" +
169
+ "Fails with 426 when the plan's archive document limit is reached.",
170
+ inputSchema: { ...uploadShape(server), response_format: responseFormatSchema },
171
+ }, async (args) => {
172
+ const file = await readUpload(server, args);
173
+ if (typeof file === "string")
174
+ return textResult(file, true);
175
+ const { body, contentType } = multipartFile("file", file);
176
+ const record = await client.request("/incoming-documents", {
177
+ method: "POST",
178
+ rawBody: body,
179
+ headers: { "Content-Type": contentType },
180
+ });
181
+ return buildMutationResponse(`Uploaded ${file.fileName} (processing in the background) —`, "incoming document", record, format(args), SUMMARY_FIELDS.incomingDocument);
182
+ });
183
+ registerWrite(server, {
184
+ name: "easybill_update_incoming_document",
185
+ title: "Update an incoming document",
186
+ description: "Correct or complete the data of an incoming document. Only the fields in 'data' change.\n\n" +
187
+ `${UPDATE_HINT}\n\nReturns the updated incoming document.`,
188
+ inputSchema: {
189
+ id: uuid("incoming document"),
190
+ data: dataSchema(`Fields to change. ${UPDATE_HINT}`),
191
+ response_format: responseFormatSchema,
192
+ },
193
+ idempotent: true,
194
+ }, async (args) => {
195
+ const record = await client.request(path(args.id), { method: "PUT", body: args.data });
196
+ return buildMutationResponse("Updated", "incoming document", record, format(args), SUMMARY_FIELDS.incomingDocument);
197
+ });
198
+ registerWrite(server, {
199
+ name: "easybill_complete_incoming_document",
200
+ title: "Complete an incoming document",
201
+ description: "Mark an incoming document as DONE. easybill assigns the next internal 'document_number'.\n\n" +
202
+ "Requires a 'document_type' and balanced amounts: net amount plus the tax amounts of all accounting " +
203
+ "positions must equal the gross amount. Review the document with the user before completing it.",
204
+ inputSchema: { id: uuid("incoming document"), response_format: responseFormatSchema },
205
+ }, async (args) => {
206
+ const record = await client.request(`${path(args.id)}/done`, { method: "PUT" });
207
+ return buildMutationResponse("Completed", "incoming document", record, format(args), SUMMARY_FIELDS.incomingDocument);
208
+ });
209
+ registerWrite(server, {
210
+ name: "easybill_delete_incoming_document",
211
+ title: "Delete an incoming document",
212
+ description: "Permanently delete an incoming document in any status, including DONE. This cannot be undone. " +
213
+ "Fails with 409 while easybill is still processing it. Confirm with the user first.",
214
+ inputSchema: { id: uuid("incoming document") },
215
+ destructive: true,
216
+ idempotent: true,
217
+ }, async (args) => {
218
+ await client.request(path(args.id), { method: "DELETE" });
219
+ return textResult(`Deleted incoming document ${String(args.id)}.`);
220
+ });
221
+ }
222
+ //# sourceMappingURL=incoming.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"incoming.js","sourceRoot":"","sources":["../../src/tools/incoming.ts"],"names":[],"mappings":"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"}
@@ -6,5 +6,5 @@
6
6
  * agent could only report "no such tool" without explaining why.
7
7
  */
8
8
  import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
9
- import type { EasybillClient } from "../services/client.js";
10
- export declare function registerMetaTools(server: McpServer, client: EasybillClient): void;
9
+ import type { ApiClient } from "../services/client.js";
10
+ export declare function registerMetaTools(server: McpServer, client: ApiClient): void;
@@ -6,8 +6,8 @@
6
6
  * agent could only report "no such tool" without explaining why.
7
7
  */
8
8
  import { z } from "zod";
9
- import { API_BASE_URL, CHARACTER_LIMIT, RATE_LIMIT_PER_MINUTE, SERVER_VERSION, WRITES_ENABLED, } from "../constants.js";
10
- import { registerRead, registrationStats } from "./registry.js";
9
+ import { API_BASE_URL, CHARACTER_LIMIT, RATE_LIMIT_PER_MINUTE, SERVER_VERSION, } from "../constants.js";
10
+ import { registerRead, serverContext } from "./registry.js";
11
11
  export function registerMetaTools(server, client) {
12
12
  registerRead(server, {
13
13
  name: "easybill_get_server_info",
@@ -25,6 +25,10 @@ export function registerMetaTools(server, client) {
25
25
  .describe("Make one lightweight API call to verify the credentials. Costs one request against your rate limit."),
26
26
  },
27
27
  }, async (args) => {
28
+ const context = serverContext(server);
29
+ const registrationStats = context.stats;
30
+ const WRITES_ENABLED = context.writesEnabled;
31
+ const hosted = context.accounts !== undefined;
28
32
  let connection = "not tested";
29
33
  if (args.test_connection !== false) {
30
34
  try {
@@ -52,9 +56,13 @@ export function registerMetaTools(server, client) {
52
56
  };
53
57
  const modeLine = WRITES_ENABLED
54
58
  ? `Write mode is ENABLED — ${registrationStats.write} create/update/delete tools are available.`
55
- : `Write mode is DISABLED (read-only). ${registrationStats.skipped} create/update/delete tools ` +
56
- `are withheld. To enable them, set EASYBILL_ENABLE_WRITES=true in the server's environment ` +
57
- `and restart the MCP server.`;
59
+ : hosted
60
+ ? `Write mode is DISABLED (read-only). ${registrationStats.skipped} create/update/delete tools ` +
61
+ `are withheld because none of the connected accounts allows writes. Which accounts allow ` +
62
+ `writes is set by the server administrator in the tenant configuration.`
63
+ : `Write mode is DISABLED (read-only). ${registrationStats.skipped} create/update/delete tools ` +
64
+ `are withheld. To enable them, set EASYBILL_ENABLE_WRITES=true in the server's environment ` +
65
+ `and restart the MCP server.`;
58
66
  const text = [
59
67
  `# easybill MCP server v${SERVER_VERSION}`,
60
68
  "",
@@ -64,7 +72,7 @@ export function registerMetaTools(server, client) {
64
72
  `- **Read-only tools**: ${registrationStats.read}`,
65
73
  `- **Write tools**: ${registrationStats.write}`,
66
74
  `- **Rate limit (client-side throttle)**: ${RATE_LIMIT_PER_MINUTE} requests/minute`,
67
- ` easybill allows 10/min on PLUS and 60/min on BUSINESS — set EASYBILL_RATE_LIMIT_PER_MINUTE to match your plan.`,
75
+ ` easybill allows 10/min on Professional and 60/min on Premium — set EASYBILL_RATE_LIMIT_PER_MINUTE to match your plan.`,
68
76
  `- **Response character limit**: ${CHARACTER_LIMIT.toLocaleString("en-US")}`,
69
77
  `- **Connection**: ${connection}`,
70
78
  ].join("\n");
@@ -1 +1 @@
1
- {"version":3,"file":"meta.js","sourceRoot":"","sources":["../../src/tools/meta.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,cAAc,GACf,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEhE,MAAM,UAAU,iBAAiB,CAAC,MAAiB,EAAE,MAAsB;IACzE,YAAY,CACV,MAAM,EACN;QACE,IAAI,EAAE,0BAA0B;QAChC,KAAK,EAAE,uCAAuC;QAC9C,WAAW,EACT,0FAA0F;YAC1F,yFAAyF;YACzF,4EAA4E;YAC5E,6EAA6E;YAC7E,kFAAkF;YAClF,iDAAiD;QACnD,WAAW,EAAE;YACX,eAAe,EAAE,CAAC;iBACf,OAAO,EAAE;iBACT,OAAO,CAAC,IAAI,CAAC;iBACb,QAAQ,CACP,qGAAqG,CACtG;SACJ;KACF,EACD,KAAK,EAAE,IAAI,EAAuB,EAAE;QAElC,IAAI,UAAU,GAAG,YAAY,CAAC;QAC9B,IAAI,IAAI,CAAC,eAAe,KAAK,KAAK,EAAE,CAAC;YACnC,IAAI,CAAC;gBACH,6DAA6D;gBAC7D,MAAM,MAAM,CAAC,OAAO,CAAU,kBAAkB,EAAE,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC3E,UAAU,GAAG,uCAAuC,CAAC;YACvD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,uBAAuB,CAAC,CAAC;gBACjE,UAAU,GAAG,YAAY,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;YACnD,CAAC;QACH,CAAC;QAED,MAAM,MAAM,GAAG;YACb,cAAc,EAAE,cAAc;YAC9B,YAAY,EAAE,YAAY;YAC1B,cAAc,EAAE,cAAc;YAC9B,gBAAgB,EAAE;gBAChB,SAAS,EAAE,iBAAiB,CAAC,IAAI;gBACjC,KAAK,EAAE,iBAAiB,CAAC,KAAK;gBAC9B,gCAAgC,EAAE,iBAAiB,CAAC,OAAO;aAC5D;YACD,qBAAqB,EAAE,qBAAqB;YAC5C,eAAe,EAAE,eAAe;YAChC,UAAU;SACX,CAAC;QAEF,MAAM,QAAQ,GAAG,cAAc;YAC7B,CAAC,CAAC,2BAA2B,iBAAiB,CAAC,KAAK,4CAA4C;YAChG,CAAC,CAAC,uCAAuC,iBAAiB,CAAC,OAAO,8BAA8B;gBAC9F,4FAA4F;gBAC5F,6BAA6B,CAAC;QAElC,MAAM,IAAI,GAAG;YACX,0BAA0B,cAAc,EAAE;YAC1C,EAAE;YACF,QAAQ;YACR,EAAE;YACF,cAAc,YAAY,EAAE;YAC5B,0BAA0B,iBAAiB,CAAC,IAAI,EAAE;YAClD,sBAAsB,iBAAiB,CAAC,KAAK,EAAE;YAC/C,4CAA4C,qBAAqB,kBAAkB;YACnF,kHAAkH;YAClH,mCAAmC,eAAe,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE;YAC5E,qBAAqB,UAAU,EAAE;SAClC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC1E,CAAC,CACF,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"meta.js","sourceRoot":"","sources":["../../src/tools/meta.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,cAAc,GACf,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE5D,MAAM,UAAU,iBAAiB,CAAC,MAAiB,EAAE,MAAiB;IACpE,YAAY,CACV,MAAM,EACN;QACE,IAAI,EAAE,0BAA0B;QAChC,KAAK,EAAE,uCAAuC;QAC9C,WAAW,EACT,0FAA0F;YAC1F,yFAAyF;YACzF,4EAA4E;YAC5E,6EAA6E;YAC7E,kFAAkF;YAClF,iDAAiD;QACnD,WAAW,EAAE;YACX,eAAe,EAAE,CAAC;iBACf,OAAO,EAAE;iBACT,OAAO,CAAC,IAAI,CAAC;iBACb,QAAQ,CACP,qGAAqG,CACtG;SACJ;KACF,EACD,KAAK,EAAE,IAAI,EAAuB,EAAE;QAClC,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QACtC,MAAM,iBAAiB,GAAG,OAAO,CAAC,KAAK,CAAC;QACxC,MAAM,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;QAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC;QAE9C,IAAI,UAAU,GAAG,YAAY,CAAC;QAC9B,IAAI,IAAI,CAAC,eAAe,KAAK,KAAK,EAAE,CAAC;YACnC,IAAI,CAAC;gBACH,6DAA6D;gBAC7D,MAAM,MAAM,CAAC,OAAO,CAAU,kBAAkB,EAAE,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC3E,UAAU,GAAG,uCAAuC,CAAC;YACvD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,uBAAuB,CAAC,CAAC;gBACjE,UAAU,GAAG,YAAY,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;YACnD,CAAC;QACH,CAAC;QAED,MAAM,MAAM,GAAG;YACb,cAAc,EAAE,cAAc;YAC9B,YAAY,EAAE,YAAY;YAC1B,cAAc,EAAE,cAAc;YAC9B,gBAAgB,EAAE;gBAChB,SAAS,EAAE,iBAAiB,CAAC,IAAI;gBACjC,KAAK,EAAE,iBAAiB,CAAC,KAAK;gBAC9B,gCAAgC,EAAE,iBAAiB,CAAC,OAAO;aAC5D;YACD,qBAAqB,EAAE,qBAAqB;YAC5C,eAAe,EAAE,eAAe;YAChC,UAAU;SACX,CAAC;QAEF,MAAM,QAAQ,GAAG,cAAc;YAC7B,CAAC,CAAC,2BAA2B,iBAAiB,CAAC,KAAK,4CAA4C;YAChG,CAAC,CAAC,MAAM;gBACN,CAAC,CAAC,uCAAuC,iBAAiB,CAAC,OAAO,8BAA8B;oBAC9F,0FAA0F;oBAC1F,wEAAwE;gBAC1E,CAAC,CAAC,uCAAuC,iBAAiB,CAAC,OAAO,8BAA8B;oBAC9F,4FAA4F;oBAC5F,6BAA6B,CAAC;QAEpC,MAAM,IAAI,GAAG;YACX,0BAA0B,cAAc,EAAE;YAC1C,EAAE;YACF,QAAQ;YACR,EAAE;YACF,cAAc,YAAY,EAAE;YAC5B,0BAA0B,iBAAiB,CAAC,IAAI,EAAE;YAClD,sBAAsB,iBAAiB,CAAC,KAAK,EAAE;YAC/C,4CAA4C,qBAAqB,kBAAkB;YACnF,yHAAyH;YACzH,mCAAmC,eAAe,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE;YAC5E,qBAAqB,UAAU,EAAE;SAClC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEb,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC1E,CAAC,CACF,CAAC;AACJ,CAAC"}
@@ -1,12 +1,16 @@
1
1
  /**
2
2
  * Tool registration helpers.
3
3
  *
4
- * `registerRead` always registers. `registerWrite` only registers when
5
- * EASYBILL_ENABLE_WRITES is set, so a default install cannot mutate live
4
+ * `registerRead` always registers. `registerWrite` only registers when writes
5
+ * are enabled for the server, so a default install cannot mutate live
6
6
  * accounting data and read-only sessions keep a lean tool list.
7
+ *
8
+ * In hosted (multi-account) mode every tool additionally takes an `account`
9
+ * argument; the wrapper strips it, checks it, and runs the handler with that
10
+ * account's client selected (see ServerContext.accounts.run).
7
11
  */
8
12
  import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
9
- import type { ZodRawShape } from "zod";
13
+ import { type ZodRawShape } from "zod";
10
14
  import { type ToolResult } from "../services/format.js";
11
15
  export interface ToolSpec<Shape extends ZodRawShape> {
12
16
  name: string;
@@ -17,7 +21,40 @@ export interface ToolSpec<Shape extends ZodRawShape> {
17
21
  destructive?: boolean;
18
22
  /** True when repeating the call has no additional effect. */
19
23
  idempotent?: boolean;
24
+ /** Hosted mode: the tool does not talk to a specific account, so it gets no `account` argument. */
25
+ accountless?: boolean;
26
+ }
27
+ /** An easybill account a hosted session can address. */
28
+ export interface AccountChoice {
29
+ id: string;
30
+ name: string;
31
+ /** Whether write tools may run against this account. */
32
+ writes: boolean;
33
+ }
34
+ export interface RegistrationStats {
35
+ read: number;
36
+ write: number;
37
+ skipped: number;
20
38
  }
39
+ /** Per-server settings that decide how tools are registered and dispatched. */
40
+ export interface ServerContext {
41
+ writesEnabled: boolean;
42
+ /** Hosted mode only. Absent in stdio mode, where there is exactly one account. */
43
+ accounts?: {
44
+ list: AccountChoice[];
45
+ /** Runs `fn` with the given account's client selected. */
46
+ run<T>(accountId: string, fn: () => Promise<T>): Promise<T>;
47
+ };
48
+ stats: RegistrationStats;
49
+ }
50
+ /** Must be called before any tool is registered on `server`. */
51
+ export declare function setServerContext(server: McpServer, context: ServerContext): void;
52
+ /**
53
+ * Hosted (multi-user) mode. Tools must then never touch the server's file
54
+ * system on a caller's behalf: no writing to or reading from caller-chosen paths.
55
+ */
56
+ export declare function isHosted(server: McpServer): boolean;
57
+ export declare function serverContext(server: McpServer): ServerContext;
21
58
  /**
22
59
  * Validated tool arguments.
23
60
  *
@@ -29,11 +66,5 @@ export interface ToolSpec<Shape extends ZodRawShape> {
29
66
  */
30
67
  export type Args = Record<string, unknown>;
31
68
  export type Handler = (args: Args) => Promise<ToolResult>;
32
- /** Counts of what actually got registered, for the startup log. */
33
- export declare const registrationStats: {
34
- read: number;
35
- write: number;
36
- skipped: number;
37
- };
38
69
  export declare function registerRead<Shape extends ZodRawShape>(server: McpServer, spec: ToolSpec<Shape>, handler: Handler): void;
39
70
  export declare function registerWrite<Shape extends ZodRawShape>(server: McpServer, spec: ToolSpec<Shape>, handler: Handler): void;
@@ -1,15 +1,38 @@
1
1
  /**
2
2
  * Tool registration helpers.
3
3
  *
4
- * `registerRead` always registers. `registerWrite` only registers when
5
- * EASYBILL_ENABLE_WRITES is set, so a default install cannot mutate live
4
+ * `registerRead` always registers. `registerWrite` only registers when writes
5
+ * are enabled for the server, so a default install cannot mutate live
6
6
  * accounting data and read-only sessions keep a lean tool list.
7
+ *
8
+ * In hosted (multi-account) mode every tool additionally takes an `account`
9
+ * argument; the wrapper strips it, checks it, and runs the handler with that
10
+ * account's client selected (see ServerContext.accounts.run).
7
11
  */
12
+ import { z } from "zod";
8
13
  import { WRITES_ENABLED } from "../constants.js";
9
14
  import { formatApiError } from "../services/client.js";
10
15
  import { textResult } from "../services/format.js";
11
- /** Counts of what actually got registered, for the startup log. */
12
- export const registrationStats = { read: 0, write: 0, skipped: 0 };
16
+ const contexts = new WeakMap();
17
+ /** Must be called before any tool is registered on `server`. */
18
+ export function setServerContext(server, context) {
19
+ contexts.set(server, context);
20
+ }
21
+ /**
22
+ * Hosted (multi-user) mode. Tools must then never touch the server's file
23
+ * system on a caller's behalf: no writing to or reading from caller-chosen paths.
24
+ */
25
+ export function isHosted(server) {
26
+ return serverContext(server).accounts !== undefined;
27
+ }
28
+ export function serverContext(server) {
29
+ let context = contexts.get(server);
30
+ if (!context) {
31
+ context = { writesEnabled: WRITES_ENABLED, stats: { read: 0, write: 0, skipped: 0 } };
32
+ contexts.set(server, context);
33
+ }
34
+ return context;
35
+ }
13
36
  /** Wraps a handler so no thrown error ever escapes as a protocol-level failure. */
14
37
  function guard(handler) {
15
38
  return async (args) => {
@@ -21,36 +44,76 @@ function guard(handler) {
21
44
  }
22
45
  };
23
46
  }
47
+ function accountSchema(list) {
48
+ const ids = list.map((a) => a.id);
49
+ const names = list.map((a) => `'${a.id}' = ${a.name}${a.writes ? "" : " (read-only)"}`).join(", ");
50
+ const base = z.enum(ids);
51
+ return list.length === 1
52
+ ? base.optional().describe(`easybill account. Only one is connected (${names}), so this can be omitted.`)
53
+ : base.describe(`Which easybill account to act on: ${names}. Required — IDs, numbers and customers differ between accounts.`);
54
+ }
55
+ /** Adds the `account` argument in hosted mode. */
56
+ function shapeFor(context, spec) {
57
+ const accounts = context.accounts;
58
+ if (!accounts || spec.accountless || accounts.list.length === 0)
59
+ return spec.inputSchema;
60
+ return { ...spec.inputSchema, account: accountSchema(accounts.list) };
61
+ }
62
+ /** Hosted mode: resolve the `account` argument and run the handler against it. */
63
+ function routed(context, spec, handler, write) {
64
+ const accounts = context.accounts;
65
+ if (!accounts || spec.accountless)
66
+ return handler;
67
+ return async (args) => {
68
+ const { account, ...rest } = args;
69
+ const list = accounts.list;
70
+ if (list.length === 0) {
71
+ return textResult("Error: no easybill account is connected to this session. Call easybill_list_accounts for the link to connect one.", true);
72
+ }
73
+ const id = typeof account === "string" ? account : list.length === 1 ? list[0].id : undefined;
74
+ const choice = list.find((a) => a.id === id);
75
+ if (!choice) {
76
+ return textResult(`Error: pass 'account' — one of ${list.map((a) => `'${a.id}' (${a.name})`).join(", ")}.`, true);
77
+ }
78
+ if (write && !choice.writes) {
79
+ return textResult(`Error: the account '${choice.id}' (${choice.name}) is read-only on this server. ` +
80
+ `Create, update and delete are not allowed there.`, true);
81
+ }
82
+ return accounts.run(choice.id, () => handler(rest));
83
+ };
84
+ }
24
85
  export function registerRead(server, spec, handler) {
86
+ const context = serverContext(server);
25
87
  server.registerTool(spec.name, {
26
88
  title: spec.title,
27
89
  description: spec.description,
28
- inputSchema: spec.inputSchema,
90
+ inputSchema: shapeFor(context, spec),
29
91
  annotations: {
30
92
  readOnlyHint: true,
31
93
  destructiveHint: false,
32
94
  idempotentHint: true,
33
95
  openWorldHint: true,
34
96
  },
35
- }, guard(handler));
36
- registrationStats.read++;
97
+ }, guard(routed(context, spec, handler, false)));
98
+ context.stats.read++;
37
99
  }
38
100
  export function registerWrite(server, spec, handler) {
39
- if (!WRITES_ENABLED) {
40
- registrationStats.skipped++;
101
+ const context = serverContext(server);
102
+ if (!context.writesEnabled) {
103
+ context.stats.skipped++;
41
104
  return;
42
105
  }
43
106
  server.registerTool(spec.name, {
44
107
  title: spec.title,
45
108
  description: spec.description,
46
- inputSchema: spec.inputSchema,
109
+ inputSchema: shapeFor(context, spec),
47
110
  annotations: {
48
111
  readOnlyHint: false,
49
112
  destructiveHint: spec.destructive ?? false,
50
113
  idempotentHint: spec.idempotent ?? false,
51
114
  openWorldHint: true,
52
115
  },
53
- }, guard(handler));
54
- registrationStats.write++;
116
+ }, guard(routed(context, spec, handler, true)));
117
+ context.stats.write++;
55
118
  }
56
119
  //# sourceMappingURL=registry.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAmB,UAAU,EAAE,MAAM,uBAAuB,CAAC;AA0BpE,mEAAmE;AACnE,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;AAEnE,mFAAmF;AACnF,SAAS,KAAK,CAAC,OAAgB;IAC7B,OAAO,KAAK,EAAE,IAAU,EAAuB,EAAE;QAC/C,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,UAAU,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,CAAC;QACjD,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,MAAiB,EACjB,IAAqB,EACrB,OAAgB;IAEhB,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT;QACE,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE;YACX,YAAY,EAAE,IAAI;YAClB,eAAe,EAAE,KAAK;YACtB,cAAc,EAAE,IAAI;YACpB,aAAa,EAAE,IAAI;SACpB;KACF,EACD,KAAK,CAAC,OAAO,CAAU,CACxB,CAAC;IACF,iBAAiB,CAAC,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,MAAiB,EACjB,IAAqB,EACrB,OAAgB;IAEhB,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,iBAAiB,CAAC,OAAO,EAAE,CAAC;QAC5B,OAAO;IACT,CAAC;IACD,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT;QACE,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE;YACX,YAAY,EAAE,KAAK;YACnB,eAAe,EAAE,IAAI,CAAC,WAAW,IAAI,KAAK;YAC1C,cAAc,EAAE,IAAI,CAAC,UAAU,IAAI,KAAK;YACxC,aAAa,EAAE,IAAI;SACpB;KACF,EACD,KAAK,CAAC,OAAO,CAAU,CACxB,CAAC;IACF,iBAAiB,CAAC,KAAK,EAAE,CAAC;AAC5B,CAAC"}
1
+ {"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"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"}
@@ -1,13 +1,14 @@
1
1
  /**
2
- * Fuzzy customer lookup.
2
+ * Customer lookup — the first question when processing an inbound inquiry:
3
+ * "is this company already a customer?"
3
4
  *
4
- * The easybill API offers no full-text search — its customer filters match exact
5
- * values only. That makes "is this company already a customer?" surprisingly hard,
6
- * which is the first question to answer when processing an inbound inquiry.
5
+ * Primary path: easybill's full-text search (GET /customers/search, API 1.102),
6
+ * one request, covering archived contacts too. Its results come sorted by
7
+ * customer number, so they are re-ranked locally by how well they match.
7
8
  *
8
- * This tool bridges the gap: it tries cheap exact filters first, then falls back to
9
- * paging the customer list and scoring candidates locally.
9
+ * Fallback, for accounts where the search endpoint is not available: cheap exact
10
+ * filters, then paging the customer list and scoring candidates locally.
10
11
  */
11
12
  import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
12
- import type { EasybillClient } from "../services/client.js";
13
- export declare function registerSearchTools(server: McpServer, client: EasybillClient): void;
13
+ import { type ApiClient } from "../services/client.js";
14
+ export declare function registerSearchTools(server: McpServer, client: ApiClient): void;