cityjson-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| CJDB_BIN | No | Optional cjdb executable override. | cjdb |
| CJIO_BIN | No | Optional cjio executable override. | cjio |
| CJVAL_BIN | No | Optional cjval executable override. | cjval |
| PGPASSWORD | No | PostgreSQL password used by cjdb for database import/export. | |
| VAL3DITY_BIN | No | Optional val3dity executable override. | val3dity |
| CITYGML_TOOLS_BIN | No | Optional citygml-tools executable override. | citygml-tools |
| CITYJSON_MCP_INPUT | No | Input directory used by cityjson_import. | ./input |
| CITYJSON_MCP_WORKSPACE | No | Managed source and derived datasets. | ./.cityjson-mcp-workspace |
| CITYJSON_MCP_ALLOWED_ROOTS | No | Authorized filesystem roots. Use ':' on macOS/Linux and ';' on Windows. | current directory |
| CITYJSON_MCP_COMMAND_TIMEOUT_MS | No | External command timeout. | 120000 |
| CITYJSON_MCP_MAX_DOWNLOAD_BYTES | No | Maximum inline MCP download size. Datum streams downloads directly. | 26214400 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
When the user names a CityJSON file in a configured project or data folder, call cityjson_open with that filename. Use a relative path only when names are ambiguous. Pass returned filenames in the dataset_id tool parameter for follow-up calls. Refer to files by name in every user-facing answer; never mention tool parameter names or opaque internal handles. If a client already provided the complete text of a small CityJSON attachment in the model context, call cityjson_import_text with that text and its original filename; do not ask the user to select it again. If the attachment text is missing, incomplete, or large, call cityjson_upload in an MCP Apps compatible client with the user’s question to open the in-chat picker. The upload app transfers file bytes without including them in the model context. After either import reports a filename, use that filename in dataset_id tool parameters and in answers. For files placed in the input inbox by a host application, call cityjson_import with the inbox filename. Use cityjson_list_imports only when needed. Do not ask users to manage the inbox or workspace. Do not put large or incomplete attachments into MCP arguments. A chat attachment is not automatically a server-visible file. Clients that cannot show MCP Apps must provide a file bridge or a shared path for larger files. Use cityjson_download to return an opened or transformed model to the client when no host directory is mounted. Transformations create a new named file and keep the source unchanged. Use cityjson_backend_status when an external backend is unavailable. Use cityjson_validate for a complete structural and geometric check; use the individual validators when you need backend-specific detail. Prefer cityjson_query over returning entire CityJSON files to the model. Consult cityjson_spec_read, cityjson_schema_read, or the extension tools when semantics or schemas are relevant.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| cityjson_backend_statusA | Check which external CityJSON/CityGML engines are installed and callable. Run this first when a backend-dependent operation fails. |
| cityjson_openA | Open a CityJSON file from an optional configured project or data folder by filename, relative path, or full server-visible path. The server snapshots the file and returns its filename for later tools. |
| cityjson_list_importsA | List JSON files in the configured input inbox. Use this when the user did not name an attached/imported file or when cityjson_import reports multiple candidates. Returns filenames only; never ask the user for an absolute path. |
| cityjson_importA | Register a CityJSON file already placed in the configured input inbox and return its filename. This is for clients with an upload bridge, such as Datum. If filename is omitted, the inbox must contain exactly one JSON file. |
| cityjson_import_textA | Import a small complete CityJSON document already available as text, including a small chat attachment exposed to the model by the client. Preserve the original filename. For missing, incomplete, or large attachments, use cityjson_upload. |
| cityjson_downloadA | Prepare an opened or transformed dataset for download. The web host streams the managed file directly; standalone MCP clients receive an embedded application/json resource within the configured inline-size limit. |
| cityjson_infoB | Return metadata, object counts, types, LoDs, attribute names, transform and extensions for an opened dataset. |
| cityjson_saveC | Copy an opened/derived CityJSON dataset to an explicit destination path. |
| cityjson_list_objectsB | List CityObjects with IDs, types, selected attributes and LoDs. Supports filtering by CityObject type and pagination. |
| cityjson_get_objectB | Return one complete CityObject and a computed real-world bounding box derived from referenced vertices. |
| cityjson_queryC | Query CityObjects natively by IDs, types, 2D bbox and attribute predicates. Attribute predicates support eq, neq, gt, gte, lt, lte, contains and in. |
| cityjson_validate_schemaB | Validate a dataset with the official cjval validator: JSON syntax, CityJSON schemas, extensions and additional structural consistency checks. |
| cityjson_validate_geometryB | Validate CityJSON 3D primitives with val3dity according to ISO 19107 concepts and CityJSON-specific geometric checks. Returns a detailed report plus a compact reportSummary containing every invalid object ID and error-code count. |
| cityjson_validateB | Run cjval and val3dity and return one combined structural + geometric validation result. geometry.reportSummary contains the complete invalidObjectIds list for reliable follow-up subsets. |
| cityjson_subsetB | Create a derived CityJSON subset with cjio using IDs, bbox, radius, random count or CityObject types. Returns a new filename. |
| cityjson_filter_lodC | Keep only one level of detail using cjio lod_filter. Returns a new filename. |
| cityjson_reprojectA | Reproject coordinates to a target EPSG CRS with cjio. The source file must already define a CRS. Returns a new filename. |
| cityjson_assign_crsA | Assign/update the EPSG reference without changing coordinate values using cjio. Returns a new filename. |
| cityjson_translateB | Translate CityJSON coordinates with cjio. With minxyz, coordinates are shifted relative to the supplied minimum; without it cjio uses the model minimum. |
| cityjson_clean_verticesB | Remove duplicate and orphan vertices with cjio vertices_clean. Returns a new filename. |
| cityjson_triangulateB | Triangulate surfaces with cjio. Use sloppy=true only when the robust triangulator fails. |
| cityjson_mergeB | Merge two or more opened CityJSON files with cjio. Returns a new filename. |
| cityjson_attribute_renameC | Rename an attribute across CityObjects with cjio. |
| cityjson_attribute_removeC | Remove an attribute across CityObjects with cjio. |
| cityjson_remove_texturesB | Remove all textures with cjio. Returns a new filename. |
| cityjson_remove_materialsB | Remove all materials with cjio. Returns a new filename. |
| cityjson_upgradeB | Upgrade an older supported CityJSON file to the version supported by the installed cjio. |
| cityjson_exportC | Export an opened CityJSON dataset with cjio to jsonl, obj, stl, glb or b3dm. |
| citygml_to_cityjsonB | Convert a CityGML 1.0/2.0/3.0 GML/XML file to CityJSON using citygml-tools. A regular CityJSON output is automatically registered and returned by filename. |
| cityjson_to_citygmlB | Convert an opened CityJSON dataset to CityGML using citygml-tools. The installed citygml-tools version controls the default target encoding. |
| cityjson_db_importB | Convert the dataset to CityJSONSeq with cjio and import it into PostgreSQL/PostGIS using cjdb. PostgreSQL password should be supplied through PGPASSWORD, not tool arguments. |
| cityjson_db_exportA | Export all objects or a read-only SELECT-defined subset from cjdb to CityJSONSeq and optionally collect it into a named CityJSON file. |
| cityjson_spec_outlineA | Return the bundled outline and canonical URLs for the current CityJSON specification and schemas. |
| cityjson_spec_readA | Fetch the canonical CityJSON 2.0.2 living specification and return either the beginning or a context window around a search query. |
| cityjson_schema_readA | Fetch one canonical CityJSON 2.0.2 JSON Schema by name. |
| cityjson_extensions_registryC | Fetch the official CityJSON Extensions registry and optionally return context around a search term. |
| cityjson_extension_schemaB | Fetch a registered CityJSON Extension schema from the canonical cityjson.github.io registry URL. |
| cityjson_uploadA | Open an in-chat file picker to upload a CityJSON file directly. Use this when the user attached or wants to choose a file that is not visible to the MCP server. The file is transferred outside the model context; no project folder or workspace setup is needed. Pass the user’s question so the app can continue after upload. |
| cityjson_upload_startC | Start an upload from the CityJSON file picker. |
| cityjson_upload_chunkC | Send the next chunk from the CityJSON file picker. |
| cityjson_upload_finishC | Validate and register the uploaded CityJSON file. |
| cityjson_upload_cancelC | Discard an unfinished CityJSON upload. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| ui://cityjson/upload-app.html | |
| cityjson-reference-index | Specification chapters, schema names and canonical reference URLs. |
TDQS
Scored across 42 tools
Most tools target a distinct operation, but two clusters overlap heavily: the upload/import family (cityjson_upload, cityjson_upload_start, cityjson_upload_chunk/finish/cancel, cityjson_import, cityjson_import_text, cityjson_open, cityjson_list_imports) and the validation family (cityjson_validate, cityjson_validate_schema, cityjson_validate_geometry). Descriptions do provide guidance on when to use each, but an agent must read carefully to avoid misselection.
All tools use a consistent snake_case cityjson_-prefixed verb_noun pattern (cityjson_validate_geometry, cityjson_subset, cityjson_reproject, etc.), which is highly predictable. A few exceptions are noun-only (cityjson_info, cityjson_download, cityjson_backend_status) but these remain readable and consistent in style.
42 tools is heavy for the stated scope and pushes well past the 15-tool guideline, especially since much of the surface is protocol plumbing (upload chunk/finish/cancel) and redundant validation entry points. The set feels over-expanded rather than tightly scoped.
Coverage of the CityJSON lifecycle is strong: ingestion, validation, spatial/CRS transforms, geometry cleanup, subsetting, format conversion, DB import/export, querying, and spec/schema lookups are all present. Minor gaps exist around mutating object data—no attribute-set/add or object creation/deletion tools—but core workflows are covered.