buchpilot-mcp 0.1.1

package/docs/tool-reference.md

@@ -0,0 +1,497 @@
+# BuchPilot MCP — Tool-Referenz
+
+Vollstaendige Referenz aller 15 Tools des BuchPilot MCP Servers.
+
+---
+
+## Kontakte
+
+### create_contact
+
+Erstellt einen neuen Kontakt (Person oder Firma) im Buchhaltungssystem.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Default | Beschreibung |
+|-----------|-----|---------|---------|-------------|
+| `type` | `"person"` \| `"company"` | Ja | — | Kontakttyp: Person oder Firma |
+| `name` | string | Ja | — | Nachname (bei Person) oder Firmenname (bei Firma) |
+| `firstName` | string | Nein | — | Vorname (nur bei Person) |
+| `email` | string | Nein | — | E-Mail-Adresse |
+| `role` | `"customer"` \| `"vendor"` \| `"both"` | Nein | `"customer"` | Rolle: Kunde, Lieferant, oder beides |
+| `backend` | string | Nein | Default-Backend | Backend (z.B. "lexoffice") |
+
+**Beispiel-Input:**
+
+```json
+{
+  "type": "company",
+  "name": "Beispiel GmbH",
+  "email": "info@beispiel.de",
+  "role": "customer"
+}
+```
+
+**Beispiel-Output:**
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "type": "company",
+  "name": "Beispiel GmbH",
+  "email": "info@beispiel.de",
+  "role": "customer",
+  "backend": "lexoffice",
+  "raw": { "...": "Lexoffice-spezifische Rohdaten" }
+}
+```
+
+---
+
+### get_contact
+
+Ruft einen Kontakt per ID ab.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Default | Beschreibung |
+|-----------|-----|---------|---------|-------------|
+| `id` | string | Ja | — | Kontakt-ID |
+| `backend` | string | Nein | Default-Backend | Backend |
+
+**Beispiel-Input:**
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+}
+```
+
+**Beispiel-Output:**
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "type": "company",
+  "name": "Beispiel GmbH",
+  "email": "info@beispiel.de",
+  "role": "customer",
+  "backend": "lexoffice",
+  "raw": { "...": "..." }
+}
+```
+
+---
+
+### list_contacts
+
+Listet Kontakte auf mit optionalen Filtern.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Default | Beschreibung |
+|-----------|-----|---------|---------|-------------|
+| `name` | string | Nein | — | Nach Name filtern (Teilsuche) |
+| `email` | string | Nein | — | Nach E-Mail filtern |
+| `role` | `"customer"` \| `"vendor"` | Nein | — | Nach Rolle filtern |
+| `limit` | number | Nein | 25 | Maximale Anzahl Ergebnisse |
+| `backend` | string | Nein | Default-Backend | Backend |
+
+**Beispiel-Input:**
+
+```json
+{
+  "role": "customer",
+  "limit": 10
+}
+```
+
+**Beispiel-Output:**
+
+```json
+[
+  {
+    "id": "a1b2c3d4-...",
+    "type": "company",
+    "name": "Beispiel GmbH",
+    "email": "info@beispiel.de",
+    "role": "customer",
+    "backend": "lexoffice",
+    "raw": { "...": "..." }
+  },
+  {
+    "id": "b2c3d4e5-...",
+    "type": "person",
+    "name": "Mustermann",
+    "firstName": "Max",
+    "email": "max@mustermann.de",
+    "role": "customer",
+    "backend": "lexoffice",
+    "raw": { "...": "..." }
+  }
+]
+```
+
+---
+
+### update_contact
+
+Aktualisiert einen bestehenden Kontakt. Nur die uebergebenen Felder werden geaendert.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Default | Beschreibung |
+|-----------|-----|---------|---------|-------------|
+| `id` | string | Ja | — | Kontakt-ID |
+| `name` | string | Nein | — | Neuer Name |
+| `firstName` | string | Nein | — | Neuer Vorname |
+| `email` | string | Nein | — | Neue E-Mail |
+| `backend` | string | Nein | Default-Backend | Backend |
+
+**Beispiel-Input:**
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "email": "neu@beispiel.de"
+}
+```
+
+---
+
+## Rechnungen
+
+### create_invoice
+
+Erstellt eine neue Rechnung mit Positionen.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Default | Beschreibung |
+|-----------|-----|---------|---------|-------------|
+| `contactId` | string | Ja | — | Kontakt-ID des Rechnungsempfaengers |
+| `date` | string | Ja | — | Rechnungsdatum (ISO 8601, z.B. `2026-03-18`) |
+| `lineItems` | Array | Ja | — | Rechnungspositionen (mind. 1) |
+| `lineItems[].name` | string | Ja | — | Positionsname |
+| `lineItems[].quantity` | number | Nein | 1 | Menge |
+| `lineItems[].unitPrice` | number | Ja | — | Einzelpreis netto |
+| `lineItems[].taxRate` | number | Nein | 19 | Steuersatz in Prozent |
+| `title` | string | Nein | — | Rechnungstitel |
+| `introduction` | string | Nein | — | Einleitungstext |
+| `remark` | string | Nein | — | Schlusstext |
+| `currency` | string | Nein | `"EUR"` | Waehrung |
+| `finalize` | boolean | Nein | `false` | Rechnung direkt finalisieren (nicht mehr editierbar) |
+| `backend` | string | Nein | Default-Backend | Backend |
+
+**Beispiel-Input:**
+
+```json
+{
+  "contactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "date": "2026-03-18",
+  "lineItems": [
+    { "name": "Beratung", "quantity": 10, "unitPrice": 150.00, "taxRate": 19 },
+    { "name": "Softwarelizenz", "quantity": 1, "unitPrice": 499.00, "taxRate": 19 }
+  ],
+  "title": "Rechnung Maerz 2026",
+  "introduction": "Vielen Dank fuer Ihren Auftrag.",
+  "remark": "Zahlbar innerhalb von 14 Tagen.",
+  "finalize": false
+}
+```
+
+**Beispiel-Output:**
+
+```json
+{
+  "id": "inv-1234-5678-abcd",
+  "number": "RE-2026-0042",
+  "contactId": "a1b2c3d4-...",
+  "date": "2026-03-18",
+  "dueDate": "2026-04-01",
+  "status": "draft",
+  "totalNet": 1999.00,
+  "totalGross": 2378.81,
+  "currency": "EUR",
+  "lineItems": [
+    { "name": "Beratung", "quantity": 10, "unitPrice": 150.00, "taxRate": 19 },
+    { "name": "Softwarelizenz", "quantity": 1, "unitPrice": 499.00, "taxRate": 19 }
+  ],
+  "backend": "lexoffice",
+  "raw": { "...": "..." }
+}
+```
+
+---
+
+### get_invoice
+
+Ruft eine Rechnung per ID ab.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Default | Beschreibung |
+|-----------|-----|---------|---------|-------------|
+| `id` | string | Ja | — | Rechnungs-ID |
+| `backend` | string | Nein | Default-Backend | Backend |
+
+---
+
+### list_invoices
+
+Listet Rechnungen auf. Kann nach Status und Kontakt gefiltert werden.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Default | Beschreibung |
+|-----------|-----|---------|---------|-------------|
+| `status` | `"draft"` \| `"open"` \| `"paid"` \| `"overdue"` | Nein | — | Nach Status filtern |
+| `contactId` | string | Nein | — | Nach Kontakt filtern |
+| `limit` | number | Nein | 25 | Maximale Anzahl |
+| `backend` | string | Nein | Default-Backend | Backend |
+
+**Beispiel-Input:**
+
+```json
+{
+  "status": "open",
+  "limit": 10
+}
+```
+
+---
+
+### get_invoice_pdf
+
+Laedt eine Rechnung als PDF herunter (Base64-kodiert). Die Rechnung muss finalisiert sein (Status "open" oder "paid").
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Default | Beschreibung |
+|-----------|-----|---------|---------|-------------|
+| `id` | string | Ja | — | Rechnungs-ID |
+| `backend` | string | Nein | Default-Backend | Backend |
+
+**Beispiel-Output:**
+
+```json
+{
+  "filename": "RE-2026-0042.pdf",
+  "size_bytes": 45231
+}
+```
+
+Zusaetzlich wird die PDF als Base64-kodierte Ressource zurueckgegeben.
+
+---
+
+### update_invoice
+
+Aktualisiert eine bestehende Rechnung. Nur Entwuerfe (Status "draft") koennen aktualisiert werden.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Default | Beschreibung |
+|-----------|-----|---------|---------|-------------|
+| `id` | string | Ja | — | Rechnungs-ID |
+| `title` | string | Nein | — | Neuer Titel |
+| `introduction` | string | Nein | — | Neuer Einleitungstext |
+| `remark` | string | Nein | — | Neuer Schlusstext |
+| `backend` | string | Nein | Default-Backend | Backend |
+
+---
+
+## Belege
+
+### create_voucher
+
+Erstellt einen neuen Beleg (Eingangsrechnung oder Gutschrift).
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Default | Beschreibung |
+|-----------|-----|---------|---------|-------------|
+| `type` | `"purchaseinvoice"` \| `"purchasecreditnote"` \| `"any"` | Ja | — | Belegtyp |
+| `date` | string | Ja | — | Belegdatum (ISO 8601) |
+| `totalGross` | number | Ja | — | Bruttobetrag |
+| `taxRate` | number | Nein | 19 | Steuersatz in Prozent |
+| `contactId` | string | Nein | — | Kontakt-ID (optional) |
+| `remark` | string | Nein | — | Bemerkung |
+| `backend` | string | Nein | Default-Backend | Backend |
+
+**Beispiel-Input:**
+
+```json
+{
+  "type": "purchaseinvoice",
+  "date": "2026-03-15",
+  "totalGross": 119.00,
+  "taxRate": 19,
+  "remark": "Bueromaterial"
+}
+```
+
+**Beispiel-Output:**
+
+```json
+{
+  "id": "voucher-abc-123",
+  "type": "purchaseinvoice",
+  "date": "2026-03-15",
+  "totalGross": 119.00,
+  "taxRate": 19,
+  "backend": "lexoffice",
+  "raw": { "...": "..." }
+}
+```
+
+---
+
+### get_voucher
+
+Ruft einen Beleg per ID ab.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Default | Beschreibung |
+|-----------|-----|---------|---------|-------------|
+| `id` | string | Ja | — | Beleg-ID |
+| `backend` | string | Nein | Default-Backend | Backend |
+
+---
+
+### list_vouchers
+
+Listet Belege auf mit optionalen Filtern.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Default | Beschreibung |
+|-----------|-----|---------|---------|-------------|
+| `type` | `"purchaseinvoice"` \| `"purchasecreditnote"` \| `"any"` | Nein | — | Nach Typ filtern |
+| `limit` | number | Nein | 25 | Maximale Anzahl |
+| `backend` | string | Nein | Default-Backend | Backend |
+
+---
+
+## Angebote
+
+### create_quotation
+
+Erstellt ein neues Angebot mit Positionen.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Default | Beschreibung |
+|-----------|-----|---------|---------|-------------|
+| `contactId` | string | Ja | — | Kontakt-ID |
+| `date` | string | Ja | — | Angebotsdatum (ISO 8601) |
+| `lineItems` | Array | Ja | — | Angebotspositionen (mind. 1) |
+| `lineItems[].name` | string | Ja | — | Positionsname |
+| `lineItems[].quantity` | number | Nein | 1 | Menge |
+| `lineItems[].unitPrice` | number | Ja | — | Einzelpreis netto |
+| `lineItems[].taxRate` | number | Nein | 19 | Steuersatz in Prozent |
+| `expirationDate` | string | Nein | — | Gueltig bis (ISO 8601) |
+| `title` | string | Nein | — | Angebotstitel |
+| `introduction` | string | Nein | — | Einleitungstext |
+| `remark` | string | Nein | — | Schlusstext |
+| `finalize` | boolean | Nein | `false` | Angebot direkt finalisieren |
+| `backend` | string | Nein | Default-Backend | Backend |
+
+**Beispiel-Input:**
+
+```json
+{
+  "contactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "date": "2026-03-18",
+  "expirationDate": "2026-04-18",
+  "lineItems": [
+    { "name": "Webseiten-Redesign", "quantity": 1, "unitPrice": 4500.00 },
+    { "name": "SEO-Optimierung", "quantity": 1, "unitPrice": 1200.00 }
+  ],
+  "title": "Angebot Webprojekt",
+  "introduction": "Gerne unterbreiten wir Ihnen folgendes Angebot."
+}
+```
+
+**Beispiel-Output:**
+
+```json
+{
+  "id": "quot-9876-abcd",
+  "contactId": "a1b2c3d4-...",
+  "date": "2026-03-18",
+  "expirationDate": "2026-04-18",
+  "totalNet": 5700.00,
+  "totalGross": 6783.00,
+  "lineItems": [
+    { "name": "Webseiten-Redesign", "quantity": 1, "unitPrice": 4500.00, "taxRate": 19 },
+    { "name": "SEO-Optimierung", "quantity": 1, "unitPrice": 1200.00, "taxRate": 19 }
+  ],
+  "backend": "lexoffice",
+  "raw": { "...": "..." }
+}
+```
+
+---
+
+### get_quotation
+
+Ruft ein Angebot per ID ab.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Default | Beschreibung |
+|-----------|-----|---------|---------|-------------|
+| `id` | string | Ja | — | Angebots-ID |
+| `backend` | string | Nein | Default-Backend | Backend |
+
+---
+
+## Ueberfaellige Rechnungen
+
+### get_overdue_invoices
+
+Listet alle ueberfaelligen Rechnungen mit Betrag, Faelligkeitsdatum und Tagen ueberfaellig auf.
+
+**Parameter:**
+
+| Parameter | Typ | Pflicht | Default | Beschreibung |
+|-----------|-----|---------|---------|-------------|
+| `days_overdue` | number | Nein | 0 | Mindestens X Tage ueberfaellig (0 = alle ueberfaelligen) |
+| `limit` | number | Nein | 50 | Maximale Anzahl |
+| `backend` | string | Nein | Default-Backend | Backend |
+
+**Beispiel-Input:**
+
+```json
+{
+  "days_overdue": 30
+}
+```
+
+**Beispiel-Output:**
+
+```json
+{
+  "count": 2,
+  "total_overdue_amount": 3456.78,
+  "currency": "EUR",
+  "invoices": [
+    {
+      "id": "inv-1111-aaaa",
+      "number": "RE-2026-0031",
+      "totalGross": 2380.00,
+      "dueDate": "2026-02-01",
+      "daysOverdue": 45
+    },
+    {
+      "id": "inv-2222-bbbb",
+      "number": "RE-2026-0035",
+      "totalGross": 1076.78,
+      "dueDate": "2026-02-15",
+      "daysOverdue": 31
+    }
+  ]
+}
+```

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "buchpilot-mcp",
+  "version": "0.1.1",
+  "description": "MCP Server fuer DACH-Buchhaltung (Lexoffice, Billomat, sevDesk)",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "buchpilot-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0"
+  }
+}