Synapse

Ein berechtigungsbewusster MCP-Server für Frappe und ERPNext. Er ermöglicht einem LLM-Client, Daten einer Site als echter Benutzer, unter den eigenen Berechtigungen dieses Benutzers, über OAuth zu lesen und zu schreiben, wobei jeder Aufruf in einem Audit-Log protokolliert wird.

POST https://<your-site>/api/method/synapse.mcp.handle_mcp

Warum noch einer?

Die meisten Frappe-MCP-Server laufen mit erweiterten Rechten und geben dem Modell rohes SQL oder ignore_permissions-Dokumentzugriff. Das ist für eine persönliche Sandbox in Ordnung, aber auf einem Geschäftssystem inakzeptabel. Synapse vertritt die gegenteilige Position:

• Kein ignore_permissions, nirgendwo. Jedes Tool läuft als der aufrufende Benutzer. DocType-Berechtigungen, Benutzerberechtigungen, Freigaberegeln und Submit-/Cancel-Rechte gelten alle, und Schreibvorgänge laufen über Document.insert/save/submit/cancel, sodass Validierungen, Hooks und Workflows genau wie im Desk ausgelöst werden.

• Eine zweite Grenze oberhalb der Berechtigungen, denn „dieser Benutzer darf im Desk Sales Invoices bearbeiten“ und „ein Agent, der das Token dieses Benutzers besitzt, darf Sales Invoices bearbeiten“ sind unterschiedliche Entscheidungen.

• Alles wird protokolliert, einschließlich Aufrufen, die abgelehnt werden, bevor sie ein Tool erreichen.

• Keine Abhängigkeiten. Der MCP-Server ist gebündelt (vendored), sodass bench install-app die gesamte Installation ist und bench update sicher bleibt.

Related MCP server: Frappe Assistant Core

Installation

bench get-app https://github.com/erpuae/synapse
bench --site <your-site> install-app synapse

Dann prüfen Sie jederzeit, wo die Site steht:

bench --site <your-site> execute synapse.mcp_tools.check.report

Es gibt aus, was konfiguriert ist und was fehlt, in der Reihenfolge, in der es behoben werden muss. Eine frische Installation ist vollständig geschlossen: Nichts ist erreichbar, bis Sie es festlegen.

Werkzeuge

Daten werden im in den MCP-Einstellungen festgelegten Format zurückgegeben, standardmäßig ISO. Schreibvorgänge akzeptieren ISO oder DD-MM-YYYY, sodass ein Lese-Ändern-Schreib-Zyklus Tag und Monat nicht vertauschen kann.

Bewusst nicht bereitgestellt: frappe.db.set_value (überspringt Validierung und Hooks – das set_value-Tool lädt und speichert stattdessen das Dokument), beliebige Whitelisted-Methodenausführung, Umbenennen und Ändern (amend).

Vier Tore

Jeder Aufruf durchläuft alle vier. Sie sind unabhängig, und die engste gewinnt.

1. Authentifizierung. Der Endpunkt ist für Gäste geschlossen, sodass ein nicht authentifizierter POST vom Framework abgelehnt wird, bevor irgendein Tool-Code läuft.

2. Eine Rolle auf dem Tool. Dokument-Tools benötigen MCP Agent, das SQL-Tool benötigt MCP SQL Reader. Ohne die Rolle wird das Tool nicht einmal aufgelistet.

3. Die MCP-Zugriffsliste (MCP-Einstellungen), eine Allowlist oder eine Denylist. Für alles außer einem Lesevorgang muss der Aufrufer außerdem eine Rolle besitzen, der die Site diese Aktion gewährt hat.

4. Frappes eigene Berechtigungen, wie oben beschrieben.

Administrator ist nicht ausgenommen. Er besitzt jede Rolle, sodass die Rollenprüfung der Tore 2 und 3 besteht, aber die DocType-Liste bindet weiterhin.

Zugriffsmodus

Allowlist – nichts ist erreichbar außer den aufgelisteten DocTypes, jeweils mit den angehakten Aktionen. Schließt standardmäßig ab; ein neuer DocType bleibt unerreichbar, bis jemand etwas anderes festlegt. Dies ist die Standardeinstellung, und eine frische Installation hat eine leere Liste, sodass überhaupt nichts erreichbar ist.

Denylist – jeder DocType ist erreichbar außer den aufgelisteten. Die eigenen Frappe-Berechtigungen des Benutzers werden zur Arbeitsgrenze, und die Liste grenzt aus, was kein Agent berühren sollte, egal was sein Benutzer tun darf. Jede Zeile blockiert standardmäßig alles; deaktivieren Sie Block Read, um einen DocType lesbar, aber unveränderbar zu lassen.

Die Denylist ist auf einem vollständigen ERP einfacher zu handhaben. Ihr Preis ist, dass ein neuer DocType erreichbar ankommt, daher werden in diesem Modus zwei Mengen erzwungen, unabhängig davon, ob jemand sie auflistet:

• Nie erreichbar: OAuth Bearer Token, OAuth Authorization Code, OAuth Client, Token Cache, Social Login Key, Connected App, Webhook, Email Account, Integration Request, User Social Login, Access Log. Das Lesen dieser ist der Weg, wie ein Leser zum Schreiber wird.

• Nur lesen, immer: DocType, DocField, DocPerm, Custom DocPerm, Custom Field, Property Setter, Server Script, Client Script, Print Format, Report, Role, Has Role, User, User Permission, System Settings, Workflow, Scheduled Job Type. Ein Agent, der Custom DocPerm bearbeiten kann, kann sich selbst alles gewähren.

Im Allowlist-Modus gilt keine der beiden Mengen – dort ist die Tabelle die einzige Autorität.

Kindtabellen sind nie direkt erreichbar; sie werden über ihre Eltern gelesen und geschrieben. Die Übereinstimmung ist case-insensitiv, und der DocType-Name wird vor der Konsultation der Liste gegen die Site kanonisiert, sodass salary slip nicht an einer Zeile mit Salary Slip vorbeikommen kann.

Um eine große Allowlist zu füllen, ohne Hunderte von Grid-Zeilen anzukreuzen:

bench --site <your-site> execute synapse.mcp_tools.allowlist.grant_all --kwargs "{'dry_run': 1}"
bench --site <your-site> execute synapse.mcp_tools.allowlist.grant_all
bench --site <your-site> execute synapse.mcp_tools.allowlist.show

grant_all ist standardmäßig nur lesend und wendet dieselben zwei geschützten Mengen an. Wenn Sie alles erreichbar machen möchten, sagt der Denylist-Modus mit einer leeren Liste das ehrlicher als 700 Allowlist-Zeilen.

Einrichtung

1. OAuth. Frappe 16 veröffentlicht OAuth-Server-Metadaten und unterstützt dynamische Client-Registrierung, wodurch sich ein MCP-Client verbinden kann, ohne dass ein OAuth-Client-Datensatz von Hand erstellt werden muss. Es ist standardmäßig deaktiviert. Aktivieren Sie in OAuth-Einstellungen Show Auth Server Metadata, Show Protected Resource Metadata und Enable Dynamic Client Registration. Synapse ändert diese nie – sie betreffen das OAuth-Verhalten der gesamten Site, nicht nur MCP.

Seien Sie sich klar darüber, was ein Token gewährt: Ein Frappe-OAuth-Token ist nicht auf MCP beschränkt. Es autorisiert die gesamte /api-Oberfläche als dieser Benutzer.

2. Weisen Sie MCP Agent dem Benutzer zu, als den der Agent handeln soll. Wer sich authentifiziert, ist die Identität, unter der jedes Tool läuft. Beschränken Sie diesen Benutzer also auf das, was der Agent sehen soll, anstatt einen Administrator zu verwenden.

3. Füllen Sie die MCP-Einstellungen aus. Aktivieren Sie Enable MCP Endpoint, wählen Sie Access Mode und füllen Sie die angezeigte Liste aus. Lesevorgänge funktionieren ab diesem Punkt. Für Schreibvorgänge aktivieren Sie außerdem Enable Write Tools und gewähren Sie die Aktionen bestimmten Rollen in Role Permissions; wenn diese Tabelle leer ist, bleibt der Endpunkt schreibgeschützt, egal was sonst eingestellt ist.

Verbinden eines Clients

claude mcp add --transport http mysite https://<your-site>/api/method/synapse.mcp.handle_mcp

Dann authentifizieren Sie sich – ein Browser öffnet sich auf dem Login der Site. Jeder MCP-Client, der Streamable HTTP mit OAuth spricht, funktioniert auf die gleiche Weise; in Claude Desktop ist es Einstellungen → Connectors → Add custom connector mit derselben URL.

Rohes SQL – lesen Sie dies, bevor Sie es aktivieren

run_sql_query umgeht das Berechtigungssystem von Frappe vollständig. Ein Benutzer mit MCP SQL Reader kann jede Tabelle auf der Site lesen, unabhängig von seinen DocType-Berechtigungen. Gewähren Sie es nur Benutzern, die bereits vollen Datenbankzugriff haben.

Es ist deaktiviert, bis Enable Read-Only SQL Tool aktiviert ist, und es verwendet die DocType-Zugriffsliste nicht – es kann nicht, da es nie einen DocType benennt. Bevorzugen Sie get_list und get_doc; greifen Sie nur für einen Join oder ein Aggregat, das sie nicht ausdrücken können, auf SQL zurück. Wenn ein Agent ständig nach SQL greift, fehlt den Dokument-Tools etwas, das er benötigt.

Zwei Ebenen stehen dahinter:

1. Ein schreibgeschützter Datenbankbenutzer, erzwungen durch MariaDB, sodass eine Abfrage, die den Textfilter passiert, trotzdem nicht schreiben kann.

2. mcp_tools/guard.py – Anweisungstyp, keine Kommentare, keine gestapelten Anweisungen, eine Keyword-Blocklist, eine Tabellen-Blocklist und eine Längenbegrenzung. Textabgleich, also behandeln Sie es als Gürtel und nicht als Hosenträger.

Richten Sie Ebene 1 pro Site ein. Als MariaDB-Root:

CREATE USER 'mcp_ro'@'localhost' IDENTIFIED BY '<STRONG_PASSWORD>';
GRANT SELECT ON `<DB_NAME>`.* TO 'mcp_ro'@'localhost';
REVOKE FILE ON *.* FROM 'mcp_ro'@'localhost';
FLUSH PRIVILEGES;

Dann in site_config.json (niemals im Repo):

{
  "mcp_ro_db_user": "mcp_ro",
  "mcp_ro_db_password": "<STRONG_PASSWORD>"
}

Ohne diese Schlüssel fällt das Tool auf die eigene Lese-Schreib-Verbindung der Site zurück und führt nach jeder Abfrage einen Rollback durch. Es funktioniert, aber der Guard wird zur einzigen Grenze. Auf gehosteten Plattformen, auf denen ein zweiter Datenbankbenutzer nicht möglich ist, ist dieser Fallback die einzige Option – entscheiden Sie bewusst, bevor Sie dort SQL aktivieren.

Erweitern Sie die Tabellen-Blocklist pro Site mit mcp_sql_blocked_tables in site_config.json. Nur MariaDB; connection.py wirft NotImplementedError auf anderen Backends.

Audit

Jeder Aufruf schreibt eine MCP Access Log-Zeile – Erfolg, Ablehnung oder Fehler – mit dem Tool, Benutzer, Authentifizierungsmethode, IP, berührtem Dokument, Zeilenzahlen und Zeitmessung. Schreibvorgänge protokollieren auch die übermittelten Werte und das Vorher/Nachher jedes geänderten Feldes. Aufrufe, die vor der Ausführung des Tool-Bodys abgelehnt werden (unbekanntes Tool, fehlende Rolle, nicht passende Argumente), werden ebenfalls protokolliert: Ein Agent, der Tools sondiert, auf die er keine Rechte hat, ist genau das, wofür ein Audit-Trail gedacht ist.

Ein Aufruf, der vollständig im Log fehlt, hat den Server nie erreicht. Wenn ein Tool blockiert erscheint und das Log nichts dafür enthält, liegt die Blockade im Client, meist in dessen eigener Tool-Berechtigungsabfrage. Das ist das Erste, was zu prüfen ist.

Zeilen werden mit einem eigenen Commit nach jedem Rollback geschrieben, sodass ein fehlgeschlagener oder abgelehnter Schreibvorgang dennoch seinen Datensatz hinterlässt. Vom System Manager lesbar und berichtbar, aber nicht vom Desk aus erstellbar oder bearbeitbar. reference_doctype und reference_name sind absichtlich Data- statt Link-Felder – eine Audit-Zeile darf das Löschen dessen, was sie aufzeichnet, niemals blockieren. Ein täglicher Job verwirft Zeilen, die das Aufbewahrungsfenster überschreiten. Deaktivieren Sie Log Field Values, wenn die Daten selbst nicht in das Log dupliziert werden sollen; passwortähnliche Felder werden in jedem Fall maskiert.

Tests

bench --site <your-site> run-tests --app synapse

Die Zugriffsliste, der SQL-Guard, die Tool-Schemas und die Wertkonvertierung importieren nichts von frappe, sodass sie auch ohne eine Site laufen:

python -m unittest discover -s apps/synapse -p 'test_mcp_*.py'

Lizenz

GNU Affero General Public License v3.0 oder später. Siehe LICENSE.

AGPL ist beabsichtigt: Wenn Sie eine modifizierte Synapse als Netzwerkdienst betreiben, haben die Benutzer Anspruch auf Ihre Änderungen.