Neo4j MCP Canary — Der Kanarienvogel geht zuerst, damit wir alle wissen, was kommt

Neo4j MCP Canary ist eine schnelllebige, experimentelle Version des Neo4j MCP-Servers für Kunden, die neue Funktionen erkunden möchten, bevor sie für den offiziellen Server in Betracht gezogen werden.

Basierend auf dem Quellcode des offiziellen Model Context Protocol (MCP)-Servers für Neo4j dient diese Variante der Erkundung potenzieller neuer Funktionen im Rahmen von Experimenten.

Da es sich um ein Labs-Projekt handelt, beachten Sie:

• Es wird nicht unterstützt.

• Es kann breaking changes zwischen eigenen Releases und gegenüber dem offiziellen Neo4j MCP-Server enthalten.

• Es sollte vor der Verwendung getestet werden.

Sie sind herzlich eingeladen, beizutragen – wir sind immer offen für neue Ideen, insbesondere in diesem Canary-Kanal.

Gehen Sie nicht davon aus, dass der Canary in Ihrer Umgebung funktioniert. Testen Sie zuerst.

Voraussetzungen

• Eine laufende Neo4j-Datenbankinstanz; Optionen umfassen Aura, Neo4j Desktop oder selbstverwaltet.

• APOC-Plugin in der Neo4j-Instanz installiert (erforderlich – get-schema verwendet apoc.meta.schema).

• Ein beliebiger MCP-kompatibler Client (z. B. VSCode mit MCP-Unterstützung).

⚠️ Bekanntes Problem: Neo4j 5.26.18 hat einen Fehler in APOC, der dazu führt, dass das get-schema-Tool fehlschlägt. Dies ist in 5.26.19 und höher behoben. Wenn Sie 5.26.18 verwenden, aktualisieren Sie bitte. Details finden Sie unter #136.

Related MCP server: FastMCP Production-Ready Server

Startprüfungen & adaptiver Betrieb

Der Server führt beim Start mehrere Pre-Flight-Prüfungen durch, um sicherzustellen, dass Ihre Umgebung korrekt konfiguriert ist.

STDIO-Modus – Pflichtanforderungen Im STDIO-Modus überprüft der Server Folgendes. Wenn eine Prüfung fehlschlägt (z. B. ungültige Konfiguration, falsche Anmeldedaten, fehlendes APOC), startet der Server nicht:

• Eine gültige Verbindung zu Ihrer Neo4j-Instanz.

• Die Fähigkeit, Abfragen auszuführen.

• Das Vorhandensein des APOC-Plugins.

HTTP-Modus – Verifizierung übersprungen Im HTTP-Modus werden die Startverifizierungsprüfungen übersprungen, da die Anmeldedaten aus den Authentifizierungs-Headern pro Anfrage stammen. Der Server startet sofort, ohne eine Verbindung zu Neo4j herzustellen. Die einzige Ausnahme ist der Query-API-Modus: Dessen Mindestversionsprüfung läuft beim Start in beiden Transportmodi, da sie nur einen nicht authentifizierten GET benötigt und nicht von anfragebezogenen Anmeldedaten abhängt.

Optionale Anforderungen Wenn eine optionale Abhängigkeit fehlt, startet der Server im adaptiven Modus. Wenn beispielsweise die Graph Data Science (GDS)-Bibliothek nicht erkannt wird, startet der Server trotzdem, deaktiviert aber automatisch GDS-abhängige Tools wie list-gds-procedures. Alle anderen Tools bleiben verfügbar.

Installation (Binärdatei)

Releases: https://github.com/neo4j-labs/neo4j-mcp-canary/releases

1. Laden Sie das Archiv für Ihr Betriebssystem/Ihre Architektur herunter.

2. Entpacken Sie es und legen Sie neo4j-mcp-canary in Ihren PATH.

Mac / Linux:

Auf dem Mac werden Sie möglicherweise beim ersten Ausführen der Binärdatei gewarnt. Wenn ja, genehmigen Sie sie über Systemeinstellungen → Datenschutz & Sicherheit.

chmod +x neo4j-mcp-canary
sudo mv neo4j-mcp-canary /usr/local/bin/

Windows (PowerShell / cmd):

move neo4j-mcp-canary.exe C:\Windows\System32

Überprüfen Sie die Installation:

neo4j-mcp-canary -v

Sollte die installierte Version ausgeben.

Aus dem Quellcode erstellen

Erfordert Go 1.25.3+ (siehe go.mod).

Erstellen Sie für Ihre aktuelle Plattform mit Task:

task build

Dies erzeugt bin/neo4j-mcp-canary. Ohne Task lautet das Äquivalent:

go build -C cmd/neo4j-mcp -o ../../bin/

Cross-Compilierung für macOS / Linux

Cross-Compilieren Sie, indem Sie GOOS/GOARCH setzen und cgo deaktivieren (die Codebasis ist reines Go, sodass CGO_ENABLED=0 eine vollständig statische Binärdatei ohne Laufzeitabhängigkeiten auf dem Zielrechner erzeugt):

CGO_ENABLED=0 GOOS=darwin  GOARCH=amd64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_darwin_amd64
CGO_ENABLED=0 GOOS=darwin  GOARCH=arm64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_darwin_arm64
CGO_ENABLED=0 GOOS=linux   GOARCH=amd64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_linux_amd64
CGO_ENABLED=0 GOOS=linux   GOARCH=arm64 go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary_linux_arm64

Um eine Version in die Binärdatei zu stempeln (-v / --version), übergeben Sie einen ldflags-Override – das macht die Release-Pipeline für getaggte Builds:

go build -C cmd/neo4j-mcp -o ../../dist/neo4j-mcp-canary \
  -ldflags "-X 'main.Version=$(git rev-parse --short HEAD)'"

Ohne diesen Wert wird Version standardmäßig auf "development" gesetzt, was auch die Telemetrie unabhängig von NEO4J_TELEMETRY deaktiviert (siehe Telemetrie).

Offizielle Multi-Plattform-Release-Archive (einschließlich Windows) werden von GoReleaser gemäß .goreleaser.yaml erstellt – siehe Installation (Binärdatei), um diese herunterzuladen, anstatt lokal zu bauen.

Transportmodi

Der Neo4j MCP Canary-Server unterstützt zwei Transportmodi:

• STDIO (Standard): Standard-MCP-Kommunikation über stdin/stdout für Desktop-Clients (Claude Desktop, VSCode).

• HTTP: RESTful-HTTP-Server mit Bearer-Token pro Anfrage oder Basic Authentication für webbasierte Clients und Multi-Tenant-Szenarien. Wenn der Standard-Authorization-Header nicht verwendet werden kann, kann ein benutzerdefinierter Headername konfiguriert werden.

Hauptunterschiede

Siehe Client-Setup-Anleitung für Konfigurationsanweisungen für beide Modi.

Nicht authentifizierte MCP-Client-Anfragen

Standardmäßig gibt es vier Anfragen, die ein MCP-Client ohne Authentifizierung senden kann, wenn der HTTP(S)-Transport verwendet wird. Einige Integrationen (AWS AgentCore, AWS Gateway usw.) verlassen sich darauf als anfänglichen Health-Check-Mechanismus:

• ping

• initialize

• tools/list

• notifications/initialize

Wenn Sie diese nicht benötigen, erzwingen Sie die Authentifizierung einzeln über die untenstehenden Variablen.

TLS/HTTPS-Konfiguration

Bei Verwendung des HTTP-Transports aktivieren Sie TLS für sichere Kommunikation über die untenstehenden Variablen.

Sicherheitskonfiguration

• Minimale TLS-Version: TLS 1.2 (TLS 1.3 wird ausgehandelt, wenn verfügbar)

• Cipher Suites: Go's sichere Standard-Cipher-Suites

• Standardport: Verwendet automatisch 443, wenn TLS aktiviert ist

Beispiel

export NEO4J_URI="bolt://localhost:7687"
export NEO4J_TRANSPORT_MODE="http"
export NEO4J_MCP_HTTP_TLS_ENABLED="true"
export NEO4J_MCP_HTTP_TLS_CERT_FILE="/path/to/cert.pem"
export NEO4J_MCP_HTTP_TLS_KEY_FILE="/path/to/key.pem"

neo4j-mcp-canary
# Server listens on https://127.0.0.1:443 by default

Produktionsnutzung: Verwenden Sie für Produktionsbereitstellungen Zertifikate von einer vertrauenswürdigen CA (Let's Encrypt, die CA Ihrer Organisation usw.).

Detaillierte Anweisungen zur Zertifikatserstellung, zum TLS-Testen und zur Produktionsbereitstellung finden Sie in CONTRIBUTING.md.

Konfigurationsoptionen

Der neo4j-mcp-canary-Server wird über Umgebungsvariablen, CLI-Flags und/oder eine optionale Konfigurationsdatei konfiguriert. CLI-Flags haben Vorrang vor Umgebungsvariablen, die wiederum Vorrang vor einer optionalen Konfigurationsdatei haben.

Umgebungsvariablen

Kernverbindung und -verhalten:

Verbindung über die Query API statt Bolt

Das Schema von NEO4J_URI bestimmt, welches Wire-Protokoll der Server für die Kommunikation mit Neo4j verwendet – kein separates Flag ist erforderlich:

• bolt://, bolt+s://, neo4j://, neo4j+s:// usw. → der Bolt-Treiber (Standard, unverändertes Verhalten).

• http:// oder https:// → die Neo4j Query API, die HTTP-basierte Abfrageschnittstelle von Neo4j. Nützlich für Bereitstellungen, die nur HTTP exponieren oder Bolt anderweitig nicht verwenden möchten.

Der Query-API-Modus erfordert Neo4j 2026.07 oder neuer (kalenderversionierte Releases) oder 5.27-aura oder neuer (nur klassisch versionierte Aura-Releases – eine reine klassische Version ohne -aura-Suffix wird nicht unterstützt). Diese Untergrenze liegt eine Version über der allgemeinen Verfügbarkeit der Query-API selbst (2026.06): Die Ablehnung von Schreibabfragen durch read-cypher hängt vom Feld queryType in der Abfrageantwort ab, das Neo4j erst in 2026.07 eingeführt hat – ein 2026.06-Server hat kein zuverlässiges Signal, um eine Abfrage vor der Ausführung als schreibgeschützt zu klassifizieren. Der Server prüft beim Start die gemeldete Version der verbundenen Instanz gegen diese Untergrenze (über einen nicht authentifizierten GET auf die Basis-URI) und weigert sich zu starten, wenn sie zu alt ist, mit einem Fehler, der die gefundene Version und die Mindestanforderung nennt.

NEO4J_USERNAME/NEO4J_PASSWORD und Anmeldedaten pro Anfrage (Basic/Bearer) funktionieren im Query-API-Modus genauso wie bei Bolt – siehe Transportmodi und Authentifizierungsmethoden (HTTP-Modus).

Schutzmechanismen für die Cypher-Ausführung (siehe Schutzmechanismen für die Cypher-Ausführung):

HTTP-Transport, TLS und Authentifizierung (siehe Tabellen oben).

CLI-Flags

Sie können jede Umgebungsvariable mithilfe von CLI-Flags überschreiben:

neo4j-mcp-canary \
  --neo4j-uri "bolt://localhost:7687" \
  --neo4j-username "neo4j" \
  --neo4j-password "password" \
  --neo4j-database "neo4j" \
  --neo4j-read-only false \
  --neo4j-telemetry true

Verfügbare Flags:

Verbindung & Verhalten

• --neo4j-uri – überschreibt NEO4J_URI

• --neo4j-username – überschreibt NEO4J_USERNAME

• --neo4j-password – überschreibt NEO4J_PASSWORD

• --neo4j-database – überschreibt NEO4J_DATABASE

• --neo4j-read-only – überschreibt NEO4J_READ_ONLY (true / false)

• --neo4j-telemetry – überschreibt NEO4J_TELEMETRY (true / false)

• --neo4j-schema-sample-size – überschreibt NEO4J_SCHEMA_SAMPLE_SIZE

• --neo4j-output-format – überschreibt NEO4J_OUTPUT_FORMAT (json / toon)

Schutzmechanismen für die Cypher-Ausführung

• --neo4j-cypher-max-rows – überschreibt NEO4J_CYPHER_MAX_ROWS (0 deaktiviert)

• --neo4j-cypher-max-bytes – überschreibt NEO4J_CYPHER_MAX_BYTES (0 deaktiviert)

• --neo4j-cypher-timeout – überschreibt NEO4J_CYPHER_TIMEOUT (Sekunden; 0 deaktiviert)

• --neo4j-cypher-max-estimated-rows – überschreibt NEO4J_CYPHER_MAX_ESTIMATED_ROWS (0 deaktiviert)

Transport / HTTP

• --neo4j-transport-mode – stdio oder http

• --neo4j-http-host – überschreibt NEO4J_MCP_HTTP_HOST

• --neo4j-http-port – überschreibt NEO4J_MCP_HTTP_PORT

• --neo4j-http-allowed-origins – überschreibt NEO4J_MCP_HTTP_ALLOWED_ORIGINS (durch Kommas getrennte CORS-Ursprünge)

• --neo4j-http-tls-enabled – überschreibt NEO4J_MCP_HTTP_TLS_ENABLED

• --neo4j-http-tls-cert-file – überschreibt NEO4J_MCP_HTTP_TLS_CERT_FILE

• --neo4j-http-tls-key-file – überschreibt NEO4J_MCP_HTTP_TLS_KEY_FILE

• --neo4j-http-auth-header-name – überschreibt NEO4J_HTTP_AUTH_HEADER_NAME

• --neo4j-http-allow-unauthenticated-ping – überschreibt NEO4J_HTTP_ALLOW_UNAUTHENTICATED_PING

• --neo4j-http-allow-unauthenticated-tools-list – überschreibt NEO4J_HTTP_ALLOW_UNAUTHENTICATED_TOOLS_LIST

• --neo4j-http-allow-unauthenticated-initialize – überschreibt NEO4J_HTTP_ALLOW_UNAUTHENTICATED_INITIALIZE

• --neo4j-http-allow-unauthenticated-notifications-initialize – überschreibt NEO4J_HTTP_ALLOW_UNAUTHENTICATED_NOTIFICATIONS_INITIALIZE

Führen Sie neo4j-mcp-canary --help aus, um die vollständige Liste mit Beschreibungen zu sehen.

Konfigurationsdatei

Als Alternative mit niedrigster Priorität zu Umgebungsvariablen kann neo4j-mcp-canary die Konfiguration aus einer optionalen JSON- oder YAML-Datei lesen:

neo4j-mcp-canary --config-file /etc/neo4j-mcp/config.yaml
# or
NEO4J_CONFIG_FILE=/etc/neo4j-mcp/config.yaml neo4j-mcp-canary

Schlüssel sind die kleingeschriebene Form der Umgebungsvariablen, der sie entsprechen:

neo4j_uri: bolt://localhost:7687
neo4j_username: neo4j
neo4j_password: password
neo4j_read_only: false
neo4j_transport_mode: http
neo4j_http_tls_enabled: true
neo4j_cypher_max_rows: 500

Das äquivalente JSON wird ebenfalls akzeptiert (.json-Erweiterung). Es werden nur skalare Werte (Zeichenketten, Zahlen, Booleans) unterstützt – ein verschachteltes Objekt oder eine Liste ist ein Startfehler. Werte aus CLI-Flags oder Umgebungsvariablen haben immer Vorrang vor der Konfigurationsdatei; eine --config-file, die nicht gelesen oder geparst werden kann, ist ein Startfehler.

Das Hinzufügen eines neuen Konfigurationsparameters zum Server (Umgebungsvariable + CLI-Flag + Konfigurationsdatei-Schlüssel, alles auf einmal) bedeutet, einen Eintrag zum fields-Slice in internal/config/schema.go hinzuzufügen – siehe die Doc-Kommentare dieser Datei für die Form.

Antwortformat (JSON vs. TOON)

Tool-Antworten (read-cypher, write-cypher, get-schema, list-gds-procedures) werden standardmäßig als JSON gerendert. Setzen Sie NEO4J_OUTPUT_FORMAT (oder --neo4j-output-format) auf toon, um sie stattdessen als TOON (Token-Oriented Object Notation) zu rendern – ein kompaktes, dennoch lesbares Format, das den LLM-Tokenverbrauch gegenüber JSON reduziert, insbesondere bei den tabellarischen Zeilenformen, die diese Tools zurückgeben:

neo4j-mcp-canary --neo4j-output-format toon
# or
NEO4J_OUTPUT_FORMAT=toon neo4j-mcp-canary

Ein read-cypher-Ergebnis als JSON:

{
  "rows": [
    { "name": "Alice", "age": 30 },
    { "name": "Bob", "age": 25 }
  ],
  "rowCount": 2,
  "truncated": false
}

Dasselbe Ergebnis als TOON:

rowCount: 2
rows[2]{age,name}:
  30,Alice
  25,Bob
truncated: false

Ein ungültiger Wert fällt mit einer Warnung auf stderr auf json zurück, genauso wie NEO4J_LOG_FORMAT.

Schutzmechanismen für die Cypher-Ausführung

read-cypher und write-cypher werden durch vier gestaffelte Schutzmechanismen geschützt, die zusammen verhindern, dass ein übereifriger LLM den MCP-Transport aufhängt oder die Datenbank erschöpft. Jede Ebene fängt eine andere Fehlerart ab; zusammen wirken sie als Verteidigung in der Tiefe.

Setzen Sie einen beliebigen Wert auf 0, um die jeweilige Ebene zu deaktivieren.

Abschneideumschlag

Wenn entweder das Zeilenlimit oder das Bytelimit greift, gibt das Tool die bereits gesammelten Zeilen plus einen Abschneideumschlag zurück:

{
  "rows": [ /* ... */ ],
  "rowCount": 1000,
  "truncated": true,
  "truncationReason": "rows",
  "maxRows": 1000,
  "hint": "Results were truncated at 1000 rows. Add a LIMIT clause or a more selective filter and retry for a complete result."
}

Aufrufer (einschließlich LLM-Agenten) können truncated / truncationReason / hint programmatisch lesen und es mit einer engeren Abfrage erneut versuchen, anstatt einen undurchsichtigen Transportfehler zu sehen.

Timeout- und Abbruchfehler

Wenn NEO4J_CYPHER_TIMEOUT greift, gibt das Tool einen klassifizierten Fehler zurück, der das konfigurierte Limit nennt und toolspezifische Abhilfe anbietet (begrenzen Sie Muster mit variabler Länge, fügen Sie WHERE-Filter hinzu oder LIMIT für read-cypher; reduzieren Sie die Batchgröße, grenzen Sie das MATCH ein oder verwenden Sie apoc.periodic.iterate für write-cypher). Ein Abbruch durch den Aufrufer (im Unterschied zum Timeout) erscheint als prägnante cancelled-Meldung ohne Abhilfehinweise.

Ablehnung aufgrund der Planerschätzung

Die Planerschätzungs-Sperre liest die EstimatedRows der Wurzel eines EXPLAIN-Plans, bevor die Abfrage ausgeführt wird. Da Neo4j LIMIT in die Wurzelschätzung einbezieht, besteht eine legitime MATCH ... LIMIT 100-Abfrage problemlos mit einer Schätzung von ~100, während ein nacktes MATCH auf einem Label mit mehreren Millionen Zeilen abgelehnt wird, bevor es startet.

Authentifizierungsmethoden (HTTP-Modus)

Bei Verwendung des HTTP-Transportmodus unterstützt der Neo4j MCP Canary-Server zwei Authentifizierungsmethoden, um verschiedene Bereitstellungsszenarien zu berücksichtigen.

Bearer-Token-Authentifizierung

Die Bearer-Token-Authentifizierung ermöglicht eine nahtlose Integration in Neo4j Enterprise Edition- und Neo4j Aura-Umgebungen, die SSO/OAuth/OIDC für das Identitätsmanagement verwenden. Diese Methode ist ideal für:

• Unternehmensbereitstellungen mit zentralisierten Identitätsanbietern (Okta, Azure AD usw.)

• Neo4j Aura-Datenbanken, die mit SSO konfiguriert sind

• Organisationen, die OAuth-2.0-Konformität benötigen

• Szenarien mit Multi-Faktor-Authentifizierung

Beispiel:

curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Das Bearer-Token wird von Ihrem Identitätsanbieter bezogen und zur Authentifizierung an Neo4j übergeben. Der MCP-Server fungiert als Durchgang, der das Token an das Authentifizierungssystem von Neo4j weiterleitet.

Basisauthentifizierung

Traditionelle Benutzername/Passwort-Authentifizierung, geeignet für:

• Neo4j Community Edition

• Entwicklungs- und Testumgebungen

• Direkte Datenbankanmeldedaten ohne SSO

Beispiel:

curl -X POST http://localhost:8080/mcp \
  -u neo4j:password \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Client-Konfiguration

Zum Konfigurieren von MCP-Clients (VSCode, Claude Desktop usw.) für die Verwendung des Neo4j MCP Canary-Servers siehe:

📘 Client-Setup-Anleitung – Vollständige Konfiguration für STDIO- und HTTP-Modi.

Tools & Verwendung

Bereitgestellte Tools:

Flag für den Schreibschutzmodus

Aktivieren Sie den Schreibschutzmodus, indem Sie NEO4J_READ_ONLY=true setzen (akzeptiert: true / false; Standard: false).

Sie können auch das CLI-Flag verwenden:

neo4j-mcp-canary \
  --neo4j-uri "bolt://localhost:7687" \
  --neo4j-username "neo4j" \
  --neo4j-password "password" \
  --neo4j-read-only true

Wenn aktiviert, werden Schreib-Tools (z. B. write-cypher) nicht für Clients bereitgestellt.

Abfrageklassifizierung

read-cypher stellt der Abfrage des Aufrufers EXPLAIN voran, um sie vor der Ausführung als Lese- oder Schreibabfrage zu klassifizieren. Konsequenzen:

• Schreiboperationen (CREATE, MERGE, DELETE, SET, REMOVE, ...) — abgelehnt mit einer Meldung, die den Aufrufer an write-cypher verweist.

• Schema-/DDL-Operationen (CREATE INDEX, DROP CONSTRAINT, ...) — abgelehnt, gleiche Meldung.

• Admin-Befehle (SHOW USERS, SHOW DATABASES, ...) — abgelehnt, gleiche Meldung.

• EXPLAIN-Präfix — abgelehnt mit einer eigenen Meldung, die darauf hinweist, dass der Schutz vor außer Kontrolle geratenen Abfragen bereits durch den Planner-Schätzungs-Guard und das Ausführungs-Timeout gewährleistet ist, und für einen profilierten Plan auf write-cypher verweist.

• PROFILE-Präfix — abgelehnt mit einer Meldung, die den Aufrufer an write-cypher verweist.

• Schreibgeschützte SHOW-Befehle (SHOW INDEXES, SHOW CONSTRAINTS, SHOW PROCEDURES, SHOW FUNCTIONS) — erlaubt.

Wenn die umschlossene Abfrage einen Syntaxfehler erzeugt, entfernt der Server das interne EXPLAIN -Präfix aus dem Fehlertext, der Spaltenposition und der Caret-Ausrichtung, bevor er die Antwort zurückgibt — sodass der Fehler so aussieht, als wäre die ursprüngliche Abfrage des Aufrufers direkt übermittelt worden.

Antwortformat für read-cypher / write-cypher

Treibertypen werden in camelCase-JSON-Strukturen verpackt, die den Cypher-Konventionen entsprechen:

• Knoten: { "elementId": "...", "labels": [...], "properties": {...} }

• Beziehungen: { "elementId": "...", "startElementId": "...", "endElementId": "...", "type": "...", "properties": {...} }

• Pfade: { "nodes": [...], "relationships": [...] }

• Punkte: { "x": ..., "y": ..., "srid": ... } (und z für 3D)

• Date / Time / DateTime / LocalTime / LocalDateTime / Duration: ISO-8601-Zeichenfolgen

Veraltete numerische Bezeichner id / startId / endId werden nicht ausgegeben — elementId / startElementId / endElementId sind die einzigen zurückgegebenen Bezeichner.

Feedback

give-feedback ermöglicht es einem Agenten, Freitext-Feedback über den MCP-Server selbst zu übermitteln — positiv oder negativ — als einzelnes feedback-String-Argument, begrenzt auf 300 Zeichen (durchgesetzt sowohl im beworbenen Tool-Schema als auch durch den Handler, falls ein Client das Schema vor dem Senden nicht validiert). Es ist für Feedback zu den Tools, dem Verhalten oder der Dokumentation des Servers gedacht, nicht für die Meldung von Cypher-/Datenbankfehlern.

Feedback wird als Mixpanel-Ereignis zusammen mit der übrigen Telemetrie des Servers gesendet, sodass es nur aufgezeichnet wird, wenn Telemetrie aktiviert ist (siehe Telemetrie) — der Tool-Aufruf selbst ist in jedem Fall erfolgreich.

Nutzungshinweise

Erkenntnisse aus Canary-Tests, die einem LLM (oder einem Menschen) helfen, das Beste aus read-cypher herauszuholen:

1. Aggregiere in der Datenbank. count, sum, avg, collect, reduce, percentileCont, stDev und ähnliche Reduktionen werden auf eine Zeile reduziert und sind von der Zeilenobergrenze nicht betroffen. Eine Abfrage wie UNWIND range(1, 50000) AS i RETURN sum(i) läuft sauber durch; dieselbe Reihe, zeilenweise gestreamt, wird an der Zeilenobergrenze abgeschnitten.

2. Verwende für explorative Abfragen immer LIMIT. Die Zeilenobergrenze schneidet bloße MATCH-Rückgaben ab; das hint-Feld des Trunkierungs-Envelopes weist den Aufrufer an, ein LIMIT hinzuzufügen. Ziehe ein selbst gewähltes LIMIT einem vom Server auferlegten vor.

3. Schränke die RETURN-Projektion bei breiten Knoten ein. Wenn ein Datensatz viele Eigenschaften enthält (z. B. einen vollständigen Company-Knoten mit 19 Feldern), greift die Byte-Obergrenze vor der Zeilenobergrenze. Gib nur die benötigten Felder zurück (RETURN c.name, c.companyNumber) statt des gesamten Knotens.

4. Verwende Parameter, einschließlich verschachtelter Maps. Parameter-Platzhalter ($name) werden aus dem params-Objekt gebunden; verschachtelter Zugriff funktioniert ($config.thresholds.pr). Fehlende erforderliche Parameter erzeugen einen klaren ParameterMissing-Fehler; zusätzliche Parameter werden stillschweigend ignoriert.

5. Sei bei Vergleichen explizit in Bezug auf Typen. Typübergreifende Vergleiche wie t.amount > "foo" ergeben null und filtern stillschweigend alles heraus — kein Fehler, nur eine leere Ergebnismenge. Validiere die eingehenden Parametertypen auf der Aufruferseite, wenn die Ergebnisform dich überrascht.

6. SHOW INDEXES / SHOW CONSTRAINTS sind erlaubt. Nützlich, bevor man eine Abfrage schreibt, die von einem Index abhängt, oder um zu debuggen, warum ein MATCH langsam ist.

7. EXPLAIN und PROFILE sind bei read-cypher nicht verfügbar. Der Schutz vor außer Kontrolle geratenen Abfragen wird bereits durch den Planner-Schätzungs-Guard und das Ausführungs-Timeout übernommen. Wenn du einen profilierten Plan mit Laufzeitstatistiken benötigst, verwende write-cypher mit PROFILE.

8. Achte auf doppelte Nutzlasten bei der Rückgabe von Pfaden. RETURN p, nodes(p), relationships(p) verdreifacht die serialisierte Nutzlast. Gib den Pfad oder seine Komponenten zurück, nicht beides.

9. Langlaufende Abfragen geben einen klassifizierten Fehler zurück. Wenn NEO4J_CYPHER_TIMEOUT greift, nennt der Fehler den Timeout-Wert und schlägt Abhilfemaßnahmen vor (begrenzte Muster mit variabler Länge, WHERE-Filter hinzufügen, LIMIT verwenden) statt eines rohen context deadline exceeded vom Treiber.

10. OPTIONAL MATCH für fehlende Daten. Wenn du per ID nachschlägst und einige IDs möglicherweise nicht existieren, gibt OPTIONAL MATCH für Fehltreffer null zurück, anstatt Zeilen zu verwerfen — besser für Batch-Nachschlagevorgänge.

11. Die Standardwerte sind kalibriert, nicht willkürlich. 1000 Zeilen / ~900 KB / 30s / 1M Planner-Schätzung decken die überwältigende Mehrheit explorativer und Produktionsabfragen ab. Erhöhe sie für Bulk-Export-Workloads; reduziere sie bei stark frequentierten Agent-Bereitstellungen.

Beispiel-Prompts in natürlicher Sprache

Prompts, die du in Copilot oder einem anderen MCP-Client ausprobieren kannst:

• „Was enthält meine Neo4j-Instanz? Liste alle Knoten-Labels, Beziehungstypen und Property-Keys auf."

• „Finde alle Person-Knoten und zeige ihre wichtigsten Beziehungen, begrenzt auf 50 Ergebnisse."

• „Welche Indizes und Constraints existieren in meiner Datenbank?"

• „Fasse den Transaktionsgraphen zusammen: Gesamtzahl, Durchschnittsbetrag und die Top-5-Kunden nach PageRank."

Sicherheitstipps

• Verwende für die Erkundung einen eingeschränkten Neo4j-Benutzer.

• Überprüfe LLM-generiertes Cypher, bevor du es in Produktionsdatenbanken ausführst.

• Behalte NEO4J_READ_ONLY=true für jede Bereitstellung bei, die den Graphen nicht verändern soll.

• Lasse die Cypher-Schutzmechanismen auf ihren Standardwerten, es sei denn, du hast einen konkreten Grund, sie zu ändern.

Protokollierung

Der Server verwendet strukturierte Protokollierung mit Unterstützung für mehrere Protokollebenen und Ausgabeformate.

Konfiguration

Protokollebene (NEO4J_LOG_LEVEL, Standard: info)

Steuert die Ausführlichkeit. Unterstützt alle MCP-Protokollebenen: debug, info, notice, warning, error, critical, alert, emergency.

Protokollformat (NEO4J_LOG_FORMAT, Standard: text)

• text — menschenlesbar (Standard)

• json — strukturiertes JSON (nützlich für die Protokollaggregation)

Telemetrie

Standardmäßig erfasst neo4j-mcp-canary anonyme Nutzungsdaten, um das Produkt zu verbessern. Dazu gehören Informationen wie die verwendeten Tools, das Betriebssystem und die CPU-Architektur. Es werden keine persönlichen oder sensiblen Informationen erfasst.

Um die Telemetrie zu deaktivieren, setze NEO4J_TELEMETRY=false (akzeptiert: true / false; Standard: true). Du kannst auch das CLI-Flag --neo4j-telemetry verwenden.

Dokumentation

📘 Client-Setup-Anleitung – Konfiguriere VSCode, Claude Desktop und andere MCP-Clients (STDIO- und HTTP-Modi) 📚 Beitragsleitfaden – Beitrags-Workflow, Entwicklungsumgebung, Mocks & Tests

Probleme / Feedback: Eröffne ein GitHub-Issue mit Reproduktionsdetails (vertrauliche Daten weglassen).