inferro-mcp

MCP-Server für die Konfiguration eines Inferro-Mandanten mit Claude Code: Der Assistent agiert als Mandanten-Administrator gegen die REST-API — Marktplätze, Unterkategorien, Produkte, Logistikzentren, Versand, Promo-Codes, Info-Seiten und Rechtstexte.

Die fachliche Dokumentation liest der Assistent von https://inferro.de/llms.txt.

Kommt der Nutzer mit seinem Anwendungsfall nicht weiter (fehlende Funktion oder Fehlverhalten), kann der Assistent — nach Zustimmung des Nutzers — direkt ein Support-Ticket beim Inferro-Support eröffnen und den Verlauf verfolgen: create_support_ticket (bug/feature), list_support_tickets, get_support_ticket, comment_support_ticket.

Voraussetzungen

1. Ein ADMIN-Konto im eigenen Mandanten.

2. Ein API-Schlüssel dieses Kontos — am einfachsten im Office unter Mandanten → eigener Mandant → Tab „KI-Assistenz“ (dort auch Liste und Widerruf). Alternativ per API (als Admin angemeldet):

   POST https://<api-host>/api/v1/api-keys
   X-Tenant-ID: <Mandanten-GUID>
   Authorization: Bearer <JWT>
   
   { "name": "claude-code" }

   Die Antwort enthält den Schlüssel (inferro_…) genau einmal — sicher ablegen. Verwalten: GET /api/v1/api-keys (Liste), DELETE /api/v1/api-keys/{id} (widerrufen).

Installation in Claude Code

claude mcp add inferro \
  --env INFERRO_BASE_URL=https://<api-host> \
  --env INFERRO_TENANT_ID=<Mandanten-GUID> \
  --env INFERRO_API_KEY=inferro_... \
  --env INFERRO_OFFICE_URL=https://office.<domain> \
  -- npx -y inferro-mcp

Das Office-UI zeigt diesen Befehl fertig ausgefüllt an: Mandanten → eigener Mandant → Tab KI-Assistenz (dort werden auch die API-Schlüssel erstellt und verwaltet).

Für die Entwicklung stattdessen aus dem Repo:

cd d-erp-mcp && npm install && npm run build
claude mcp add inferro --env ... -- node /pfad/zu/d-erp-mcp/dist/index.js

Danach in Claude Code z. B.: „Verschaffe dir mit get_setup_status einen Überblick und richte meinen Shop ein: Ich verkaufe …“

Sicherheitsmodell

• Der API-Schlüssel wirkt mit den Rechten seines Besitzers im eigenen Mandanten — fremde Mandanten sind durch das Backend ausgeschlossen (404).
• Zugangsdaten (Stripe, GLS, DHL, Postfach, Social Login) laufen nie über den Assistenten: Kein Werkzeug nimmt Secrets an; get_office_link verweist auf das Office-UI, wo der Kunde sie selbst einträgt.
• Schlüssel sind widerrufbar und serverseitig nur als SHA-256-Hash gespeichert.

Entwicklung

npm run build     # TypeScript → dist/
npm run smoke     # bootet den Server über stdio und listet die Werkzeuge

Veröffentlichen (npm)

Kunden beziehen den Server per npx -y inferro-mcp — dafür muss das Paket auf npm veröffentlicht sein. Releases laufen vollautomatisch über GitHub Actions; lokal wird weder npm version noch npm publish ausgeführt.

Release auslösen

GitHub ▸ Actions ▸ Release ▸ Run workflow:

| Eingabe | Bedeutung | | --- | --- | | release-type | patch / minor / major / prerelease — oder custom für eine exakte Version | | custom-version | nur bei release-type: custom, z. B. 1.4.0 | | dry-run | baut und packt nur, veröffentlicht nichts (guter Testlauf) |

Der Workflow baut (tsc), führt den Smoke-Test aus, erhöht die Version, veröffentlicht auf npm, pusht Commit und Tag nach main und erstellt ein GitHub-Release mit generierten Notes. Veröffentlicht wird vor dem Push: schlägt npm publish fehl, bleibt main unverändert und der Lauf kann einfach wiederholt werden.

Jeder Push und PR auf main wird zusätzlich vom CI-Workflow gegen Node 20, 22 und 24 gebaut und smoke-getestet.

Authentifizierung: npm Trusted Publishing

Es ist kein NPM_TOKEN im Repository hinterlegt. npm authentifiziert den Workflow über OIDC (GitHub Actions Identity) und hängt eine Provenance-Attestation an das Paket. Die Konfiguration liegt auf npmjs.com ▸ Paket inferro-mcp ▸ Settings ▸ Trusted Publisher: Owner dimamost, Repository d-erp-mcp, Workflow release.yml, Environment leer.

Damit das funktioniert, muss einmalig eingerichtet sein:

1. GitHub ▸ Settings ▸ Actions ▸ General ▸ Workflow permissions auf Read and write (sonst schlägt der Push von Commit und Tag fehl).
2. Ein erster Publish von Hand (npm publish) — der Trusted Publisher lässt sich erst an einem existierenden Paket konfigurieren.
3. Der Trusted Publisher selbst, wie oben beschrieben.

Kontrolle

npm view inferro-mcp version              # veröffentlichte Version
npm view inferro-mcp dist.attestations    # Provenance vorhanden?
npm pack --dry-run                        # was ins Paket wandert: dist/, package.json, README.md, LICENSE