MCP4Acumatica

Haftungsausschluss: Dieses Projekt ist eine unabhängige, von der Community entwickelte Integration und steht in keiner Verbindung zu Acumatica, Inc. und wird von diesem weder unterstützt noch befürwortet. „Acumatica“ ist eine eingetragene Marke von Acumatica, Inc. Die Verwendung des Namens und der API von Acumatica dient ausschließlich Interoperabilitätszwecken.

Ein entfernter Model Context Protocol (MCP)-Server, der Claude mit Acumatica ERP 2025 R2 verbindet. Läuft auf Cloudflare Workers mit benutzerspezifischer OAuth-Authentifizierung gegen Ihre Acumatica-Instanz.

Jeder Benutzer authentifiziert sich mit seinen eigenen Acumatica-Anmeldedaten. Seine Acumatica-Rolle steuert, auf welche Datensätze er zugreifen kann. Der MCP-Server erfordert zusätzlich eine bestimmte Acumatica-Rolle für den Zugriff, zeigt einen Zustimmungsbildschirm an und schwärzt automatisch sensible Felder, bevor Daten das KI-Modell erreichen.

Funktionen

• 49 Tools – 38 schreibgeschützte Abfragen + 6 Dienstprogramme/Erkennung + 4 Schema-Wissen + 1 Schreib-Tool (Kunde erstellen/aktualisieren, standardmäßig deaktiviert) (siehe Verfügbare Tools)

• Benutzerspezifisches OAuth – Benutzer melden sich mit ihren Acumatica-Anmeldedaten (oder SSO) an

• Rollenbasierter Zugriff – Acumaticas Sicherheitsmodell bestimmt, was jeder Benutzer sieht

• Zugangssperre – nur Benutzer, die eine bestimmte Kanarien-Generic-Inquiry lesen können, können sich verbinden (beschränken Sie sie nach Belieben; eine Markierungsrolle wie MCP Access wird empfohlen)

• Zustimmungsbildschirm – Benutzer müssen die KI-Datenverarbeitung bestätigen, bevor sie auf Tools zugreifen können

• Schwärzung sensibler Felder – SSN, Bankkonten, Gehalt und andere personenbezogene Daten werden automatisch geschwärzt, bevor Daten den Server verlassen

• Ratenbegrenzung – Standardmäßig 3 gleichzeitige Anfragen und 40 Anfragen pro Minute pro Benutzer, beide über die Admin-Konsole anpassbar. Eine Anfrage, die alle Slots belegt vorfindet, wartet kurz auf einen, anstatt sofort zu scheitern, und eine Ablehnung gibt eine strukturierte { error: "rate_limited", retryAfterSeconds, actionRequired }-Hülle zurück, die der KI genau sagt, wie lange sie warten soll, anstatt in einer Schleife zu wiederholen

• Ablehnung der Paginierung – Listen-/Abfrage-Tools geben eine strukturierte { truncated, paginationSupported: false, actionRequired }-Hülle zurück, wenn Ergebnisse die Datensatzobergrenze erreichen, und weisen die KI an, den Benutzer um einen engeren Filter zu bitten, anstatt das Tool erneut aufzurufen

• Strukturierte Audit-Protokollierung – alle Tool-Aufrufe, Authentifizierungsereignisse und Feld-Schwärzungen werden protokolliert

• Admin-Konsole – webbasierte Admin-Oberfläche unter /docs/admin zum Anzeigen von Protokollen und Verwalten von Laufzeiteinstellungen ohne erneutes Bereitstellen

• Langfristige Protokollaufbewahrung – R2-gestützte Protokollspeicherung über Cloudflare Logpush mit durchsuchbarem Protokollbetrachter

Related MCP server: MCP4Acumatica

Architektur

Claude (claude.ai / Desktop / API)
    |
    v  MCP over streamable-http
+----------------------------------+
|  Cloudflare Worker               |
|  OAuth 2.1 Provider              |
|    /authorize -> Acumatica login |
|    /callback  <- Acumatica       |
|    (access gate + OIDC userinfo) |
|    /consent   -> AI data consent |
|    /token, /register (DCR)       |
|    /mcp -> McpAgent DO (49 tools)|
+---------------+------------------+
                |  Bearer token (per-user)
                v
        Acumatica 25R2 SaaS
        Contract-Based REST API
        Default/25.200.001

Voraussetzungen

• Node.js >= 18

• Ein Cloudflare-Konto (Workers-Paid-Plan für Durable Objects)

• Eine Acumatica 2025 R2-Instanz mit:

  • Einer Connected Application, die in SM303010 mit dem Authorization Code OAuth 2.0-Flow konfiguriert ist (Scopes werden vom Server in der Anfrage gesendet, nicht in der App konfiguriert)

  • Einer Redirect-URI, die auf den /callback-Endpunkt Ihres Workers zeigt

  • Einer MCPAccess Generic Inquiry (SM208000) – einer trivialen Kanarien-GI mit aktiviertem Expose via OData; die Anmelde-Zugangssperre prüft, ob der Benutzer sie lesen kann (siehe Architektur-Dokumentation für Details). Der GI-Name ist über ACUMATICA_CANARY_GI konfigurierbar.

  • Einer Möglichkeit, einzuschränken, wer diese GI lesen kann – eine Markierungsrolle MCP Access (SM201005), die nur berechtigten Benutzern zugewiesen wird, ist der empfohlene Ansatz

Einrichtung

Es gibt drei Installationspfade. Alle drei basieren auf denselben acumatica-seitigen Voraussetzungen – erledigen Sie diese zuerst (siehe „Acumatica-seitige Konfiguration" unten), unabhängig davon, welchen Pfad Sie wählen.

Pfad A – Deploy to Cloudflare-Button (kein Terminal)

Der Button forkt dieses Repository in Ihr GitHub-Konto, liest wrangler.jsonc, erstellt automatisch den KV-Namespace und den R2-Bucket, fordert Geheimnisse an und stellt bereit. Schritt für Schritt:

1. Klicken Sie auf den Button. Cloudflare fordert Sie auf, sich anzumelden (oder ein Konto zu erstellen) und einen GitHub-Fork zu autorisieren.

2. Bestätigen Sie die Bindungen. Sie werden aufgefordert, KV-Namespaces zweimal zu erstellen – einmal für die TOKEN_STORE-Bindung (App-Daten: Token, OAuth-Status, Cache, Konfiguration, Admin-Sitzungen) und einmal für OAUTH_KV (intern von der OAuth-Bibliothek verwendet). Dies ist beabsichtigt: Es sind zwei separate Bindungen, die niemals Schlüssel teilen.

   ⚠️ Geben Sie den beiden Namespaces unterschiedliche Namen (z. B. mcp4acumatica-app für TOKEN_STORE und mcp4acumatica-oauth für OAUTH_KV). Die automatische Bereitstellung von Cloudflare leitet den Standardtitel vom Worker-Namen ab, daher standardmäßig beide Felder auf mcp4acumatica – und das Erstellen von zwei Namespaces mit demselben Titel schlägt fehl mit "Cannot provision a KV Namespace with the title … because it already exists." Wenn Sie diesen Fehler bereits erhalten haben, wurde ein halbfertiger Namespace zurückgelassen: Gehen Sie zu Storage & Databases → KV und löschen Sie den verwaisten mcp4acumatica-Namespace, dann wiederholen Sie den Vorgang mit zwei unterschiedlichen Namen. (Die GUI-Autoprovisionierung von Cloudflare kann nicht beide Bindungen auf einen Namespace verweisen, und die Konfiguration kann keine unterschiedlichen Titel voreinstellen – daher sind zwei separate Namespaces mit unterschiedlichen Namen der richtige Weg. Wenn die GUI weiterhin fehlschlägt, verwenden Sie einen Terminal-Installationspfad unten: setup.sh erstellt einen Namespace und bindet beide daran.)

   Die R2-Buckets (mcp4acumatica-logs, mcp4acumatica-index) werden auf die gleiche Weise erstellt, aber ihre Namen sind in wrangler.jsonc festgelegt, sodass sie nicht kollidieren.

3. Legen Sie Geheimnisse fest. Wenn Sie dazu aufgefordert werden, fügen Sie ein:

   • ACUMATICA_CLIENT_ID – aus Ihrer Connected Application (SM303010)

   • ACUMATICA_CLIENT_SECRET – vom selben Bildschirm

   • COOKIE_ENCRYPTION_KEY – öffnen Sie die Browser-Konsole auf einer beliebigen Seite und führen Sie aus:

     [...crypto.getRandomValues(new Uint8Array(32))].map(b => b.toString(16).padStart(2,'0')).join('')

     Kopieren Sie die resultierende 64-stellige Hex-Zeichenfolge.

   • ADMIN_SECRET – ein beliebiges Passwort, das Sie sich merken werden (schützt die /docs/admin-Konsole). Generieren Sie eines mit [...crypto.getRandomValues(new Uint8Array(24))].map(b => b.toString(16).padStart(2,'0')).join(''), wenn Sie keine Präferenz haben.

4. Bereitstellen. Cloudflare verbindet den Fork mit Workers Builds und pusht die erste Bereitstellung.

5. Aktualisieren Sie die Acumatica-Variablen. Nach Abschluss der Bereitstellung öffnen Sie Workers & Pages → mcp4acumatica → Settings → Variables and Secrets im Cloudflare-Dashboard und bearbeiten:

   • ACUMATICA_URL (z. B. https://ihre-firma.acumatica.com)

   • ACUMATICA_TENANT (Ihr Anmeldeunternehmen)

   • Optional ACUMATICA_MAX_RECORDS, ACUMATICA_CANARY_GI, REDACT_PATTERNS, REDACT_SKIP Klicken Sie auf Save and Deploy – Cloudflare stellt mit den neuen Werten erneut bereit.

6. Fügen Sie eine Redirect-URI zu Ihrer Connected Application hinzu. Ihr Worker ist jetzt unter https://mcp4acumatica.<ihr-konto>.workers.dev erreichbar. Fügen Sie https://<dieser-host>/callback zu den Redirect-URIs im Acumatica-Bildschirm SM303010 hinzu. (Um stattdessen eine benutzerdefinierte Domain zu verwenden, siehe „Benutzerdefinierte Domain (optional)" unten.)

7. Testen Sie die Bereitstellung. Besuchen Sie https://<ihr-host>/docs/admin/preflight, melden Sie sich mit Ihrem ADMIN_SECRET an und führen Sie die Preflight-Diagnose aus. Sie testet die Acumatica-Konnektivität, den OIDC-Discovery-Endpunkt, die Connected-App-Anmeldeinformationen, den Tenant-Pfad und die Vertrags-API-Version – jede Fehlkonfiguration wird namentlich genannt.

Danach kann sich Claude verbinden (siehe „Claude verbinden" unten).

Pfad B – Einzeiliger Installer (Terminal)

Wenn Sie bereits git, node und npm haben, führen Sie aus:

curl -fsSL https://mcp4acumatica.hallboys.com/install.sh | bash

Dies klont das Repository, installiert Abhängigkeiten und führt ./setup.sh aus. Das Setup-Skript fragt nach den Acumatica-Werten, die Sie angeben müssen (URL, Tenant, Connected-App-Client-ID und -Geheimnis), generiert automatisch die Krypto-Geheimnisse, erstellt den KV-Namespace und den R2-Bucket, lädt Geheimnisse hoch, stellt bereit und führt dann die Preflight-Prüfung durch.

Wenn Sie das Skript zuerst überprüfen möchten:

curl -fsSL https://mcp4acumatica.hallboys.com/install.sh -o install.sh
less install.sh   # read it
bash install.sh   # then run

Pfad C – Manuelle Einrichtung (Terminal)

1. Klonen und installieren

git clone https://github.com/hallboys/MCP4Acumatica.git
cd MCP4Acumatica
npm install

2. KV-Namespace erstellen

npx wrangler kv namespace create TOKEN_STORE

Notieren Sie die Namespace-ID aus der Ausgabe – Sie werden sie im nächsten Schritt in wrangler.jsonc einfügen. Dieselbe ID wird sowohl für die TOKEN_STORE- als auch für die OAUTH_KV-Bindung verwendet.

3. Wrangler konfigurieren

wrangler.jsonc wird im Repository als Bereitstellungsvorlage verfolgt. Bearbeiten Sie es direkt und füllen Sie aus:

• Die KV-Namespace-ID aus Schritt 2 (sowohl TOKEN_STORE- als auch OAUTH_KV-Bindung – gleiche ID)

• ACUMATICA_URL – Ihre Acumatica-Instanz-URL (z. B. https://ihre-firma.acumatica.com)

• ACUMATICA_TENANT – Ihr Acumatica-Unternehmen/Tenant-Name

Um Ihre lokalen Werte aus git status herauszuhalten (damit Sie weiterhin Updates pullen können, ohne Konflikte zu verursachen):

git update-index --skip-worktree wrangler.jsonc

4. Geheimnisse festlegen

npx wrangler secret put ACUMATICA_CLIENT_ID
npx wrangler secret put ACUMATICA_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY      # use `openssl rand -hex 32`
npx wrangler secret put ADMIN_SECRET                # any password — protects /docs/admin

5. Bereitstellen

npx wrangler deploy

6. Lokale Entwicklung (optional)

cp .dev.vars.example .dev.vars
# Edit .dev.vars with your Acumatica credentials
npx wrangler dev

Acumatica-seitige Konfiguration

Diese Schritte sind unabhängig vom gewählten Installationspfad erforderlich. Sie können nicht automatisiert werden – die Acumatica-API macht sie nicht zugänglich.

Connected Application (SM303010)

1. In Acumatica: System > Integration > Connected Applications (SM303010).

2. Erstellen Sie eine neue Connected Application.

3. Setzen Sie den OAuth 2.0 Flow auf Authorization Code.

4. Fügen Sie eine Redirect-URI hinzu: https://<ihre-worker-url>/callback (verwenden Sie den *.workers.dev-Hostnamen oder Ihre benutzerdefinierte Domain).

5. Notieren Sie sich die Client-ID und das Client-Geheimnis – Sie werden diese als Geheimnisse während der Bereitstellung angeben.

Es gibt hier kein Scope-Feld zum Konfigurieren. OAuth-Scopes (api openid profile email offline_access, einschließlich des offline_access, der Acumatica veranlasst, Refresh-Tokens auszustellen) werden vom MCP-Server in der Autorisierungsanfrage gesendet – sie werden nicht in der Connected Application festgelegt.

Zugangssperre: Kanarien-Generic-Inquiry (SM208000, SM201005)

Bevor ein Benutzer auf die KI-Tools zugreifen kann, führt der Anmeldevorgang eine Zugangssperre durch: Er fragt eine triviale Kanarien-Generic-Inquiry über OData ab und prüft, ob das Token des Benutzers sie lesen kann (200 → erlaubt, 403 → verweigert). Der Server überprüft niemals die Acumatica-Rollenmitgliedschaft – er fragt nur „Können Sie diese eine GI sehen?“. Sie schränken ein, wer die Kanarien-GI lesen kann, wie es Ihr Sicherheitsmodell bevorzugt; eine Markierungsrolle ist der empfohlene, sauberste Weg.

1. Erstellen Sie die Kanarien-GI: System > Customization > Generic Inquiry (SM208000) → erstellen Sie eine GI mit dem Namen MCPAccess mit einer beliebigen trivialen Abfrage (eine einzelne Spalte aus einer beliebigen Tabelle ist in Ordnung). Aktivieren Sie Expose via OData.

2. Schränken Sie ein, wer sie lesen kann (empfohlen: eine Markierungsrolle): System > Access Rights > User Roles (SM201005) → erstellen Sie eine Rolle mit dem Namen MCP Access ohne Bildschirmberechtigungen, weisen Sie die MCPAccess-GI nur dieser Rolle zu, dann weisen Sie die Rolle jedem Benutzer zu, der KI-Assistentenzugriff haben soll. Jeder andere Mechanismus, der den OData-Lesezugriff auf die GI steuert, funktioniert ebenfalls.

Der Name der Kanarien-GI ist über die Variable ACUMATICA_CANARY_GI konfigurierbar (Standard MCPAccess). Bearbeiten Sie ihn im Cloudflare-Dashboard (Variables and Secrets) oder in wrangler.jsonc.

Generic Inquiry-Exposition gegenüber KI (dringend empfohlen)

Eine ausgereifte Acumatica-Instanz kann hunderte von generischen Abfragen enthalten, die meisten für menschliche Bildschirme konzipiert (breite Berichtsraster, Dashboards, Ad-hoc-Abfragen). Wenn man sie alle dem Assistenten zugänglich macht, überflutet dies seinen Kontext und führt dazu, dass er die falsche Abfrage auswählt – und schlimmer noch: Eine parametrisierte GI, die über OData verfügbar gemacht wird, gibt stillschweigend falsche Daten zurück: Ohne ihre Parameter abgefragt, gibt Acumatica standardmäßig ungefilterte Zeilen ohne Fehler zurück, was das Modell nicht erkennen kann. Das GI-Exposure-Gate kehrt dies zu Opt-in um: Sie kennzeichnen die GIs, die für einen KI-Agenten tatsächlich nützlich und korrekt abzufragen sind (ExposedToMCP), und das Modell sieht nur diese.

Das Gate ist inaktiv, bis Sie es konfigurieren – der Server läuft, aber ohne Registrierung kann der Assistent keine GIs entdecken (acumatica_list_generic_inquiries gibt nichts zurück; ein Benutzer kann eine GI dennoch mit genauem Namen ausführen). Die Konfiguration gibt dem Assistenten einen kuratierten Satz, den er sicher entdecken kann. Die Aktivierung ist ein einmaliges Acumatica Anpassungsprojekt – gebündelt in acumatica/, fügt es die benutzerdefinierten Felder UsrExposedToMCP / UsrAIDescription (GIDesign) und UsrResAIDescription (GIResult) sowie die SM208000-Formularänderungen hinzu – gefolgt von den Feed-GIs MCPGIs / MCPGIFields, Lesezugriff auf die Feeds für die Rolle MCP Access und der Kennzeichnung der GIs, die Sie verfügbar machen möchten. Siehe docs/generic-inquiries.md.

Siehe Generische Abfragen für die vollständige Begründung, wie Sie entscheiden, welche GIs verfügbar gemacht werden sollen, und die Schritt-für-Schritt-Einrichtung.

Custom-Domain (optional)

Die Bereitstellung gibt Ihnen standardmäßig einen *.workers.dev-Hostnamen. Um einen gebrandeten Hostnamen anzuhängen:

• Über das Cloudflare-Dashboard: Workers & Pages → mcp4acumatica → Settings → Domains & Routes → Add. Die Zone der Domain muss sich in Ihrem Cloudflare-Konto befinden.

• Über wrangler.jsonc: Kommentieren Sie den routes-Block am Anfang der Datei aus, bearbeiten Sie pattern und zone_name, und stellen Sie erneut bereit.

Wenn Sie Hostnamen ändern, denken Sie daran, die neue https://<host>/callback zu den Redirect-URIs Ihrer Verbundenen Anwendung in SM303010 hinzuzufügen.

Claude verbinden

Claude.ai / Claude Desktop

1. Gehen Sie zu Settings > Connectors

2. Klicken Sie auf Add Connector und geben Sie die URL ein: https://<your-worker-url>/mcp

3. Bei der ersten Verwendung werden Sie zu Ihrer Acumatica-Anmeldeseite weitergeleitet

4. Wenn Ihr Konto die Canary-GI lesen kann (d.h. Ihnen wurde Zugriff gewährt), sehen Sie eine Zustimmungsseite, die die KI-Datenverarbeitung erklärt

5. Nach der Zustimmung hat Claude Zugriff auf alle 49 Tools

Claude Code (CLI)

claude mcp add acumatica-erp --transport streamable-http https://<your-worker-url>/mcp

API (über Anthropic SDK)

Bei Verwendung der Anthropic-API mit MCP verweisen Sie den MCP-Client auf https://<your-worker-url>/mcp. Der Server unterstützt OAuth 2.1 mit Dynamic Client Registration unter /register.

Verfügbare Tools

Kern

Finanzen / Buchhaltung

Lager & Warenwirtschaft

Einkauf

Projekte

Service & Außendienst

Vertrieb & CRM

Versand & Auftragsabwicklung

HR & Lohnabrechnung

CRM-Aktivitäten

Hilfsprogramme / Entdeckung

Tipp: Verwenden Sie zuerst acumatica_describe_entity, um verfügbare Felder zu entdecken, dann acumatica_list_entities zum Suchen/Filter. Für Generische Abfragen verwenden Sie acumatica_list_generic_inquiries, um GI-Namen zu finden, und acumatica_describe_inquiry, um verfügbare Felder zu sehen. Siehe docs/example-prompts.md für Verwendungsmuster.

Dokumentation

Detaillierte Dokumentation finden Sie im Ordner docs/:

• Tool-Referenz -- Vollständige Spezifikation aller 49 Tools mit Parametern und Endpunkten

• Beispiel-Prompts -- Beispiel-Prompts für Claude und andere MCP-Clients, organisiert nach Anwendungsfall

• OData-Filteranleitung -- Leitfaden zu $filter, $orderby, $select, $expand und $top-Abfrageparametern

• Generische Abfragen -- Warum GIs für die KI-Nutzung gesperrt sind, welche GIs verfügbar gemacht werden sollen und wie das Opt-in-Register aktiviert wird

• Schema-Wissen -- Offline-Schema-Erkennungstools zum Erstellen von Integrationen/Anpassungen und wie der Schema-Index aufgebaut wird

• Architektur -- Detaillierte Architektur, OAuth-Ablauf, Sicherheitsmodell und Designentscheidungen

• Self-Hosting-Anleitung -- So führen Sie den MCP-Server auf Node.js oder anderen Plattformen außerhalb von Cloudflare aus

• Acumatica aktualisieren -- Schritte beim Wechseln oder Aktualisieren der verbundenen Acumatica-Version

Skills

Wiederverwendbare Claude-Skills, die mit diesem Repo ausgeliefert werden, in skills/:

• acumatica-gi-descriptions -- End-to-End-Prozess zum Schreiben von KI-bezogenen Beschreibungen für Generische Abfragen und deren Ergebnisspalten, basierend auf den eigenen Entwurfsmetadaten der GI (Tabellen, Joins, WHERE-Bedingungen, Spalten) und nicht aus Namen erraten. Enthält die Plattform-Fallen, die Bulk-GI-Metadatenarbeit stillschweigend schiefgehen lassen, eine Checkliste von Entwurfssignalen, die es zu finden gilt, und drei Skripte für Kürzungsaudit, Entwurfsbriefing und Entwurfsvalidierung.

Um es zu verwenden, verweisen Sie Claude auf das Skill-Verzeichnis oder kopieren Sie es in Ihr eigenes .claude/skills/.

Sicherheit

• Keine gespeicherten Anmeldeinformationen. Der MCP-Server speichert keine Acumatica-Passwörter. Er verwendet den OAuth-2.0-Autorisierungscode-Flow – Benutzer authentifizieren sich direkt bei Acumatica.

• Pro-Benutzer-Tokens. Das Acumatica-Zugriffstoken jedes Benutzers wird im plattformeigenen Schlüssel-Wert-Speicher (Cloudflare KV bei der Standardbereitstellung) gespeichert und auf den Benutzernamen beschränkt. Tokens werden bei Ablauf automatisch aktualisiert. Wenn ein Refresh-Token abläuft, authentifiziert sich die Verbindung automatisch neu, anstatt eine manuelle Neuverbindung zu erfordern.

• Zugangskontrolle. Nur Benutzer, die eine bestimmte Canary Generic Inquiry lesen können, können eine Verbindung herstellen. Der Server überprüft die GI-Lesbarkeit über OData während des Logins (nicht über die Rollenmitgliedschaft); Benutzer ohne Zugriff sehen eine Zugriffsverweigerungsseite. Beschränken Sie die GI nach Belieben – eine Markierung „MCP Access“-Rolle wird empfohlen. Der GI-Name ist über ACUMATICA_CANARY_GI konfigurierbar.

• Einwilligungsdialog. Nach der Zugangsprüfung müssen Benutzer bestätigen, dass ihre Daten von einem externen KI-Modell verarbeitet werden, bevor die MCP-Sitzung aktiviert wird.

• Schwärzung sensibler Felder. Tool-Antworten werden automatisch auf sensible Feldnamen (SSN, Bankkonten, Gehalt, Kreditkarte usw.) überprüft und übereinstimmende Werte durch [REDACTED] ersetzt. Muster sind über die Umgebungsvariablen REDACT_PATTERNS und REDACT_SKIP konfigurierbar.

• Rollenbasierter Zugriff. Die Acumatica-Rolle des Benutzers bestimmt, welche Datensätze er lesen kann. Wenn ein Benutzer in Acumatica keinen Zugriff auf einen Datensatz hat, kann er auch über den MCP-Server nicht darauf zugreifen.

• Nur-Lesen. Alle aktuellen Tools sind reine Leseabfragen. Es werden keine Daten erstellt, geändert oder gelöscht.

• Ratenbegrenzung. 3 gleichzeitige Anfragen, 40 Anfragen pro Minute und standardmäßig eine Obergrenze von 1000 Datensätzen pro Abfrage – alles über die Admin-Konsole unter /docs/admin/settings konfigurierbar, ohne erneutes Bereitstellen. Grenzen gelten pro Benutzer und zählen HTTP-Aufrufe an Acumatica (nicht Tool-Aufrufe). Ablehnungen geben eine strukturierte Hülle mit einem genauen retryAfterSeconds zurück und werden als rate_limit_hit-Ereignisse protokolliert, sodass Sie erkennen können, ob die Grenzen zu eng sind.

• Verweigerung der Paginierung. Die Listen-/Abfrage-Tools (acumatica_list_entities, acumatica_run_inquiry, acumatica_list_generic_inquiries) unterstützen keine Paginierung. Wenn eine Antwort ACUMATICA_MAX_RECORDS erreicht, gibt das Tool eine strukturierte Hülle zurück (truncated: true, paginationSupported: false, actionRequired: "..."), die die KI anweist, anzuhalten und den Benutzer nach einem engeren Filter zu fragen, anstatt weitere Datensätze abzurufen.

• Prüfprotokollierung. Alle Tool-Aufrufe, Authentifizierungsereignisse (Login-Erfolg/-Verweigerung, Einwilligung akzeptiert) und Felderschwärzungsereignisse werden als strukturiertes JSON protokolliert. Anzeigen mit npx wrangler tail.

Plattformportabilität

Während die Standardbereitstellung auf Cloudflare Workers abzielt, sind die Tool-Handler und Kernbibliotheken plattformunabhängig. Eine Speicherabstraktion (IKeyValueStore-Schnittstelle + AppEnv-Typ) entkoppelt die Tool-Logik von Cloudflare-spezifischen APIs und ermöglicht selbst gehostete Bereitstellungen auf Node.js mit Redis, SQLite oder anderen Speicher-Backends. Einzelheiten finden Sie im Selbsthosting-Leitfaden.

Technologie-Stapel

• Laufzeit: Cloudflare Workes + Durable Objects

• MCP: agents SDK (McpAgent), @modlcontextprotocol/sdk

• Auth: @cloudflae/wokes-oaut-povide

• HTTP-outing: Hono

• Spache: TypeScip

• Vlidation: Zod

Entwicklung

npx wrangler dev       # Start local dev server
npx tsc --noEmit       # Type check
npx wrangler tail      # Stream live logs from deployed worker

Lizenz

Apache 2.0 – Uhebec 2026 Hall Boys, Inc.