informer-mcp

Ein Model Context Protocol-Server für die Informer-Buchhaltungs-API (v2). Er gibt jedem MCP-Client direkten Zugriff auf Ihre Kontakte, Verkaufs- und Einkaufsrechnungen, Angebote, Bestellungen, Belege, Produkte und Finanzberichte.

Jedes Tool ist aus Informers eigenem OpenAPI-Dokument (api.informer.eu/docs/v2) abgeleitet. Eine Kopie wird mit dem Server ausgeliefert, sodass er offline funktioniert, und er hält sich selbst aktuell – siehe Aktuell bleiben bei API-Änderungen.

Inoffizielles Projekt. Nicht mit Informer verbunden oder von Informer unterstützt.

Schnellstart

Fügen Sie dies in einen beliebigen KI-Assistenten ein, der MCP-Server installieren kann:

Install the following MCP server: https://github.com/vladxyz/informer-mcp and run the local setup screen for the API keys.

Er klont das Repository, baut es, registriert den Server bei Ihrem Client und führt dann informer-mcp setup aus – das öffnet eine Seite in Ihrem Browser unter 127.0.0.1. Auf dieser Seite geben Sie Ihre API-Zugangsdaten ein; im Chat wird nichts abgefragt, und es wird niemals ein Schlüssel in eine Unterhaltung eingefügt.

Was Sie auf dieser Seite sehen

Eine Karte pro Administration, plus Administration hinzufügen, wenn Sie mehr als eine verwalten:

┌─ Administration ────────────────────────────── Remove ─┐
│  ALIAS                        COMPANY NAME             │
│  [ acme                ]      [ ACME BV           ]    │
│  Short handle you use         Optional, shown in       │
│  in prompts.                  tool descriptions.       │
│                                                        │
│  API KEY                      SECURITY CODE            │
│  [ •••••••••••••••••  ]      [ •••••••••••••••  ]     │
│                                                        │
│  ACCESS                                                │
│  [ Read and write   ▾ ]                                │
│  Read only hides every tool that changes this          │
│  client's books.                                       │
└────────────────────────────────────────────────────────┘

  [ Add administration ]   [ Verify & save ]   ☐ Save without verifying

Beide Zugangsdaten gehören zu einer Administration, daher fügt ein Buchhalter pro Kunde eine Karte hinzu. Siehe Mehrere Kunden-Administrationen.

Was passiert, wenn Sie auf „Verifizieren & speichern“ klicken

1. Jedes Schlüssel-/Sicherheitscode-Paar wird gegen die API geprüft, und die Seite zeigt Ihnen den Firmennamen, zu dem es tatsächlich gehört – so fällt ein in die falsche Zeile eingefügter Schlüssel sofort auf, bevor etwas gespeichert wird.

2. Wird ein Paar abgelehnt, wird nichts geschrieben und die fehlerhafte Zeile benannt. Aktivieren Sie Ohne Verifizierung speichern, um es trotzdem zu speichern, zum Beispiel wenn Sie offline sind.

3. Im Erfolgsfall werden die Zugangsdaten mit den Berechtigungen 0600 in ~/.informer-mcp.json geschrieben. Wurde die Seite über open_setup geöffnet, übernimmt der laufende Server die Änderung sofort – eine neue Administration ist bereits in der nächsten Nachricht auswählbar. Wurde sie von einem Terminal aus geöffnet, starten Sie Ihren Client neu.

Fragen Sie „zu welchen Administrationen haben Sie Zugriff?“, um das zu bestätigen – das ruft list_administrations auf und listet jeden Alias mit seiner Firma auf.

Related MCP server: billingo-mcp

Was Sie erhalten

• 68 Tools, die alle 49 dokumentierten Endpunkte abdecken – lesen und schreiben.

• Setup im Browser. Bitten Sie Ihren Assistenten, die Setup-Seite zu öffnen, oder führen Sie informer-mcp setup aus. Es prüft jeden Schlüssel gegen die API, schreibt die Konfigurationsdatei, und die Änderung wird wirksam, ohne dass etwas neu gestartet werden muss.

• Folgt der API. Wenn Informer einen neuen Endpunkt veröffentlicht, erkennt der Server das und fügt das Tool hinzu, während Ihr Client verbunden bleibt – keine Neuinstallation, kein Neustart.

• Mehrere Kunden-Administrationen in einem Server. Buchhalter können von einer Verbindung aus auf die Bücher jedes Kunden zugreifen, mit einem administration-Argument, das erforderlich ist, sobald mehr als eine Administration konfiguriert ist.

• Eine Frage über das gesamte Portfolio. Schreibgeschützte Tools akzeptieren eine Liste von Aliasen oder "all" und fragen sie gleichzeitig ab; die Ergebnisse sind nach Kunde gruppiert.

• Vollständige Anforderungsschemas. Create-/Update-Tools geben das vollständige JSON-Schema für ihre Nutzlast an, sodass das Modell weiß, welche Felder existieren und welche erforderlich sind, bevor es etwas sendet.

• Schreibgeschützt oder beschreibbar, ganz nach Wahl. Ein --read-only-Flag blendet jedes Tool aus, das etwas ändert, und einzelne Clients können auf schreibgeschützt festgelegt werden, während die übrigen beschreibbar bleiben. Zulassungs-/Ablehnungslisten grenzen die Angriffsfläche weiter ein.

• PDFs und Anhänge werden aus Base64 dekodiert und können direkt auf die Festplatte geschrieben werden.

• Robustes HTTP. Timeouts, Wiederholungen mit Retry-After-Unterstützung und Informers niederländische Validierungsfehler, die unverändert angezeigt werden (HTTP 422: invoice_date: ongeldig).

Voraussetzungen

• Node.js 20 oder neuer

• Ein InformerOnline-Konto mit API-Zugriff

Einrichten Ihrer Zugangsdaten

Fragen Sie einfach im Gespräch:

„Ich möchte meine Informer-Administrationen ändern“ „Einen neuen Kunden zu Informer hinzufügen“ „Mein Informer-API-Schlüssel hat sich geändert“

Ihr Assistent ruft das open_setup-Tool auf und die Seite öffnet sich. Es gibt keine Konfigurationsdatei zu suchen und nichts von Hand zu bearbeiten – und da die Seite ein Browserformular ist, muss Ihr API-Schlüssel niemals in einen Chat eingegeben werden.

Dieselbe Seite von einem Terminal aus:

npm run setup          # or: informer-mcp setup

In beiden Fällen erhalten Sie http://127.0.0.1:<port> in Ihrem Browser, mit einem Formular für jede Administration: Alias, Firmenname, API-Schlüssel, Sicherheitscode und ob sie beschrieben werden darf. Beim Speichern wird jedes Paar gegen die API geprüft – so wird ein vertippter Schlüssel sofort erkannt, und Sie sehen den Firmennamen, zu dem jeder Schlüssel tatsächlich gehört – und anschließend werden ~/.informer-mcp.json mit den Berechtigungen 0600 geschrieben.

Wenn der Server ohne jegliche Zugangsdaten gestartet wird, öffnet er dieselbe Seite automatisch, denn genau dann brauchen Sie sie. Setzen Sie INFORMER_AUTO_SETUP=false, um das zu deaktivieren, oder INFORMER_OPEN_BROWSER=false auf einem Rechner ohne Bildschirm, um nur die URL auszugeben. Wie auch immer sie geöffnet wurde, es gibt immer nur eine Seite: Wenn Sie erneut danach fragen, erhalten Sie dieselbe URL zurück.

Einige Dinge, die die Seite bewusst tut:

• sie bindet nur an 127.0.0.1, und jeder Lauf erzeugt ein zufälliges Token, das in der URL und in der Speicheranfrage enthalten sein muss, sodass eine andere Website in Ihrem Browser nichts an sie senden kann;

• sie sendet gespeicherte Schlüssel niemals zurück an die Seite – vorhandene Administrationen erscheinen mit leeren Zugangsdaten und bleiben erhalten, es sei denn, Sie geben einen neuen Wert ein;

• sie weigert sich, Zugangsdaten zu speichern, die die API ablehnt, es sei denn, Sie aktivieren Ohne Verifizierung speichern.

Nichts hindert Sie daran, die Datei oder die Umgebungsvariablen von Hand zu schreiben; die Seite ist eine Annehmlichkeit, keine Voraussetzung.

Woher die Schlüssel kommen

Die API authentifiziert sich mit zwei Headern, beide erforderlich:

Beide sind auf eine Administration beschränkt: Der API-Schlüssel gehört zu der Administration, in der er erstellt wurde (GET /administration gibt „die mit diesem API-Schlüssel verknüpfte Administration“ zurück), und der Sicherheitscode identifiziert diese Firma. Es gibt keinen Endpunkt, der Administrationen auflistet oder zwischen ihnen wechselt.

Ein Schlüssel gewährt vollen Zugriff auf die Bücher dieser Administration. Behandeln Sie ihn wie ein Passwort: Bewahren Sie ihn in Ihrer Umgebung, einem Secret-Manager oder einer Konfigurationsdatei außerhalb des Repositorys auf.

Mehrere Kunden-Administrationen

Ein Buchhalter mit mehreren Kunden benötigt ein Schlüssel-/Sicherheitscode-Paar pro Kunden-Administration – ein Buchhalter-Benutzer mit Zugriff auf eine Administration kann sie über deren Einstellungen erstellen. Fügen Sie sie auf der Setup-Seite hinzu oder schreiben Sie ~/.informer-mcp.json (oder eine beliebige Datei, die durch INFORMER_CONFIG_FILE benannt wird) selbst:

{
  "administrations": {
    "acme":     { "label": "ACME BV",         "api_key": "...", "security_code": "..." },
    "bakkerij": { "label": "Bakkerij de Bol", "api_key": "...", "security_code": "...", "mode": "read-only" }
  }
}

Wenn mehr als eine Administration konfiguriert ist, erfordert jedes Tool ein administration-Argument, das als Aufzählung Ihrer Aliase angegeben wird:

list_sales_invoices({ "administration": "acme", "filter": "open" })

Es gibt bewusst keinen Standardwert. Eine Rechnung in die Bücher des falschen Kunden zu buchen ist der eine Fehler, der nicht still passieren darf. Daher wird ein Aufruf ohne das Argument bereits durch die Schema-Validierung abgelehnt, bevor eine HTTP-Anfrage gestellt wird – ebenso wie ein Alias, den Sie nie konfiguriert haben.

list_administrations zeigt die konfigurierten Aliase; übergeben Sie verify: true, um jeden Firmennamen von der API abzurufen. Das bestätigt sowohl, dass die Zugangsdaten funktionieren, als auch, dass jeder Alias auf das Unternehmen zeigt, das Sie vermuten.

Mehrere Clients gleichzeitig abfragen

Schreibgeschützte Tools akzeptieren auch eine Liste von Aliasen oder "all":

list_sales_invoices({ "administration": "all", "filter": "open", "records": 50 })
list_sales_invoices({ "administration": ["acme", "bakkerij"], "filter": "open" })

Die Administrationen werden gleichzeitig abgefragt (INFORMER_FANOUT_CONCURRENCY, standardmäßig vier auf einmal), und die Antwort ist nach Alias gruppiert:

{
  "administrations": ["acme", "bakkerij"],
  "results": {
    "acme": { "pagination": { "total": 3 }, "invoices": [ ... ] },
    "bakkerij": { "error": "[bakkerij] HTTP 401: Authentication failed" }
  }
}

Drei Eigenschaften, die Sie kennen sollten:

• Ein fehlgeschlagener Client bringt die Abfrage nicht zu Fall. Sein Eintrag enthält einen error, und die übrigen liefern weiterhin Daten.

• Das Antwortbudget wird gleichmäßig aufgeteilt. Jede Administration erhält INFORMER_MAX_RESPONSE_CHARS / n Zeichen, sodass ein großer Client die anderen nicht verdrängen kann; alles, was über seinen Anteil hinausgeht, wird als { "truncated": true, "partial": ... } zurückgegeben.

• Fan-out ist schreibgeschützt. Tools, die schreiben, und die PDF-/Anhang-Downloads akzeptieren einen einzelnen Alias – ihr Schema bietet nicht einmal das Array oder "all" an, und der Handler lehnt sie ein zweites Mal ab. Dieselbe Rechnung in zwölf Administrationen zu erstellen, ist kein Versehen, das man ermöglichen sollte.

Eine einzelne Administration gibt die API-Nutzlast weiterhin unverpackt zurück, genau wie zuvor.

Bei einer einzelnen Administration – dem häufigsten Fall – ändert sich nichts: Setzen Sie INFORMER_API_KEY und INFORMER_SECURITY_CODE wie gewohnt, und das Argument bleibt optional.

Installation

git clone https://github.com/vladxyz/informer-mcp.git
cd informer-mcp
npm install          # also builds dist/ via the prepare script
npm run setup        # opens a local page to enter your API credentials

Die Setup-Seite läuft auf 127.0.0.1, prüft jeden Schlüssel gegen die API und schreibt ~/.informer-mcp.json. Siehe Einrichten Ihrer Zugangsdaten.

Claude Desktop als Erweiterung

Der einfachste Weg: Ein Bundle erstellen und öffnen.

npm run bundle          # writes informer-mcp.mcpb

Gehen Sie in Claude Desktop zu Einstellungen → Erweiterungen → Erweiterte Einstellungen → Erweiterung installieren… und wählen Sie die .mcpb-Datei. Sie bringt ihre eigenen Abhängigkeiten mit, sodass außer Node.js 20 nichts zuerst installiert werden muss.

Der Installationsdialog bietet einen API-Schlüssel, einen Sicherheitscode und einen Nur-Lesen-Schalter. Sie können alle drei leer lassen: Der Server öffnet dann beim ersten Start seine Setup-Seite, was auch der einzige Weg ist, mehr als eine Administration zu konfigurieren.

Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen in Claude Desktop ist etwas anderes: Dort wird die URL eines entfernten MCP-Servers angegeben. Dieser Server läuft lokal über stdio und wird daher als Erweiterung statt als Connector installiert.

Claude Desktop, manuell

Bearbeiten Sie die Konfigurationsdatei direkt:

{
  "mcpServers": {
    "informer": {
      "command": "node",
      "args": ["C:\\path\\to\\informer-mcp\\dist\\index.js"]
    }
  }
}

Starten Sie Claude Desktop danach neu. Unter Windows müssen Backslashes in JSON verdoppelt werden; Schrägstriche funktionieren ebenfalls und sind leichter zu lesen.

Jeder andere MCP-Client

Der Server spricht MCP über stdio, daher konfiguriert ihn jeder Client auf dieselbe Weise – ein Befehl und seine Argumente. Der obige Block funktioniert unverändert in Claude Code (claude mcp add), Cursor, Zed oder allem anderen, das MCP spricht.

Die Zugangsdaten stammen aus ~/.informer-mcp.json, sodass sie nicht in der Client-Konfiguration wiederholt werden müssen. Um sie stattdessen pro Client zu übergeben, fügen Sie einen env-Block mit INFORMER_API_KEY und INFORMER_SECURITY_CODE hinzu oder verweisen Sie INFORMER_CONFIG_FILE auf einen anderen Speicherort.

Fügen Sie --read-only zu args hinzu, um einen Server zu registrieren, der nichts ändern kann — siehe Schreibgeschützt oder schreibend. Es funktioniert gut, denselben Server zweimal unter zwei Namen zu registrieren, einmal schreibgeschützt und einmal schreibend.

stdout transportiert das Protokoll, also geht die gesamte Protokollierung an stderr — ein einzeiliges Banner beim Start teilt mit, wie viele Werkzeuge registriert wurden und welche Verwaltungen gefunden wurden.

Schreibgeschützt oder schreibend

Standardmäßig ist jedes Werkzeug verfügbar. Um die Schreibwerkzeuge vollständig zu entfernen, starten Sie den Server mit einem Flag:

informer-mcp --read-only     # only the tools that read
informer-mcp --read-write    # the default: create, update and delete too

INFORMER_READ_ONLY=true bewirkt dasselbe, wobei das Flag Vorrang vor der Variable hat — Sie können also denselben Server zweimal in einem Client registrieren, einmal schreibgeschützt für alltägliche Fragen und einmal schreibend für die Sitzungen, in denen Sie tatsächlich etwas buchen.

Im schreibgeschützten Modus werden die Schreibwerkzeuge gar nicht erst registriert: Sie erscheinen nie in der Werkzeugliste, es gibt also nichts, wonach ein Modell greifen könnte.

Pro Client

Einzelne Verwaltungen können in der Konfigurationsdatei festgelegt werden, was dann nützlich ist, wenn Sie nur in die Bücher einiger Clients schauen dürfen:

{
  "administrations": {
    "acme":     { "api_key": "...", "security_code": "..." },
    "bakkerij": { "api_key": "...", "security_code": "...", "mode": "read-only" }
  }
}

"read_only": true funktioniert als Kurzform. Die restriktivste Einstellung gewinnt:

Ein als schreibgeschützt markierter Client kann also nie versehentlich beschrieben werden, und eine mit --read-only gestartete Sitzung bleibt dies auch, egal was die Konfigurationsdatei sagt.

Wenn einige Verwaltungen beschreibbar sind und andere nicht, bleiben die Schreibwerkzeuge registriert, aber ihre administration-Aufzählung bietet nur die beschreibbaren an. Die Aufforderung, eine Rechnung in einem schreibgeschützten Client zu erstellen, wird abgelehnt, bevor eine HTTP-Anfrage gesendet wird:

Administration(s) bakkerij are configured as read-only, so this tool cannot change them.
Writable: acme, garage.

list_administrations meldet den effektiven Modus jedes Clients, und das Startbanner fasst es zusammen: read-write: acme, garage.

Konfiguration

Filter akzeptieren entweder ein OpenAPI-Tag oder einen Werkzeugnamen und werden ohne Beachtung von Groß-/Kleinschreibung und Satzzeichen abgeglichen:

# read-only access to invoicing data
INFORMER_TOOLS="Sales Invoices,Relations" node dist/index.js --read-only

# everything except deleting attachments
INFORMER_EXCLUDE_TOOLS=delete_sales_invoice_attachment node dist/index.js

Verwendung

Fragen Sie nach dem Verbinden in einfacher Sprache:

• "Welche Verkaufsrechnungen aus 2026 sind noch unbezahlt?" → list_sales_invoices mit filter

• "Erstelle einen Rechnungsentwurf für ACME über 10 Stunden Beratung zu 125 €." → get_sales_invoice_options für gültige Sachkonto-/USt.-/Vorlagen-IDs, dann create_sales_invoice

• "Lade Rechnung 12345 als PDF auf meinen Desktop herunter." → get_sales_invoice_pdf mit save_path

• "Zeige die Bilanz für Periode 6 von 2026." → get_balance_report

Wissenswerte Konventionen

• Wählen Sie die Verwaltung explizit aus. Bei mehreren konfigurierten Clients akzeptiert jedes Werkzeug administration: "<alias>". list_administrations bildet Aliase auf Firmen ab, und schreibgeschützte Werkzeuge akzeptieren auch eine Liste oder "all".

• Daten sind immer JJJJ-MM-TT.

• Listenwerkzeuge werden paginiert über page (Standard 1) und records (Standard 20) und geben ein pagination-Objekt mit total und pages zurück.

• Anfragenutzlasten kommen in ein einziges body-Argument. Pfad- und Abfrageparameter bleiben auf oberster Ebene, sodass update_relation { "id": 42, "body": { ... } } akzeptiert.

• Rufen Sie zuerst das *_options-Werkzeug auf, wenn Sie Dokumente erstellen. get_sales_invoice_options, get_quotation_options und ähnliche geben die gültigen Sachkonto-, USt.-, Vorlagen-, Währungs- und Zahlungsbedingungs-IDs für Ihre Verwaltung zurück.

• Berichte benötigen explizite Bereiche. get_balance_report erfordert year_from, year_to und period; get_column_balance_report möchte zusätzlich einen Sachkontenbereich.

PDFs und Anhänge

Informer gibt Dateien als Base64 in JSON zurück. Werkzeuge, die dies tun (get_*_pdf, download_sales_invoice_attachment), akzeptieren ein optionales save_path:

• mit save_path — die Datei wird dekodiert und unter diesem Pfad gespeichert, und das Werkzeug gibt { saved_to, filename, bytes, mime_type } zurück;

• ohne — die Datei wird als Inline-MCP-Ressource mit dem richtigen MIME-Typ zurückgegeben, was bei großen Dokumenten im Kontext teuer werden kann.

Das Hochladen funktioniert umgekehrt: upload_sales_invoice_attachment akzeptiert { filename, file }, wobei file base64-kodierter Inhalt ist (max. 10 MB; PDF, PNG, JPEG, GIF, DOC(X), XLS(X)).

Werkzeugreferenz

npm run tools gibt diese Liste aus der aktuellen Spezifikation aus; npm run tools -- --md erzeugt die folgenden Tabellen neu.

Neben den Endpunkt-Werkzeugen gibt es drei vom Server bereitgestellte:

Verwaltung

Beziehungen

Kontakte

Verkaufsrechnungen

Einkaufsrechnungen

Wiederkehrende Rechnungen

Verkaufsaufträge

Angebote

Verkaufsbuch

Zahlungsbedingungen

Vorlagen

MwSt

Sachkonten

Kosten

Währungen

Journale

Abonnementtypen

Anhänge

Produkte

Belege

Memorandum

Berichte

Benennung der Tools

Die Namen werden aus der HTTP-Methode und dem Pfad abgeleitet, nicht aus Prosa, sodass sie über Spezifikations-Updates hinweg stabil bleiben:

Endpunkte, die die Benennungstabelle nicht erkennt, fallen auf <Verb>_<Pfad-Slug> zurück, sodass eine Spezifikations-Aktualisierung nie ein defektes Tool erzeugt.

Mit API-Änderungen Schritt halten

Die Tools werden aus dem OpenAPI-Dokument von Informer generiert. Wenn Informer also einen Endpunkt hinzufügt, fehlt nur eine frische Kopie dieses Dokuments. Der Server kann sie selbst abrufen.

Drei Ebenen, in der Reihenfolge ihrer Priorität:

1. Eine heruntergeladene Kopie, zwischengespeichert unter ~/.informer-mcp.spec.json.

2. Die gebündelte Kopie in openapi/api-docs.json, die mit dem Server ausgeliefert wird und immer offline funktioniert.

3. Keiner wird jemals blind vertraut – ein Download muss als OpenAPI-3-Dokument mit mindestens einer nutzbaren Operation geparst werden können, sonst wird er abgelehnt und die aktuellen Tools bleiben. Ein Captive-Portal oder eine Wartungsseite kann Ihre Tool-Sammlung nicht löschen.

Zeitgesteuert

Einmal täglich, kurz nach dem Start, prüft der Server im Hintergrund auf ein neueres Dokument. Der Start wird nie blockiert, und eine fehlgeschlagene Prüfung wird protokolliert und ignoriert. INFORMER_SPEC_MAX_AGE_HOURS=0 deaktiviert dies.

Auf Anfrage

Das Tool refresh_api_spec macht dasselbe, wenn Sie es anfordern – nützlich, wenn ein erwarteter Endpunkt fehlt oder ein Argument als unbekannt abgelehnt wird:

"Aktualisieren Sie die Informer-API-Beschreibung und sagen Sie mir, was sich geändert hat."

{
  "adopted": true,
  "api_version": "2.0.0",
  "endpoints": 49,
  "tools": 68,
  "changes": {
    "added":   [{ "tool": "list_projects", "endpoint": "GET /projects" }],
    "removed": [],
    "changed": [{ "tool": "create_sales_invoice", "endpoint": "POST /invoices/sales",
                  "notes": ["body now requires: project_id"] }],
    "unchanged": 66
  },
  "note": "The tool list has been updated; no restart is needed."
}

Übergeben Sie dry_run, um diesen Bericht zu sehen, ohne etwas anzuwenden.

Der Diff ist bewusst spezifisch: Er nennt die Tools, die erschienen und verschwunden sind, und für die geänderten sagt er, was sich geändert hat – ein neues Argument, ein entferntes, ein Feld, das jetzt erforderlich ist. Das ist der Teil, den ein bloßer Pfadvergleich übersieht, und es ist normalerweise der Teil, der sonst als rätselhafter 422 auftauchen würde.

Das Übernehmen eines Dokuments aktualisiert den laufenden Server: Neue Tools werden registriert, zurückgezogene entfernt, geänderte neu beworben, und eine tools/list_changed-Benachrichtigung wird gesendet, damit Ihr Client die Liste während der Sitzung neu lädt.

Die Kopie im Repository

npm run update-spec aktualisiert das gebündelte Dokument und meldet, welche Pfade kamen und gingen. Das ist das, was Sie ausführen sollten, wenn Sie die Änderung für alle committen möchten, die den Server installieren; refresh_api_spec betrifft nur Ihren eigenen Rechner.

Ressourcen

Der Server stellt das OpenAPI-Dokument auch als MCP-Ressource unter informer://openapi.json bereit, was praktisch ist, wenn Sie möchten, dass das Modell eine Felddefinition überprüft, ohne zu raten.

Entwicklung

npm install         # install + build
npm run setup       # enter credentials in the browser
npm run bundle      # package as informer-mcp.mcpb for one-click install
npm run dev         # run from source with tsx
npm test            # vitest
npm run typecheck   # tsc --noEmit
npm run build       # compile to dist/
npm run tools       # print the tool surface
npm run update-spec # re-download openapi/api-docs.json and report added/removed paths

Projektstruktur

openapi/api-docs.json   vendored OpenAPI 3.0 document — the source of truth
src/openapi.ts          spec → operations: tool names, JSON Schema conversion
src/client.ts           HTTP client: auth headers, retries, error formatting
src/tools.ts            operations → MCP tools, filtering, result formatting
src/server.ts           server assembly (tools + openapi resource)
src/spec.ts             download, validate, cache and diff the OpenAPI document
src/setup.ts            local setup server: verify credentials, write the config file
src/setup-page.ts       the HTML it serves
src/index.ts            stdio entry point and CLI
manifest.json           extension manifest: entry point and install-time settings
scripts/update-spec.mjs refresh the vendored spec
scripts/list-tools.ts   print/regenerate the tool reference
scripts/bundle.mjs      stage production dependencies and pack the .mcpb

Das Hinzufügen von Endpunkten ist normalerweise überhaupt keine Codeänderung – der laufende Server übernimmt sie von selbst, und npm run update-spec committet dieselbe Änderung in die gebündelte Kopie. Nur wirklich neue URL-Formen benötigen eine Regel in der RESOURCES-Tabelle in src/openapi.ts; ohne eine werden sie trotzdem zu Tools, nur mit einem langweiligeren Namen.

Wie Schemas konvertiert werden

OpenAPI 3.0 ist nicht ganz JSON Schema. Auf dem Weg zur MCP-Tool-Definition:

• #/components/schemas/X-Referenzen werden zu #/$defs/X, wobei nur die transitive Hülle, die jede Operation tatsächlich benötigt, inline eingefügt wird – so bleiben Tool-Definitionen klein;

• nullable: true wird zu einer ["type", "null"]-Vereinigung;

• Pfad- und Query-Parameter werden zu Top-Level-Eigenschaften, Request-Bodies kommen unter body, und additionalProperties: false verhindert, dass Tippfehler die API erreichen.

Argumente werden vor jedem HTTP-Aufruf gegen dieses Schema validiert.

Sicherheitshinweise

• Dieser Server kann echte Buchhaltungsdatensätze erstellen, aktualisieren und löschen. Beginnen Sie mit --read-only, wenn Sie nur Berichte benötigen, pinnen Sie einzelne Clients mit "mode": "read-only" und lassen Sie Ihren MCP-Client bei Schreibwerkzeugen um Genehmigung bitten.

• Anmeldedaten für mehrere Clients in einem Prozess bedeuten, dass ein fehlgeleiteter Aufruf die Bücher eines anderen berührt. Das erforderliche administration-Argument, die Aufzählung bekannter Aliase, die Nur-Lese-Beschränkung für Fan-out und das Alias-Präfix in jeder Fehlermeldung ([acme] HTTP 422: ...) existieren alle aus diesem Grund. Halten Sie die Konfigurationsdatei aus der Versionskontrolle heraus und nur für Sie lesbar.

• Werkzeuge sind mit readOnlyHint, destructiveHint und idempotentHint annotiert, sodass Clients, die diese Hinweise verwenden, die riskanten abschirmen können.

• Es wird nichts auf stdout protokolliert, und Anmeldedaten werden niemals in der Werkzeugausgabe angezeigt oder an die Einrichtungsseite zurückgesendet. open_setup gibt eine URL zurück, niemals einen Schlüssel – ein Assistent hat keine Möglichkeit, Ihre Anmeldedaten zu lesen, und keinen Grund, Sie in einem Chat danach zu fragen.

• Die API-Beschreibung wird ohne Anmeldedaten heruntergeladen, und ein Dokument, das nicht als brauchbare OpenAPI-3-Datei geparst werden kann, wird abgelehnt statt übernommen.

Lizenz

MIT — siehe LICENSE.