CityJSON MCP

Ein lokaler Model Context Protocol (MCP)-Server, um tatsächlich mit CityJSON zu arbeiten, statt nur die Spezifikation zu lesen.

Er bietet MCP-Clients wie Claude Desktop, Cursor und VS Code eine stabile, auf CityJSON ausgerichtete Tool-API, die auf Folgendem basiert:

• cjio — CityJSON-Manipulation, Filterung, CRS-Operationen, Bereinigung, Zusammenführen und Export.

• cjval — offizielle CityJSON/CityJSONSeq-Syntax-, Schema- und Strukturvalidierung.

• val3dity — 3D-geometrische Gültigkeitsprüfung für CityJSON-Primitive.

• citygml-tools — CityGML ↔ CityJSON-Konvertierung.

• cjdb + PostgreSQL/PostGIS — persistente CityJSON-Speicherung/Import/Export.

• CityJSON 2.0.2-Spezifikation, JSON-Schemas und Extensions-Registry — Live-Kanonische Referenzzugriff für den Agenten.

Der Server stellt 38 MCP-Tools bereit. Transformationen verwenden unveränderliche Datensatz-Handles: Eine Operation wie cityjson_subset gibt eine neue dataset_id zurück und überschreibt den Quelldatensatz nicht. Ein optionaler Ein-Seiten-Chat-Host streamt Browser-Anhänge in den MCP-Eingangsinbox und sendet nur Datensatz-Handles an das konfigurierte Modell.

Status: Dies ist eine praktische v0.1-Implementierung. Das empfohlene Docker-Image bündelt alle externen Backends; Entwicklung ohne Docker erfordert weiterhin die Installation der einzelnen Befehle.

Architektur

flowchart LR
  CLIENT["MCP clients<br/>Claude Desktop · Cursor · VS Code"]
  BROWSER["One-page chat<br/>browser + attachments"]
  CHAT["Chat host<br/>model API + MCP client"]
  MODEL["Tool-capable model<br/>Anthropic · OpenAI"]
  INPUT["Input inbox<br/>streamed CityJSON files"]
  SERVER["Docker container<br/>CityJSON MCP · stdio server"]
  CORE["Dataset manager<br/>immutable handles + path policy"]
  NATIVE["Native inspection/query<br/>JSON + CityObjects + bbox"]
  CJIO["cjio<br/>transform · subset · export"]
  CJVAL["cjval<br/>schema + structural validation"]
  VAL3["val3dity<br/>3D geometry validation"]
  CGML["citygml-tools<br/>CityGML ↔ CityJSON"]
  CJDB["cjdb + PostGIS<br/>persistence"]
  KNOW["CityJSON 2.0.2 references<br/>spec + schemas + extensions"]

  CLIENT -->|MCP stdio| SERVER
  BROWSER --> CHAT
  BROWSER -->|file stream| INPUT
  CHAT --> MODEL
  CHAT -->|MCP stdio| SERVER
  INPUT --> CORE
  SERVER --> CORE
  CORE --> NATIVE
  CORE --> CJIO
  CORE --> CJVAL
  CORE --> VAL3
  CORE --> CGML
  CORE --> CJDB
  SERVER --> KNOW

PNG herunterladen – hohe Auflösung

Die MCP-orientierte API setzt bewusst keine beliebigen Shell-Befehle wie run_cjio("...") aus. Jedes MCP-Tool hat ein typisiertes Eingabeschema. Befehle werden mit spawn(..., { shell: false }) aufgerufen, was den agentenorientierten Vertrag stabil hält und Shell-String-Interpolation vermeidet.

Typischer Agenten-Workflow

flowchart TD
  START["User asks about a CityJSON file"]
  IMPORT["cityjson_import<br/>returns dataset_id"]
  INSPECT["Inspect/query<br/>info · list_objects · get_object · query"]
  VALIDATE["Validate<br/>cjval + val3dity"]
  TRANSFORM["Transform<br/>subset · LoD · CRS · clean · triangulate · merge"]
  DERIVED["New immutable dataset_id"]
  OUTPUT["Output<br/>save · export · CityGML · cjdb"]
  KNOW["Need semantics?<br/>spec · schema · extensions"]

  START --> IMPORT
  IMPORT --> INSPECT
  IMPORT --> VALIDATE
  IMPORT --> TRANSFORM
  TRANSFORM --> DERIVED
  DERIVED --> VALIDATE
  DERIVED --> OUTPUT
  INSPECT --> OUTPUT
  VALIDATE --> OUTPUT
  INSPECT --> KNOW
  VALIDATE --> KNOW

PNG herunterladen – hohe Auflösung

Ein Benutzer kann zum Beispiel sagen:

Importiere rotterdam.city.json, validiere sowohl seine CityJSON-Struktur als auch die 3D-Geometrie, behalte nur Gebäude innerhalb der Bounding-Box [90000, 435000, 91000, 436000], projiziere das Ergebnis auf EPSG:28992 um, bereinige doppelte und verwaiste Vertices, validiere das Ergebnis erneut und gib es mit cityjson_download zurück.

Ein MCP-Client kann diese Anfrage ungefähr wie folgt auflösen:

1. cityjson_import

2. cityjson_validate

3. cityjson_subset

4. cityjson_reproject

5. cityjson_clean_vertices

6. cityjson_validate

7. cityjson_save

Jede Transformation gibt eine neue dataset_id zurück, sodass Zwischenzustände während des Gesprächs verfügbar bleiben.

Schnellstart

DATUM Ein-Seiten-Chat mit direkten Anhängen

Die enthaltene DATUM-Chat-Anwendung ist der einfachste Anhang-Workflow. Sie streamt jeden Browser-Anhang an CITYJSON_MCP_INPUT, importiert ihn über den Live-MCP-Server und gibt dem Modell nur die resultierende dataset_id und eine Zusammenfassung.

Sie können optional ein Standardmodell in einer lokalen Umgebungsdatei vorkonfigurieren:

cp .env.example .env

Wählen Sie den API-Stil und setzen Sie dann eine tool-fähige Modell-ID, ihren Schlüssel und ihre Basis-URL. Zum Beispiel verwendet DeepSeek den OpenAI-kompatiblen Stil:

MODEL_PROVIDER=openai
MODEL_NAME=deepseek-v4-pro
MODEL_API_KEY=your-api-key
MODEL_BASE_URL=https://api.deepseek.com

Diese Datei ist optional: Modell, Anbieter, API-Schlüssel und Basis-URL können auch im Dialog Modell konfigurieren der Anwendung eingegeben werden. Dialog-Anmeldedaten werden nur im Serverspeicher für die Browser-Sitzung gehalten und niemals an den Browser zurückgegeben oder an ein MCP-Tool übergeben.

MODEL_PROVIDER akzeptiert anthropic oder openai, da es das API-Protokoll auswählt, nicht das Unternehmen, das das Modell bereitstellt. anthropic verwendet Messages; openai verwendet OpenAI-kompatible Chat Completions und unterstützt daher auch kompatible Dienste wie DeepSeek über MODEL_BASE_URL.

Führen Sie die vollständige Anwendung aus. Dies ist die Standardeinstellung, da das Image cjio, cjval, val3dity, citygml-tools und cjdb enthält:

npm install
npm run chat

Öffnen Sie dann http://127.0.0.1:3000. Das Anhängen einer Datei führt diese Sequenz automatisch aus:

browser multipart stream → input inbox → cityjson_import → dataset_id → model tool loop

npm run chat entspricht:

docker compose -f docker/docker-compose.chat.yml up --build

Die Compose-Konfiguration bindet die Anwendung nur an 127.0.0.1 und hält Eingabe-/Arbeitsbereichsdaten in Docker-Volumes. Sie liest ein optionales Standardmodell aus .env; andernfalls öffnet die Anwendung den Modellkonfigurationsdialog.

Für die Entwicklung auf einem Host, auf dem alle fünf ausführbaren Dateien bereits installiert sind, verwenden Sie npm run chat:host. Der Host-Modus führt eine Backend-Bereitschaftsprüfung durch und weigert sich, eine nicht funktionsfähige Toolbox zu bewerben. CHAT_ALLOW_PARTIAL_BACKENDS=true überschreibt diese Prüfung nur für bewusste reine Inspektionsentwicklung.

Eigenständige MCP-Clients mit der vollständigen Docker-Laufzeit

Das Docker-Image enthält den MCP-Server und alle fünf Backends. Installieren Sie Docker Desktop und ziehen Sie dann das Image von Docker Hub:

docker pull yarroudh/cityjson-mcp:latest

Bestätigen Sie, dass jedes Backend vorhanden ist:

docker run --rm --entrypoint node yarroudh/cityjson-mcp:latest /app/scripts/doctor.mjs

Die Ausgabe sollte OK für cjio, cjval, val3dity, citygml-tools und cjdb melden.

Eingabe-Inbox konfigurieren

MCP selbst überträgt keine gewöhnlichen Chat-Anhänge. Für Claude Desktop und andere eigenständige Clients mounten Sie einmal ein Host-Verzeichnis. Ersetzen Sie /absolute/path/to/cityjson-files durch ein echtes absolutes Verzeichnis:

{
  "mcpServers": {
    "cityjson": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--mount",
        "type=bind,source=/absolute/path/to/cityjson-files,target=/input,readonly",
        "--env",
        "CITYJSON_MCP_ALLOWED_ROOTS=/input:/data",
        "--env",
        "CITYJSON_MCP_INPUT=/input",
        "yarroudh/cityjson-mcp:latest"
      ]
    }
  }
}

Das Host-Verzeichnis erscheint als /input in Docker. Benutzer und Agenten beziehen sich nur auf den Dateinamen:

Importiere model.city.json und fasse es zusammen.

Der Agent ruft cityjson_import({"filename":"model.city.json"}) auf. cityjson_list_imports kann verfügbare Dateinamen ermitteln, und cityjson_import kopiert die ausgewählte Quelle in den unveränderlichen verwalteten Arbeitsbereich. Der Eingabe-Mount kann nicht geändert werden.

Chat-Anhangspfade wie /mnt/user-data/... und /home/claude/... gehören zur privaten Umgebung des Clients. Sie existieren nicht im MCP-Container. cityjson_import_text bleibt nur für kleine programmatisch bereitgestellte JSON-Texte verfügbar; cityjson_upload ist sein veraltetes Kompatibilitäts-Alias und kein echter Datei-Upload-Kanal.

Das Image enthält cjio, cjval, val3dity, citygml-tools und cjdb; es sind keine Host-Python-, Rust-, Java- oder Geodaten-Bibliotheken erforderlich. Docker zieht automatisch neuere Image-Ebenen, wenn nötig, nachdem Sie docker pull yarroudh/cityjson-mcp:latest erneut ausgeführt haben.

Um aus dem Quellcode zu bauen, cachen Sie die beiden langsamen Compiler-Stufen, bevor Sie das restliche Image bauen:

npm install
npm run docker:cache:val3dity
npm run docker:cache:cjval
npm run docker:build
npm run docker:doctor

Wenn eine spätere Ebene fehlschlägt, verwendet das erneute Ausführen des letzten Befehls die abgeschlossenen val3dity- und cjval-Ebenen erneut, anstatt sie von Grund auf zu kompilieren.

Optional: Ohne Docker ausführen

Die folgenden Abschnitte werden nur benötigt, wenn Sie node src/index.mjs direkt ausführen, anstatt das vollständige Docker-Image zu verwenden.

1. Anforderungen

Der MCP-Server selbst benötigt:

• Node.js 20+

• npm

Installieren Sie seine JavaScript-Abhängigkeiten:

cd cityjson-mcp
npm install

Überprüfen Sie dann den Quellcode und die nativen Tests:

npm run check
npm test

Überprüfen Sie, welche externen Backends verfügbar sind:

npm run doctor

Der MCP kann auch starten, wenn einige Backends fehlen. Nur Tools, die von einem fehlenden Backend abhängen, schlagen fehl. Der Agent kann auch selbst cityjson_backend_status aufrufen.

2. Installieren Sie die benötigten Backends

cjio

Offizielles Projekt: https://github.com/cityjson/cjio

python -m pip install 'cjio[export,reproject,validate]'

Die Extras sind nützlich, da Reprojektion, Triangulierung/Export und verwandte Operationen optionale Python-Pakete benötigen.

cjval

Offizielles Projekt: https://github.com/cityjson/cjval

Installieren Sie Rust, dann:

cargo install cjval --features build-binary

val3dity

Offizielles Projekt: https://github.com/tudelft3d/val3dity

Auf macOS bietet das Upstream-Projekt eine Homebrew-Formel:

brew tap tudelft3d/software
brew install val3dity

Unter Windows verwenden Sie die ausführbare Datei der Upstream-Version. Unter Linux folgen Sie den Upstream-Bauanweisungen für CMake/CGAL/Eigen/GEOS. val3dity validiert derzeit CityJSON/CityJSONSeq direkt; aktuelle Versionen parsen kein CityGML mehr, verwenden Sie also zuerst citygml_to_cityjson, wenn Ihre Quelle CityGML ist.

citygml-tools

Offizielles Projekt: https://github.com/citygml4j/citygml-tools

Aktuelle Versionen erfordern Java 17+. Laden Sie die Distribution herunter und entpacken Sie sie, stellen Sie dann sicher, dass der citygml-tools-Launcher im PATH ist, oder zeigen Sie mit CITYGML_TOOLS_BIN auf den Launcher. Die aktuelle stabile Version zum Zeitpunkt der Erstellung dieser README ist 2.5.0.

cjdb

Offizielles Projekt: https://github.com/cityjson/cjdb

python -m pip install cjdb

cjdb erfordert PostgreSQL mit PostGIS. Eine Entwicklungs-Compose-Datei ist unter docker/docker-compose.postgis.yml enthalten.

3. Autorisieren Sie die Ordner, auf die der MCP zugreifen darf

Der Server lehnt Dateipfade außerhalb explizit autorisierter Wurzeln ab.

macOS/Linux-Beispiel:

export CITYJSON_MCP_ALLOWED_ROOTS="/Users/me/citydata:/Volumes/3d-city-models"
export CITYJSON_MCP_INPUT="/Users/me/citydata/input"
export CITYJSON_MCP_WORKSPACE="/Users/me/citydata/.cityjson-mcp-workspace"

Windows verwendet Semikolons zwischen Wurzeln:

C:\citydata;D:\city-models

Der Arbeitsbereich speichert abgeleitete CityJSON-Datensätze, Validator-Berichte und zwischenzeitliche CityJSONSeq-Dateien. Er wird automatisch erstellt.

Optionale Überschreibungen für ausführbare Dateien:

export CJIO_BIN=/custom/path/cjio
export CJVAL_BIN=/custom/path/cjval
export VAL3DITY_BIN=/custom/path/val3dity
export CITYGML_TOOLS_BIN=/custom/path/citygml-tools
export CJDB_BIN=/custom/path/cjdb

Für cjdb setzen Sie das PostgreSQL-Passwort in der Prozessumgebung, anstatt es in MCP-Argumente zu setzen:

export PGPASSWORD='...'

4. Testen Sie den Server manuell

stdio-MCP-Server scheinen normalerweise „nichts zu tun“, wenn sie direkt gestartet werden, da sie auf MCP-JSON-RPC-Nachrichten auf stdin warten. Sie können den Start trotzdem bestätigen mit:

npm run doctor
npm test

Konfigurieren Sie dann einen der unten genannten MCP-Clients. Die mitgelieferten Vorlagen starten das vollständige Docker-Image. Mitwirkende können den Docker-Befehl durch einen absoluten Pfad zu node src/index.mjs ersetzen und die obigen Umgebungsvariablen setzen.

Hinzufügen zu Claude Desktop

Lokale MCP-Konfigurationen von Claude Desktop verwenden ein mcpServers-Objekt. Die mitgelieferte Vorlage startet das veröffentlichte Image ohne Host-Mount. Fügen Sie den im Schnellstart gezeigten Mount hinzu, wenn Sie mit großen Dateien arbeiten.

Die Claude-Desktop-Vorlage befindet sich in config/claude-desktop.json.

{
  "mcpServers": {
    "cityjson": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "yarroudh/cityjson-mcp:latest"]
    }
  }
}

Typische Konfigurationsorte für lokale Claude-Desktop-Server sind:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Fügen Sie die Vorlage in die Client-Konfiguration ein, beenden Sie dann Claude Desktop vollständig und öffnen Sie es erneut. Das Verzeichnis config/ enthält Vorlagen; Claude liest es nicht automatisch.

Klicken Sie in einem normalen Claude-Chat auf +, öffnen Sie Connectors, aktivieren Sie cityjson und erlauben Sie seine Tools unter Tool-Zugriff. Der Connector ist nur für Chats verfügbar, in denen er aktiviert ist. /input existiert im Connector-Container, nicht in Claudes Code-Umgebung.

So überprüfen Sie die Tool-Nutzung auf macOS:

tail -f "$HOME/Library/Logs/Claude/mcp-server-cityjson.log"

Erfolgreiche Aufrufe erscheinen als method="tools/call" gefolgt von einem Serverergebnis. Drücken Sie Ctrl+C, um die Überwachung zu beenden.

Claude Desktop unterstützt auch verpackte MCP-Bundles/Erweiterungen. Dieses Repository wird als Quell-ZIP geliefert, damit es transparent und bearbeitbar bleibt; die direkte stdio-Konfiguration oben ist das einfachste Entwicklungssetup.

Hinzufügen zu Claude Code

Die Claude-Code-Vorlage befindet sich in config/claude-code.json. Kopieren Sie sie in .mcp.json in das Projekt, in dem Sie Claude Code ausführen:

cp config/claude-code.json .mcp.json

Starten Sie Claude Code neu oder verbinden Sie seine MCP-Server nach der Änderung der Konfiguration erneut.

Hinzufügen zu Cursor

Cursor unterstützt lokale stdio-MCP-Server in mcp.json.

Eine Vorlage ist unter config/cursor-mcp.json enthalten.

Projektkonfiguration:

your-project/
└── .cursor/
    └── mcp.json

Globale Konfiguration:

~/.cursor/mcp.json

Beispiel:

{
  "mcpServers": {
    "cityjson": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "--rm", "-i", "yarroudh/cityjson-mcp:latest"]
    }
  }
}

Sobald aktiviert, erkennt Cursor die MCP-Tools und kann sie automatisch auswählen. Sie können auch explizit ein Tool in der Eingabeaufforderung nennen, zum Beispiel:

Verwenden Sie cityjson_validate für dieses Modell und erklären Sie dann jeden fehlgeschlagenen val3dity-Fehler unter Verwendung der CityJSON-Spezifikation, wo relevant.

Cursor-Dokumentation: https://cursor.com/docs/mcp

Hinzufügen zu VS Code

VS Code verwendet eine mcp.json, deren oberster Schlüssel servers ist.

Eine Vorlage ist unter config/vscode-mcp.json enthalten.

Arbeitsbereichskonfiguration:

your-project/
└── .vscode/
    └── mcp.json

Beispiel:

{
  "servers": {
    "cityjson": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "--rm", "-i", "yarroudh/cityjson-mcp:latest"]
    }
  }
}

Öffnen Sie die Befehlspalette und verwenden Sie die MCP-Serververwaltungsbefehle, um den Server bei Bedarf zu überprüfen/starten. VS Code unterstützt auch MCP-Sandbox-Steuerelemente auf unterstützten Plattformen; diese können über der eigenen Richtlinie für erlaubte Wurzeln dieses Servers geschichtet werden.

VS-Code-Dokumentation: https://code.visualstudio.com/docs/agents/reference/mcp-configuration

Client-Setup-Modell

flowchart LR
  CLAUDE["Claude Desktop<br/>claude_desktop_config.json"]
  CLAUDECODE["Claude Code<br/>.mcp.json"]
  CURSOR["Cursor<br/>.cursor/mcp.json"]
  VSCODE["VS Code<br/>.vscode/mcp.json"]
  WEB["CityJSON chat<br/>browser"]
  HOST["Chat host<br/>model + MCP client"]
  DOCKER["CityJSON MCP Docker image<br/>MCP stdio"]
  INPUT["Input inbox<br/>/input"]
  WS["Managed workspace<br/>/data"]
  TOOLS["Bundled backends<br/>cjio · cjval · val3dity · citygml-tools · cjdb"]

  CLAUDE --> DOCKER
  CLAUDECODE --> DOCKER
  CURSOR --> DOCKER
  VSCODE --> DOCKER
  WEB -->|stream attachments| INPUT
  WEB --> HOST
  HOST --> DOCKER
  INPUT --> DOCKER
  DOCKER --> WS
  DOCKER --> TOOLS

PNG herunterladen – hohe Auflösung

Tool-Katalog

Datensatz und Diagnostik

cityjson_import

Verwenden Sie dies für Dateien, die von der Chat-Anwendung in den Eingangsordner geliefert oder in einem gemounteten Verzeichnis abgelegt wurden:

{
  "filename": "amsterdam.city.json"
}

Wenn der Dateiname unbekannt ist, rufen Sie cityjson_list_imports auf. Wird filename weggelassen, wird nur dann automatisch importiert, wenn genau eine JSON-Datei vorhanden ist. Das Werkzeug kopiert und validiert die Quelle, bevor es ein Handle zurückgibt.

cityjson_import_text

Verwenden Sie dies nur, wenn ein kleines CityJSON-Dokument in einem Anwendungsworkflow bereits als Text vorliegt:

{
  "filename": "model.city.json",
  "content": "{\"type\":\"CityJSON\",\"version\":\"2.0\",\"CityObjects\":{},\"vertices\":[]}"
}

Der Inhalt wird strukturell geprüft, bevor er in den verwalteten Arbeitsbereich geschrieben wird. Es ist nicht für Browser-/Chat-Anhänge geeignet, da das vollständige Dokument über die MCP-Anfrage übertragen wird. cityjson_upload bleibt als veralteter Alias für die Kompatibilität erhalten.

cityjson_open

cityjson_open bleibt für fortgeschrittene Clients verfügbar, die absichtlich einen vollständigen, server-sichtbaren Pfad innerhalb eines erlaubten Wurzelverzeichnisses angeben. Normale Eingangsordner- und Anhang-Workflows sollten cityjson_import verwenden.

cityjson_download

Verwenden Sie dies, um ein Quell- oder transformiertes Dataset abzurufen, wenn im Container kein Host-Verzeichnis gemountet ist:

{
  "dataset_id": "cj_abc123def456",
  "filename": "cleaned.city.json"
}

In DATUM streamt der Host die unveränderliche Arbeitsbereichsdatei direkt und zeigt eine Download-Schaltfläche an, sodass große Ergebnisse nicht über den Modellkontext oder MCP-JSON laufen. Eigenständige MCP-Clients erhalten eine eingebettete application/json-Ressource; dieser Inline-Pfad hat standardmäßig ein Limit von 25 MiB, das über CITYJSON_MCP_MAX_DOWNLOAD_BYTES gesteuert wird.

Beispielhaftes Ergebnis:

{
  "datasetId": "cj_4ad572e79331",
  "version": "2.0",
  "cityObjectCount": 12543,
  "vertexCount": 382901,
  "lods": ["1.2", "2.2"]
}

Das Handle sind In-Memory-Metadaten, die auf eine Datei verweisen; das CityJSON-Dokument selbst wird durch das bloße Öffnen nicht kopiert.

Inspektion und Abfrage

cityjson_query ist der bevorzugte Weg, einem LLM die Inspektion großer Modelle zu ermöglichen, ohne das gesamte CityJSON-Dokument in den Modellkontext zu senden.

Beispiel:

{
  "dataset_id": "cj_4ad572e79331",
  "types": ["Building", "BuildingPart"],
  "bbox": [85000, 446000, 86000, 447000],
  "attributes": {
    "yearOfConstruction": { "gte": 2000 },
    "status": { "in": ["existing", "planned"] }
  },
  "limit": 100
}

Attribut-Prädikat-Operatoren:

• eq

• neq

• gt

• gte

• lt

• lte

• contains

• in

Der Bounding-Box-Filter ist [minX, minY, maxX, maxY] im CRS des Datasets. Objekt-Bounding-Boxen werden aus den referenzierten Vertices des Objekts und der CityJSON-transform berechnet, sofern vorhanden.

Validierung

flowchart LR
  DATA["Opened CityJSON<br/>dataset_id"]
  ALL["cityjson_validate"]
  CJVAL["cityjson_validate_schema<br/>cjval"]
  VAL3["cityjson_validate_geometry<br/>val3dity"]
  STRUCT["JSON + schema + structural<br/>consistency result"]
  GEOM["ISO 19107-style 3D<br/>geometry report"]
  COMBINE["Combined validation result"]

  DATA --> ALL
  ALL --> CJVAL
  ALL --> VAL3
  CJVAL --> STRUCT
  VAL3 --> GEOM
  STRUCT --> COMBINE
  GEOM --> COMBINE

PNG herunterladen — hohe Auflösung

Wann welcher Validator verwendet werden sollte

Verwenden Sie cityjson_validate_schema für Fragen wie:

• Ist das JSON syntaktisch gültiges CityJSON?

• Entspricht es dem CityJSON-Schema?

• Sind Eltern-/Kind-Referenzen konsistent?

• Existieren Vertex-Indizes?

• Sind Semantik-/Material-/Textur-Arrays strukturell kohärent?

• Sind Erweiterungsschemas gültig?

Verwenden Sie cityjson_validate_geometry für die geometrische Gültigkeit von MultiSurface-, CompositeSurface-, Solid-, MultiSolid- und CompositeSolid-Primitiven sowie für verwandte CityJSON-spezifische geometrische Prüfungen.

Für die übliche Benutzeranfrage „dieses CityJSON validieren“ verwenden Sie cityjson_validate.

Beispiel:

{
  "dataset_id": "cj_4ad572e79331"
}

Wenn eine cjval-Warnung doppelte oder ungenutzte Vertices meldet, ist eine natürliche Reparaturschleife:

1. cityjson_clean_vertices

2. cityjson_validate_schema

3. optional cityjson_validate_geometry

Transformation und Bearbeitung

Alle Werkzeuge in diesem Abschnitt geben ein neues Dataset-Handle zurück.

Beispiele für Teilmengen

Gebäude in einer Bounding-Box:

{
  "dataset_id": "cj_4ad572e79331",
  "types": ["Building"],
  "bbox": [85000, 446000, 86000, 447000]
}

Bestimmte Objekte:

{
  "dataset_id": "cj_4ad572e79331",
  "ids": ["NL.IMBAG.Pand.001", "NL.IMBAG.Pand.002"]
}

Alles außer Vegetationsobjekten:

{
  "dataset_id": "cj_4ad572e79331",
  "types": ["SolitaryVegetationObject", "PlantCover"],
  "exclude": true
}

CRS-Behandlung

Verwenden Sie cityjson_assign_crs nur, wenn die Koordinaten bereits im CRS ausgedrückt sind und die Metadaten fehlen/falsch sind. Es transformiert keine Koordinaten.

Verwenden Sie cityjson_reproject, wenn Koordinaten tatsächlich transformiert werden müssen:

{
  "dataset_id": "cj_4ad572e79331",
  "epsg": 28992
}

Für eine zuverlässige Neuprojektion benötigt das Quellmodell ein nutzbares Quell-CRS.

Export und Interoperabilität

Beispiel-Export:

{
  "dataset_id": "cj_4ad572e79331",
  "format": "glb",
  "destination": "/data/buildings.glb"
}

Beispiel CityGML → CityJSON:

{
  "source": "/input/model.gml",
  "json_lines": false
}

Beispiel CityJSON → CityGML:

{
  "dataset_id": "cj_4ad572e79331",
  "crs_name": "urn:ogc:def:crs:EPSG::28992",
  "output_directory": "/data/citygml-output"
}

Der Wrapper erfindet bewusst keine Option für eine CityGML/CityJSON-Zielversion. citygml-tools unterstützt CityGML 1.0/2.0/3.0 und CityJSON 1.0/1.1/2.0, aber das genaue CLI-Verhalten der Zielversion kann je nach Upstream-Version variieren; die Standardwerte des installierten Backends bleiben maßgeblich.

Datenbank-Werkzeuge

Verbindungsobjekt:

{
  "host": "localhost",
  "user": "cityjson",
  "database": "cityjson",
  "schema": "rotterdam"
}

Import:

{
  "dataset_id": "cj_4ad572e79331",
  "connection": {
    "host": "localhost",
    "user": "cityjson",
    "database": "cityjson",
    "schema": "rotterdam"
  },
  "attribute_indexes": ["yearOfConstruction"],
  "partial_attribute_indexes": ["function"]
}

Teilmengen-Export:

{
  "connection": {
    "host": "localhost",
    "user": "cityjson_reader",
    "database": "cityjson",
    "schema": "rotterdam"
  },
  "query": "SELECT object_id FROM rotterdam.cj_object WHERE object_id LIKE 'NL.IMBAG.%'",
  "collect": true
}

Der Wrapper lehnt SQL außer SELECT, Semikolons und offensichtlich modifizierende Schlüsselwörter ab. Dies ist eine Schutzmaßnahme, keine SQL-Sicherheitsgrenze: Verwenden Sie eine Datenbankrolle mit nur den für die Operation angemessenen Berechtigungen. Verwenden Sie für Exporte eine Rolle, die keine Daten ändern kann.

Spezifikations-, Schema- und Erweiterungswissen

Beispiel für eine Spezifikationsabfrage:

{
  "query": "Geometry templates",
  "max_chars": 20000
}

Beispiel für eine Kernschema-Abfrage:

{
  "name": "geomprimitives.schema.json"
}

Beispiel für die Erweiterungssuche:

{
  "query": "noise"
}

Dann ein bestimmtes Schema abrufen:

{
  "name": "noise",
  "version": "2.0.0"
}

Warum dies nicht von cityjson/cj-mcp abhängt

cityjson/cj-mcp ist nützlich für den Abruf von Spezifikationskapiteln. Dieser Server benötigt umfassendere Operationen, daher liest der Wissensadapter die kanonischen CityJSON-Spezifikations-/Schema-/Erweiterungsquellen direkt und bündelt einen kleinen deterministischen 2.0.2-Referenzindex. Dies vermeidet einen zweiten MCP-Prozess und einen Versionsabweichungs-Fehlermodus.

Ein zukünftiger Adapter könnte cityjson_spec_read an cj-mcp delegieren, ohne die öffentlichen MCP-Toolnamen zu ändern.

Empfohlene Prompts / Rezepte

Diese Prompts setzen voraus, dass das Host-Dateiverzeichnis als Eingabe-Inbox konfiguriert ist. Der Agent verwendet Dateinamen und prüft /input nie in seiner eigenen Code-Umgebung.

Prüfen vor dem Ändern

Importiere tile.city.json mit cityjson_import. Nenne mir die CityJSON-Version, das CRS, die CityObject-Anzahl nach Typ, die LoDs, Attributnamen und Erweiterungen. Ändere nichts.

Erwartete Tools: cityjson_import → cityjson_info.

Validieren und diagnostizieren

Importiere tile.city.json und validiere es dann mit cjval und val3dity. Verwende nur die CityJSON-Connector-Tools. Trenne cjval-Warnungen von Fehlern, gruppiere val3dity-Fehler nach Fehlercode, identifiziere die betroffenen CityObject-IDs und konsultiere die CityJSON-Spezifikation, wenn ein Fehler eine strukturelle CityJSON-Regel betrifft. Wenn ein Validierungsbericht das Tool-Ausgabelimit überschreitet, erstelle nicht überlappende räumliche Teilmengen, validiere jede Teilmenge und aggregiere die Zählungen ohne Doppelzählung. Ändere die Originaldatei nicht.

Erwartete Tools: cityjson_import → cityjson_validate → optional cityjson_get_object / cityjson_spec_read.

Sicherer Bereinigungszyklus

Importiere tile.city.json, führe eine strukturelle Validierung durch, und wenn die einzigen strukturellen Warnungen doppelte oder ungenutzte Vertices sind, erstelle einen bereinigten abgeleiteten Datensatz, führe die vollständige Validierung erneut durch und gib das Ergebnis mit cityjson_download als tile-clean.city.json zurück. Überschreibe niemals das Original.

Erwartete Tools: cityjson_import → cityjson_validate_schema → cityjson_clean_vertices → cityjson_validate → cityjson_save.

Räumlicher Ausschnitt

Extrahiere aus der Inbox-Datei city.city.json nur Building- und BuildingPart-Objekte, die die Bbox [85000, 446000, 86000, 447000] schneiden, behalte LoD 2.2, projiziere auf EPSG:28992 um, validiere das Ergebnis und gib es dann mit cityjson_download als extract.city.json zurück.

Erwartete Tools: cityjson_import → cityjson_subset → cityjson_filter_lod → cityjson_reproject → cityjson_validate → cityjson_save.

CityGML-Interoperabilität

Konvertiere /input/source.gml in CityJSON, prüfe die resultierenden Objekttypen und LoDs, validiere es mit cjval und val3dity und berichte über alle Informationen, die während der Konvertierung verloren gegangen oder normalisiert wurden.

Erwartete Tools: citygml_to_cityjson → cityjson_info → cityjson_validate, plus Spezifikationsabfrage, wenn nützlich.

Datenbank-Workflow

Importiere die Inbox-Datei municipality.city.json, validiere sie und importiere sie dann in den PostgreSQL-Host localhost, Datenbank cityjson, Schema municipality. Füge einen Attributindex für yearOfConstruction hinzu. Verwende das Datenbankpasswort aus der MCP-Prozessumgebung.

Erwartete Tools: cityjson_import → cityjson_validate_schema → cityjson_db_import.

Erweiterungsbewusstes Denken

Dieses Modell deklariert die CityJSON-noise-Erweiterung. Finde die registrierte Erweiterungsdokumentation/das Schema, erkläre die zusätzlichen Eigenschaften, die sie zulässt, und validiere das Modell mit seinem lokalen Erweiterungsschema, falls ich eines bereitstelle.

Erwartete Tools: cityjson_info → cityjson_extensions_registry → cityjson_extension_schema → optional cityjson_validate_schema.

Datenlebenszyklus und Unveränderlichkeit

Das zentrale Design ist:

browser attachment ──stream──> input inbox ──cityjson_import──> cj_A
mounted inbox file ──────────────────────────cityjson_import──> cj_A
authorized path ─────────────────────────────cityjson_open────> cj_A
                                  │
                                  ├── subset ───────> cj_B
                                  │                   │
                                  │                   └── reproject ──> cj_C
                                  │
                                  └── validate (does not modify data)

• cityjson_import kopiert eine Inbox-Datei in den verwalteten Arbeitsbereich, validiert sie und gibt die anfängliche Dataset-ID zurück.

• cityjson_open registriert einen explizit autorisierten, server-sichtbaren Pfad für erweiterte Workflows.

• cityjson_import_text ist ein Fallback für kleine Dokumente; sein veralteter Alias cityjson_upload verarbeitet keine binären Anhänge.

• Eine Transformation fordert das Backend auf, eine neue Datei innerhalb von CITYJSON_MCP_WORKSPACE zu schreiben.

• Der Server öffnet die erzeugte Datei und vergibt ihr eine neue zufällige dataset_id.

• cityjson_save ist der explizite Schritt, der einen ausgewählten Zustand an ein vom Benutzer gewähltes Ziel kopiert.

Dies erleichtert es einem Agenten erheblich, Vorher/Nachher-Validierungen zu vergleichen, und verhindert, dass normale Transformationsaufrufe die Originalquelle stillschweigend überschreiben.

Sicherheitsmodell

Dieser Server führt leistungsfähige georäumliche Programme lokal aus. Behandeln Sie die MCP-Serverinstallation wie eine lokale Codeinstallation.

Eingebaute Schutzmaßnahmen:

1. Erlaubte Wurzeln — Host-Pfadoperationen müssen innerhalb von CITYJSON_MCP_ALLOWED_ROOTS, CITYJSON_MCP_INPUT oder dem verwalteten Arbeitsbereich liegen. Browser-Uploads erhalten zufällige sichere Dateinamen im Eingabeverzeichnis.

2. Kein beliebiges Shell-Tool — es gibt keinen run_shell-Befehl oder ein uneingeschränktes run_cjio-MCP-Tool.

3. Keine Shell-Interpolation — externe Programme werden mit Argumentarrays und shell: false aufgerufen.

4. Typisierte Tool-Schemas — Zod beschränkt Typen, Enums, EPSG-Ganzzahlen, Bbox-Formen, Datenbankschema-Identifikatoren usw.

5. PostgreSQL-Passwort bleibt in der Umgebung — Datenbank-Tool-Schemas enthalten kein Passwortfeld.

6. DB-Export-SQL-Schutz — nur einzelne SELECT-Zeichenfolgen ohne Semikolons oder offensichtlich mutierende Schlüsselwörter werden akzeptiert. Verwenden Sie dennoch eine Datenbankrolle mit nur den erforderlichen Berechtigungen.

7. Befehls-Timeout/Ausgabegrenze — Unterprozesse haben standardmäßig ein 120-Sekunden-Timeout und begrenzte erfasste Ausgabe. Setzen Sie CITYJSON_MCP_COMMAND_TIMEOUT_MS für große Aufträge.

Führen Sie den MCP für gemeinsame oder Produktionsumgebungen unter einem Betriebssystemkonto/Container mit nur den Dateisystem- und Datenbankberechtigungen aus, die er tatsächlich benötigt.

Docker

Das enthaltene docker/Dockerfile installiert:

• Node-Laufzeit + MCP-Paketabhängigkeiten

• cjio

• cjdb

• cjval

• val3dity

• citygml-tools

Die meisten Benutzer sollten das veröffentlichte Image ziehen:

docker pull yarroudh/cityjson-mcp:latest

Für einen lokalen Quellcode-Build cachen Sie die beiden teuren Compiler-Stufen, bevor Sie den Rest bauen:

docker build -f docker/Dockerfile --target val3dity-builder -t cityjson-mcp-val3dity-builder .
docker build -f docker/Dockerfile --target cjval-builder -t cityjson-mcp-cjval-builder .
docker build -f docker/Dockerfile -t cityjson-mcp .

Führen Sie nach einem lokalen Build docker run --rm --entrypoint node cityjson-mcp /app/scripts/doctor.mjs aus, um alle fünf ausführbaren Dateien zu verifizieren.

Von GitHub Actions veröffentlichen

Der Workflow in .github/workflows/docker-publish.yml baut linux/amd64- und linux/arm64-Images auf nativen Runnern, erstellt ein Multiplattform-Manifest und pusht es an yarroudh/cityjson-mcp.

Konfigurieren Sie das GitHub-Repository unter Settings → Secrets and variables → Actions:

• Variable DOCKERHUB_USERNAME: yarroudh

• Secret DOCKERHUB_TOKEN: ein Docker-Hub-Zugriffstoken mit Schreibberechtigung für dieses Repository

Führen Sie den Workflow manuell über den Tab Actions aus oder veröffentlichen Sie einen Versions-Tag:

git tag v0.1.0
git push origin v0.1.0

Ein Versions-Tag veröffentlicht 0.1.0, 0.1 und latest. Der BuildKit-Cache wird für spätere Läufe beibehalten, sodass unveränderte val3dity- und cjval-Ebenen nicht erneut kompiliert werden müssen.

Entwicklungs-PostGIS:

docker compose -f docker/docker-compose.postgis.yml up -d

Siehe docker/README.md.

Entwicklungsstruktur

cityjson-mcp/
├── src/
│   ├── index.mjs                 # MCP server entry point
│   ├── core/
│   │   ├── dataset-manager.mjs   # immutable dataset handles
│   │   ├── cityjson-native.mjs   # parsing, summaries, bbox, queries
│   │   ├── path-policy.mjs       # allowed filesystem roots
│   │   └── command-runner.mjs    # safe subprocess execution
│   ├── adapters/
│   │   ├── cjio.mjs
│   │   ├── cjval.mjs
│   │   ├── val3dity.mjs
│   │   ├── citygml-tools.mjs
│   │   ├── cjdb.mjs
│   │   └── knowledge.mjs
│   ├── tools/
│   │   └── register-tools.mjs
│   └── util/
├── resources/spec/               # deterministic CityJSON 2.0.2 reference index
├── config/                       # Claude/Cursor/VS Code examples
├── diagrams/                     # Mermaid source + high-resolution PNG exports
├── examples/
├── scripts/
├── test/
└── docker/

Die MCP-Protokollebene verwendet die stabile v2-Linie des offiziellen Model-Context-Protocol-TypeScript-Server-SDKs und den stdio-Transport.

Diagramme

Der gesamte Mermaid-Quellcode ist in diagrams/*.mmd gespeichert. Die eingecheckten PNG-Dateien werden aus denselben Graphdefinitionen mit 300-DPI-Graphviz-Ausgabe generiert, mit Abmessungen im Bereich von mehreren tausend Pixeln, damit sie in Dokumenten/Folien scharf bleiben.

Regenerieren Sie sie:

python3 scripts/render_diagrams.py

Der Renderer unterstützt die in dieser README verwendete Mermaid-Flussdiagramm-Teilmenge und erfordert die Graphviz-dot-ausführbare Datei.

Aktuelle PNG-Dateien:

• diagrams/architecture.png

• diagrams/workflow.png

• diagrams/validation.png

• diagrams/client-setup.png

Tests

Native Tests benötigen kein externes georäumliches Backend:

npm test

Sie testen:

• CityJSON-Parsing und Zusammenfassungserstellung

• transformierte/dequantisierte Objekt-Bbox-Berechnung

• native Typ-/Bbox-/Attributabfragen

• enthaltenes Beispiel-JSON

Syntaxprüfung jeder .mjs-Quelldatei:

npm run check

Externe Adapter sind bewusst dünne Wrapper um ihre offiziellen CLIs. Fügen Sie für eine Bereitstellungsumgebung Integrationstests hinzu, die an die genauen Backend-Versionen gebunden sind, die Sie bereitstellen.

Bekannte Einschränkungen / v0.1-Entscheidungen

• Das native cityjson_open lädt derzeit eine reguläre CityJSON-JSON-Datei in den Speicher. Für extrem große CityJSONSeq-Streams verwenden Sie Backend-Workflows oder fügen Sie einen Streaming-Adapter hinzu.

• Dataset-Handles existieren für die Lebensdauer des MCP-Serverprozesses; ein Neustart des Clients/Servers macht alte dataset_id-Werte ungültig. Öffnen Sie Quell-/gespeicherte Dateien nach dem Neustart erneut.

• Abgeleitete Arbeitsbereichsdateien werden nicht automatisch gelöscht. Dies ist für die Rückverfolgbarkeit beabsichtigt, aber bereinigen Sie den Arbeitsbereich regelmäßig.

• cityjson_query berechnet Bounding-Boxen aus Geometrie, die explizit auf jedem CityObject gespeichert ist. Es vereinigt nicht automatisch alle Kind-Geometrien in die Bounding-Box eines Elternteils.

• cityjson_spec_read, cityjson_schema_read und Erweiterungs-Registry-/Schema-Tools benötigen ausgehenden Netzwerkzugriff auf kanonische CityJSON-Endpunkte. cityjson_spec_outline funktioniert aus dem gebündelten Index.

• cityjson_to_citygml überlässt die Auswahl der Ziel-CityGML-Version bewusst den installierten citygml-tools-Standardwerten, anstatt sich auf ein unverifiziertes CLI-Flag zu verlassen.

• val3dity ist GPL-3.0-Software; dieses Projekt ruft die ausführbare Datei als externes Backend auf und bindet sie nicht ein. Überprüfen Sie die Lizenzauswirkungen für Ihr eigenes Vertriebs-/Bereitstellungsmodell.

• Das mitgelieferte Docker-Basisimage enthält weder val3dity noch citygml-tools.

Upstream-Referenzen

• CityJSON-Spezifikation: https://www.cityjson.org/specs/

• CityJSON-Spezifikations-Repository: https://github.com/cityjson/specs

• CityJSON-Erweiterungs-Registry: https://github.com/cityjson/extensions

• cjio: https://github.com/cityjson/cjio

• cjval: https://github.com/cityjson/cjval

• val3dity: https://github.com/tudelft3d/val3dity

• citygml-tools: https://github.com/citygml4j/citygml-tools

• cjdb: https://github.com/cityjson/cjdb

• Bestehendes spezifikationsbasiertes CityJSON-MCP: https://github.com/cityjson/cj-mcp

• MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

• Cursor-MCP-Dokumentation: https://cursor.com/docs/mcp

• VS-Code-MCP-Dokumentation: https://code.visualstudio.com/docs/agents/reference/mcp-configuration

Lizenz

Der Code in diesem Repository wird unter der MIT-Lizenz bereitgestellt; siehe LICENSE.

Die externen Backends bleiben separate Software unter ihren eigenen Lizenzen. Insbesondere ist val3dity GPL-3.0, citygml-tools Apache-2.0, und cjio/cjval/cjdb haben ihre eigenen Upstream-Lizenzdateien. Nichts in diesem Repository lizenziert diese Projekte neu.