billingengine-mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,19 +1,21 @@
 # BillingEngine MCP server
 
+[![AllMCPs Verified](https://allmcps.com/api/badge/billingengine-mcp)](https://allmcps.com/mcp/billingengine-mcp?verify=e69e154f-3c18-4a25-b8a9-42bfcd9c6182)
+
 Create customers and invoices, look up open invoices and record payments in
 [BillingEngine](https://www.billingengine.com) by talking to Claude, Cursor or any other
 [MCP](https://modelcontextprotocol.io) client:
 
-> "Create an invoice for Malermeister Müller over 100 euros."
+> "Create an invoice for Acme Painting over 100 euros."
 >
 > "Which invoices are overdue?"
 >
-> "Müller paid invoice 2610030028, record the payment."
+> "Acme paid invoice 2610030028, record the payment."
 
 BillingEngine is invoicing software for freelancers and small businesses with
-[e-invoicing](https://www.billingengine.com/en/features) (XRechnung and ZUGFeRD / Factur-X),
-DATEV export and a German and English interface. The server is a thin layer over the
-[BillingEngine API](https://www.billingengine.com/en/api) and runs on your computer.
+[e-invoicing](https://www.billingengine.com/en/features) (EN 16931, XRechnung, ZUGFeRD / Factur-X).
+The server is a thin layer over the [BillingEngine API](https://www.billingengine.com/en/api)
+and runs on your computer.
 
 ## Requirements
 

package/dist/index.js

@@ -20,7 +20,7 @@ const INSTRUCTIONS = [
     "Invoices are created as drafts and are not sent: tell the user to review and send them in BillingEngine, using the app_url in the result.",
     "Nothing can be deleted through this server.",
 ].join(" ");
-const server = new McpServer({ name: "billingengine", version: "0.1.0" }, { instructions: INSTRUCTIONS });
+const server = new McpServer({ name: "billingengine", version: "0.1.2" }, { instructions: INSTRUCTIONS });
 const date = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Use YYYY-MM-DD");
 const page = z.number().int().min(1).optional().describe("Page of the list, starting at 1");
 const address = z.object({
@@ -51,17 +51,20 @@ const item = z.object({
 const invoiceFields = {
     date: date.optional().describe("Invoice date, defaults to today"),
     due_days: z.number().int().min(0).optional().describe("Days until payment is due"),
-    introduction: z.string().optional(),
-    signature: z.string().optional(),
+    opening_text: z.string().optional().describe("Text above the items, defaults to the account's text"),
+    closing_text: z.string().optional().describe("Text below the items, defaults to the account's text"),
     service_period_start_date: date.optional(),
     service_period_end_date: date.optional(),
 };
 const READ = { readOnlyHint: true, openWorldHint: false };
 const WRITE = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
+const UPDATE = { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false };
+const output = z.looseObject({});
 async function respond(action) {
     try {
         const value = await action();
-        return { content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }] };
+        const structured = typeof value === "string" ? { message: value } : value;
+        return { content: [{ type: "text", text: JSON.stringify(structured, null, 2) }], structuredContent: structured };
     }
     catch (error) {
         const message = error instanceof BillingEngineError ? error.message : `Unexpected error: ${error.message}`;
@@ -81,32 +84,37 @@ server.registerTool("find_customers", {
     title: "Find customers",
     description: "Lists customers, optionally filtered by a search text that matches company, names and email.",
     inputSchema: { query: z.string().optional(), page },
+    outputSchema: output,
     annotations: READ,
 }, ({ query, page }) => respond(() => client.get("/customers", { query, page })));
 server.registerTool("create_customer", {
     title: "Create a customer",
     description: "Creates a customer. Needs a company or a last name and a full address (line 1, postal code, city, country).",
     inputSchema: { ...customerFields, address },
+    outputSchema: output,
     annotations: WRITE,
 }, ({ address, ...fields }) => respond(() => client.post("/customers", { ...fields, address_attributes: address })));
 server.registerTool("update_customer", {
     title: "Update a customer",
     description: "Changes the given fields of a customer; fields that are left out stay as they are.",
     inputSchema: { id: z.number().int(), ...customerFields, address: address.partial().optional() },
-    annotations: { ...WRITE, idempotentHint: true },
+    outputSchema: output,
+    annotations: UPDATE,
 }, ({ id, address, ...fields }) => respond(() => client.patch(`/customers/${id}`, { ...fields, ...(address && { address_attributes: address }) })));
 server.registerTool("create_invoice", {
     title: "Create a draft invoice",
     description: "Creates a draft invoice for a customer. Number, language, texts and VAT treatment come from the account settings. " +
         "The invoice is not sent; it counts towards the monthly invoice maximum of the plan.",
     inputSchema: { customer_id: z.number().int(), items: z.array(item).min(1), ...invoiceFields },
+    outputSchema: output,
     annotations: WRITE,
 }, (input) => respond(async () => withInvoiceLinks(await client.post("/invoices", input))));
 server.registerTool("update_invoice", {
     title: "Update a draft invoice",
     description: "Changes a draft invoice. Passing items replaces all existing items, so send the complete list. Sent invoices cannot be changed.",
     inputSchema: { id: z.number().int(), items: z.array(item).min(1).optional(), ...invoiceFields },
-    annotations: { ...WRITE, idempotentHint: true },
+    outputSchema: output,
+    annotations: UPDATE,
 }, ({ id, ...changes }) => respond(async () => withInvoiceLinks(await client.patch(`/invoices/${id}`, changes))));
 server.registerTool("list_invoices", {
     title: "List invoices",
@@ -120,12 +128,14 @@ server.registerTool("list_invoices", {
         page,
         per_page: z.number().int().min(1).max(100).optional(),
     },
+    outputSchema: output,
     annotations: READ,
 }, (filters) => respond(async () => withInvoiceLinks(await client.get("/invoices", filters))));
 server.registerTool("get_invoice", {
     title: "Get an invoice",
     description: "Returns one invoice with its items, amounts and payment status.",
     inputSchema: { id: z.number().int() },
+    outputSchema: output,
     annotations: READ,
 }, ({ id }) => respond(async () => withInvoiceLinks(await client.get(`/invoices/${id}`))));
 server.registerTool("download_invoice", {
@@ -137,6 +147,7 @@ server.registerTool("download_invoice", {
         format: z.enum(["pdf", "xml"]).default("pdf"),
         directory: z.string().optional().describe("Target folder, defaults to ~/Downloads"),
     },
+    outputSchema: output,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
 }, ({ id, format, directory }) => respond(async () => {
     const file = await client.getFile(`/invoices/${id}.${format}`);
@@ -155,12 +166,24 @@ server.registerTool("record_payment", {
         payment_method: z.enum(["transfer", "cash"]).optional().describe("Defaults to transfer"),
         date: date.optional().describe("Defaults to today"),
     },
+    outputSchema: output,
     annotations: WRITE,
-}, (input) => respond(() => client.post("/payments", input)));
+}, (input) => respond(async () => {
+    try {
+        return await client.post("/payments", input);
+    }
+    catch (error) {
+        if (error instanceof BillingEngineError && error.message.includes("Invoices is invalid")) {
+            throw new BillingEngineError(`${error.message} Payments can only be recorded for sent, open invoices of the same customer and tax rate; drafts cannot be paid.`);
+        }
+        throw error;
+    }
+}));
 server.registerTool("list_payments", {
     title: "List payments",
     description: "Lists recorded payments, newest first, optionally only those for one invoice.",
     inputSchema: { invoice_id: z.number().int().optional(), page },
+    outputSchema: output,
     annotations: READ,
 }, (filters) => respond(() => client.get("/payments", filters)));
 await server.connect(new StdioServerTransport());

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "billingengine-mcp",
   "mcpName": "com.billingengine/mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for BillingEngine: create customers and invoices, look up invoices and record payments from Claude, Cursor and other MCP clients.",
   "keywords": [
     "mcp",
@@ -13,7 +13,7 @@
     "xrechnung",
     "zugferd"
   ],
-  "homepage": "https://www.billingengine.com/mcp",
+  "homepage": "https://www.billingengine.com/en/mcp",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/billingengine/billingengine-mcp.git"
@@ -37,14 +37,18 @@
   },
   "scripts": {
     "build": "tsc && chmod +x dist/index.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "bundle": "npm run build && esbuild dist/index.js --bundle --platform=node --format=esm --target=node20 --outfile=mcpb/server/index.js --banner:js=\"import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);\" && mcpb pack mcpb billingengine.mcpb",
+    "bundle:smithery": "npm run bundle && node scripts/smithery-bundle.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {
+    "@anthropic-ai/mcpb": "^2.1.2",
     "@types/node": "^26.6.4",
+    "esbuild": "^0.28.2",
     "typescript": "^7.0.2"
   }
 }