CityJSON MCP

一个本地 Model Context Protocol (MCP) 服务器，用于实际处理 CityJSON，而不仅仅是阅读规范。

它为 MCP 客户端（如 Claude Desktop、Cursor 和 VS Code）提供了一个稳定的、面向 CityJSON 的工具 API，底层由以下组件支持：

• cjio — CityJSON 操作、过滤、CRS 操作、清理、合并和导出。

• cjval — 官方 CityJSON/CityJSONSeq 语法、模式和结构验证。

• val3dity — 针对 CityJSON 图元的 3D 几何有效性检查。

• citygml-tools — CityGML ↔ CityJSON 转换。

• cjdb + PostgreSQL/PostGIS — 持久化 CityJSON 存储/导入/导出。

• CityJSON 2.0.2 规范、JSON Schema 和扩展注册表 — 为代理提供实时规范参考访问。

该服务器暴露了 38 个 MCP 工具。转换使用不可变数据集句柄：诸如 cityjson_subset 之类的操作会返回一个新的 dataset_id，并且不会覆盖源数据集。一个可选的一页式聊天主机将浏览器附件流式传输到 MCP 输入收件箱，并且只将数据集句柄发送给配置的模型。

状态：这是一个实用的 v0.1 实现。推荐的 Docker 镜像捆绑了所有外部后端；不使用 Docker 进行开发仍然需要单独安装各个命令。

架构

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 — 高分辨率

面向 MCP 的 API 刻意不暴露任意 shell 命令，例如 run_cjio("...")。每个 MCP 工具都有类型化的输入模式。命令通过 spawn(..., { shell: false }) 调用，这保持了面向代理的契约稳定，并避免了 shell 字符串插值。

典型代理工作流

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 — 高分辨率

例如，用户可以这样说：

导入 rotterdam.city.json，验证其 CityJSON 结构和 3D 几何，仅保留 bbox [90000, 435000, 91000, 436000] 内的建筑物，将结果重投影到 EPSG:28992，清理重复和孤立顶点，再次验证结果，并通过 cityjson_download 返回它。

MCP 客户端可以大致按以下方式解析该请求：

1. cityjson_import

2. cityjson_validate

3. cityjson_subset

4. cityjson_reproject

5. cityjson_clean_vertices

6. cityjson_validate

7. cityjson_save

每个转换都会返回一个新的 dataset_id，因此中间状态在对话期间保持可用。

快速开始

DATUM 一页式聊天，支持直接附件

包含的 DATUM 聊天应用程序是最简单的附件工作流。它将每个浏览器附件流式传输到 CITYJSON_MCP_INPUT，通过实时 MCP 服务器导入它，并且只给模型提供生成的 dataset_id 和摘要。

您可以选择在本地环境文件中预配置默认模型：

cp .env.example .env

选择 API 风格，然后设置支持工具调用的模型 ID、其密钥及其基础 URL。例如，DeepSeek 使用 OpenAI 兼容风格：

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

此文件是可选的：模型、提供商、API 密钥和基础 URL 也可以在应用程序的 配置模型 对话框中输入。对话框凭据仅保存在服务器内存中，用于浏览器会话，绝不会返回给浏览器或传递给 MCP 工具。

MODEL_PROVIDER 接受 anthropic 或 openai，因为它选择的是 API 协议，而不是提供模型的公司。anthropic 使用 Messages；openai 使用 OpenAI 兼容的 Chat Completions，因此也通过 MODEL_BASE_URL 支持兼容服务，例如 DeepSeek。

运行完整的应用程序。这是默认方式，因为镜像包含 cjio、cjval、val3dity、citygml-tools 和 cjdb：

npm install
npm run chat

然后打开 http://127.0.0.1:3000。附加文件会自动执行以下序列：

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

npm run chat 等同于：

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

Compose 配置仅将应用程序绑定到 127.0.0.1，并将输入/工作区数据保存在 Docker 卷中。它从 .env 读取可选的默认模型；否则应用程序会打开模型配置对话框。

对于在已安装全部五个可执行文件的主机上进行开发，请使用 npm run chat:host。主机模式会执行后端就绪检查，并拒绝宣传非功能性工具箱。CHAT_ALLOW_PARTIAL_BACKENDS=true 仅用于有意的仅检查开发，以覆盖该检查。

使用完整 Docker 运行时的独立 MCP 客户端

Docker 镜像包含 MCP 服务器和全部五个后端。安装 Docker Desktop，然后从 Docker Hub 拉取镜像：

docker pull yarroudh/cityjson-mcp:latest

确认每个后端都存在：

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

输出应报告 cjio、cjval、val3dity、citygml-tools 和 cjdb 的 OK。

配置输入收件箱

MCP 本身不传输普通的聊天附件。对于 Claude Desktop 和其他独立客户端，请挂载一次主机目录。将 /absolute/path/to/cityjson-files 替换为真实的绝对目录：

{
  "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"
      ]
    }
  }
}

主机目录在 Docker 内部显示为 /input。用户和代理仅引用文件名：

导入 model.city.json 并总结它。

代理调用 cityjson_import({"filename":"model.city.json"})。cityjson_list_imports 可以发现可用的文件名，cityjson_import 将选定的源复制到不可变的管理工作区中。输入挂载无法修改。

聊天附件路径（如 /mnt/user-data/... 和 /home/claude/...）属于客户端的私有环境。它们不存在于 MCP 容器内部。cityjson_import_text 仅可用于小型程序化提供的 JSON 文本；cityjson_upload 是其已弃用的兼容性别名，不是真正的文件上传通道。

镜像包含 cjio、cjval、val3dity、citygml-tools 和 cjdb；不需要主机 Python、Rust、Java 或地理空间库。在您再次运行 docker pull yarroudh/cityjson-mcp:latest 后，Docker 会在需要时自动拉取更新的镜像层。

要从源码构建，请先缓存两个较慢的编译阶段，然后再构建其余镜像：

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

如果后续层失败，重新运行最终命令会重用已完成的 val3dity 和 cjval 层，而不是从头编译它们。

可选：不使用 Docker 运行

以下部分仅在直接运行 node src/index.mjs 而不是使用完整 Docker 镜像时才需要。

1. 要求

MCP 服务器本身需要：

• Node.js 20+

• npm

安装其 JavaScript 依赖项：

cd cityjson-mcp
npm install

然后检查源码和原生测试：

npm run check
npm test

检查哪些外部后端可用：

npm run doctor

即使某些后端缺失，MCP 也可以启动。只有依赖缺失后端的工具才会失败。代理也可以自行调用 cityjson_backend_status。

2. 安装您需要的后端

cjio

官方项目：https://github.com/cityjson/cjio

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

这些附加组件很有用，因为重投影、三角化/导出和相关操作需要可选的 Python 包。

cjval

官方项目：https://github.com/cityjson/cjval

安装 Rust，然后：

cargo install cjval --features build-binary

val3dity

官方项目：https://github.com/tudelft3d/val3dity

在 macOS 上，上游项目提供了 Homebrew 公式：

brew tap tudelft3d/software
brew install val3dity

在 Windows 上，使用上游发布的可执行文件。在 Linux 上，请遵循上游的 CMake/CGAL/Eigen/GEOS 构建说明。val3dity 目前直接验证 CityJSON/CityJSONSeq；当前版本不再解析 CityGML，因此当您的源是 CityGML 时，请先使用 citygml_to_cityjson。

citygml-tools

官方项目：https://github.com/citygml4j/citygml-tools

当前版本需要 Java 17+。下载并解压发行版，然后确保 citygml-tools 启动器在 PATH 上，或者将 CITYGML_TOOLS_BIN 指向该启动器。准备本 README 时的当前稳定版本是 2.5.0。

cjdb

官方项目：https://github.com/cityjson/cjdb

python -m pip install cjdb

cjdb 需要带有 PostGIS 的 PostgreSQL。docker/docker-compose.postgis.yml 中包含一个开发用 compose 文件。

3. 授权 MCP 可以访问的文件夹

服务器拒绝访问明确授权的根目录之外的文件路径。

macOS/Linux 示例：

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 在根目录之间使用分号：

C:\citydata;D:\city-models

工作区存储派生的 CityJSON 数据集、验证器报告和中间 CityJSONSeq 文件。它会自动创建。

可选的可执行文件覆盖：

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

对于 cjdb，请在进程环境中设置 PostgreSQL 密码，而不是将其放在 MCP 参数中：

export PGPASSWORD='...'

4. 手动测试服务器

stdio MCP 服务器在直接启动时通常看起来“什么都不做”，因为它们正在等待 stdin 上的 MCP JSON-RPC 消息。您仍然可以通过以下方式确认启动：

npm run doctor
npm test

然后配置下面的一个 MCP 客户端。提供的模板启动完整的 Docker 镜像。贡献者可以将 Docker 命令替换为 node src/index.mjs 的绝对路径，并设置上述环境变量。

将其添加到 Claude Desktop

Claude Desktop 本地 MCP 配置使用 mcpServers 对象。提供的模板启动已发布的镜像，无需主机挂载。处理大文件时，请添加快速开始中显示的挂载。

Claude Desktop 模板位于 config/claude-desktop.json。

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

Claude Desktop 本地服务器的典型配置位置是：

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

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

将模板合并到客户端配置中，然后完全退出并重新打开 Claude Desktop。config/ 目录包含模板；Claude 不会自动读取它。

在普通的 Claude 聊天中，点击 +，打开 连接器，启用 cityjson，并在 工具访问 下允许其工具。该连接器仅对启用了它的聊天可用。/input 存在于连接器容器内部，而不是 Claude 的代码环境中。

要在 macOS 上验证工具使用情况：

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

成功的调用显示为 method="tools/call"，后跟服务器结果。按 Ctrl+C 停止监视。

Claude Desktop 还支持打包的 MCP 捆绑包/扩展。此仓库以源码 ZIP 形式交付，因此保持透明且可编辑；上述直接 stdio 配置是最简单的开发设置。

将其添加到 Claude Code

Claude Code 模板位于 config/claude-code.json。将其复制到您运行 Claude Code 的项目中的 .mcp.json：

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

更改配置后，请重启 Claude Code 或重新连接其 MCP 服务器。

将其添加到 Cursor

Cursor 在 mcp.json 中支持本地 stdio MCP 服务器。

模板包含在 config/cursor-mcp.json 中。

项目配置：

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

全局配置：

~/.cursor/mcp.json

示例：

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

启用后，Cursor 会发现 MCP 工具并可以自动选择它们。您也可以在提示中显式命名工具，例如：

在此模型上使用 cityjson_validate，然后使用 CityJSON 规范（如相关）解释每个失败的 val3dity 错误。

Cursor 文档：https://cursor.com/docs/mcp

将其添加到 VS Code

VS Code 使用 mcp.json，其顶级键是 servers。

模板包含在 config/vscode-mcp.json 中。

工作区配置：

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

示例：

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

打开命令面板，并使用 MCP 服务器管理命令来检查/启动服务器（如果需要）。VS Code 在支持的平台上还支持 MCP 沙箱控制；这些可以叠加在此服务器自身的允许根策略之上。

VS Code 文档：https://code.visualstudio.com/docs/agents/reference/mcp-configuration

客户端设置模型

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 — 高分辨率

工具目录

数据集和诊断

cityjson_import

对于由聊天应用投递到输入收件箱或放置在挂载目录中的文件，请使用此工具：

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

如果文件名未知，请调用 cityjson_list_imports。仅当恰好存在一个 JSON 文件时，省略 filename 才会自动导入。该工具在返回句柄之前会复制并验证源文件。

cityjson_import_text

仅当小型 CityJSON 文档已作为文本存在于应用工作流中时，才使用此工具：

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

内容在写入托管工作区之前会进行结构检查。它不适用于浏览器/聊天附件，因为完整文档需要通过 MCP 请求传输。cityjson_upload 作为已弃用的兼容别名保留。

cityjson_open

cityjson_open 仍可供高级客户端使用，这些客户端有意在允许的根目录内提供服务器可见的完整路径。常规收件箱和附件工作流应使用 cityjson_import。

cityjson_download

当容器未挂载主机目录时，使用此工具检索源数据集或转换后的数据集：

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

在 DATUM 中，主机直接流式传输不可变的工作区文件并显示下载按钮，因此大型结果不会经过模型上下文或 MCP JSON。独立的 MCP 客户端会收到内嵌的 application/json 资源；该内联路径默认有 25 MiB 的限制，由 CITYJSON_MCP_MAX_DOWNLOAD_BYTES 控制。

代表性结果：

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

句柄是指向文件的内存元数据；仅打开 CityJSON 文档并不会复制该文档本身。

检查与查询

cityjson_query 是让 LLM 检查大型模型的首选方式，无需将整个 CityJSON 文档送入模型上下文。

示例：

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

属性谓词运算符：

• eq

• neq

• gt

• gte

• lt

• lte

• contains

• in

包围盒过滤器为数据集 CRS 中的 [minX, minY, maxX, maxY]。对象包围盒根据对象引用的顶点以及存在时的 CityJSON transform 计算。

验证

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 — 高分辨率

何时使用哪个验证器

对于以下问题，请使用 cityjson_validate_schema：

• JSON 在语法上是否为有效的 CityJSON？

• 是否符合 CityJSON 模式？

• 父/子引用是否一致？

• 顶点索引是否存在？

• 语义/材质/纹理数组在结构上是否连贯？

• 扩展模式是否有效？

对于 MultiSurface、CompositeSurface、Solid、MultiSolid 和 CompositeSolid 图元的几何有效性以及相关的 CityJSON 特定几何检查，请使用 cityjson_validate_geometry。

对于常规的用户请求“验证此 CityJSON”，请使用 cityjson_validate。

示例：

{
  "dataset_id": "cj_4ad572e79331"
}

如果 cjval 警告报告存在重复或未使用的顶点，自然的修复循环是：

1. cityjson_clean_vertices

2. cityjson_validate_schema

3. 可选 cityjson_validate_geometry

转换与操作

本节中的所有工具均返回新的数据集句柄。

子集示例

包围盒内的建筑物：

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

特定对象：

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

除植被对象外的所有内容：

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

CRS 处理

仅当坐标已以该 CRS 表示且元数据缺失/错误时，才使用 cityjson_assign_crs。它不会转换坐标。

当坐标确实需要转换时，请使用 cityjson_reproject：

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

要获得可靠的重新投影，源模型需要具有可用的源 CRS。

导出与互操作

导出示例：

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

CityGML → CityJSON 示例：

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

CityJSON → CityGML 示例：

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

该包装器有意不自行设定 CityGML/CityJSON 目标版本选项。citygml-tools 支持 CityGML 1.0/2.0/3.0 和 CityJSON 1.0/1.1/2.0，但确切的目标版本 CLI 行为可能因上游版本而异；已安装后端的默认值仍然具有权威性。

数据库工具

连接对象：

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

导入：

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

子集导出：

{
  "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
}

该包装器拒绝除 SELECT 之外的 SQL、分号以及明显的修改性关键字。这是一个护栏，不是 SQL 安全边界：请使用仅具有该操作所需权限的数据库角色。对于导出，请使用无法修改数据的角色。

规范、模式与扩展知识

规范查询示例：

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

核心模式查询示例：

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

扩展发现示例：

{
  "query": "noise"
}

然后获取特定模式：

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

为什么这不依赖 cityjson/cj-mcp

cityjson/cj-mcp 对于规范章节检索很有用。此服务器需要更广泛的操作，因此知识适配器直接读取权威 CityJSON 规范/模式/扩展来源，并捆绑一个小的确定性 2.0.2 参考索引。这避免了第二个 MCP 进程和版本偏差故障模式。

未来的适配器可以将 cityjson_spec_read 委托给 cj-mcp，而无需更改公开的 MCP 工具名称。

推荐提示词 / 配方

这些提示词假定主机文件目录已配置为输入收件箱。代理使用文件名，并且永远不会在其自身代码环境中检查 /input。

修改前检查

使用 cityjson_import 导入 tile.city.json。告诉我 CityJSON 版本、CRS、按类型统计的 CityObject 数量、LoD、属性名称和扩展。不要修改任何内容。

预期工具：cityjson_import → cityjson_info。

验证与诊断

导入 tile.city.json，然后使用 cjval 和 val3dity 进行验证。仅使用 CityJSON 连接器工具。将 cjval 警告与错误分开，按错误代码对 val3dity 错误进行分组，识别受影响的 CityObject ID，并在错误涉及 CityJSON 结构规则时查阅 CityJSON 规范。如果验证报告超过工具输出限制，请创建不重叠的空间子集，验证每个子集，并汇总计数而不重复计数。不要修改原始文件。

预期工具：cityjson_import → cityjson_validate → 可选 cityjson_get_object / cityjson_spec_read。

安全清理循环

导入 tile.city.json，运行结构验证，如果唯一的结构警告是重复或未使用的顶点，则创建一个清理后的派生数据集，再次运行完整验证，并使用 cityjson_download 以 tile-clean.city.json 返回结果。切勿覆盖原始文件。

预期工具：cityjson_import → cityjson_validate_schema → cityjson_clean_vertices → cityjson_validate → cityjson_save。

空间提取

从收件箱文件 city.city.json 中，仅提取与 bbox [85000, 446000, 86000, 447000] 相交的 Building 和 BuildingPart 对象，保留 LoD 2.2，重投影到 EPSG:28992，验证结果，然后使用 cityjson_download 以 extract.city.json 返回。

预期工具：cityjson_import → cityjson_subset → cityjson_filter_lod → cityjson_reproject → cityjson_validate → cityjson_save。

CityGML 互操作性

将 /input/source.gml 转换为 CityJSON，检查生成的对象类型和 LoD，使用 cjval 和 val3dity 进行验证，并报告转换过程中可能丢失或规范化的任何信息。

预期工具：citygml_to_cityjson → cityjson_info → cityjson_validate，以及在有用时进行规范查询。

数据库工作流

导入收件箱文件 municipality.city.json，验证它，然后将其导入 PostgreSQL 主机 localhost、数据库 cityjson、模式 municipality。为 yearOfConstruction 添加属性索引。使用 MCP 进程环境中的数据库密码。

预期工具：cityjson_import → cityjson_validate_schema → cityjson_db_import。

扩展感知推理

此模型声明了 CityJSON noise 扩展。查找已注册的扩展文档/模式，解释它允许的附加属性，如果我提供本地扩展模式，则使用它验证模型。

预期工具：cityjson_info → cityjson_extensions_registry → cityjson_extension_schema → 可选 cityjson_validate_schema。

数据生命周期与不可变性

关键设计是：

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 将收件箱文件复制到托管工作区，验证它，并返回初始数据集 ID。

• cityjson_open 为高级工作流注册一个明确授权的服务器可见路径。

• cityjson_import_text 是小文档的备用方案；其已弃用的 cityjson_upload 别名不处理二进制附件。

• 转换操作要求后端在 CITYJSON_MCP_WORKSPACE 内写入新文件。

• 服务器打开生成的文件并为其分配一个新的随机 dataset_id。

• cityjson_save 是显式步骤，将所选状态复制到用户选择的目标位置。

这使得代理更容易比较验证前后的结果，并防止正常的转换调用静默覆盖原始源文件。

安全模型

此服务器在本地执行强大的地理空间程序。请将 MCP 服务器安装视为本地代码安装。

内置护栏：

1. 允许的根目录 — 主机路径操作必须位于 CITYJSON_MCP_ALLOWED_ROOTS、CITYJSON_MCP_INPUT 或托管工作区内。浏览器上传在输入目录内被分配随机化的安全文件名。

2. 无任意 shell 工具 — 没有 run_shell 命令或不受限制的 run_cjio MCP 工具。

3. 无 shell 插值 — 外部程序使用参数数组和 shell: false 调用。

4. 类型化工具模式 — Zod 限制类型、枚举、EPSG 整数、bbox 形状、数据库模式标识符等。

5. PostgreSQL 密码保留在环境中 — 数据库工具模式不包含密码字段。

6. 数据库导出 SQL 防护 — 仅接受不含分号或明显修改性关键字的单个 SELECT 字符串。仍应使用仅具有所需权限的数据库角色。

7. 命令超时/输出上限 — 子进程默认为 120 秒超时和受限的捕获输出。对于大型任务，请设置 CITYJSON_MCP_COMMAND_TIMEOUT_MS。

对于共享或生产环境，请在仅具有其实际所需的文件系统和数据库权限的 OS 账户/容器下运行 MCP。

Docker

随附的 docker/Dockerfile 安装：

• Node 运行时 + MCP 包依赖

• cjio

• cjdb

• cjval

• val3dity

• citygml-tools

大多数用户应拉取已发布的镜像：

docker pull yarroudh/cityjson-mcp:latest

对于本地源码构建，在构建其余部分之前缓存两个昂贵的编译阶段：

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 .

本地构建后运行 docker run --rm --entrypoint node cityjson-mcp /app/scripts/doctor.mjs 以验证所有五个可执行文件。

从 GitHub Actions 发布

.github/workflows/docker-publish.yml 中的工作流在本机运行器上构建 linux/amd64 和 linux/arm64 镜像，创建一个多平台清单，并将其推送到 yarroudh/cityjson-mcp。

在 Settings → Secrets and variables → Actions 下配置 GitHub 仓库：

• 变量 DOCKERHUB_USERNAME：yarroudh

• 密钥 DOCKERHUB_TOKEN：具有写入此仓库权限的 Docker Hub 访问令牌

从 Actions 选项卡手动运行工作流，或发布版本标签：

git tag v0.1.0
git push origin v0.1.0

版本标签发布 0.1.0、0.1 和 latest。BuildKit 缓存会为后续运行保留，因此未更改的 val3dity 和 cjval 层无需重新编译。

开发用 PostGIS：

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

参见 docker/README.md。

开发布局

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/

MCP 协议层使用官方 Model Context Protocol TypeScript 服务器 SDK 的稳定 v2 系列和 stdio 传输。

图表

所有 Mermaid 源文件存储在 diagrams/*.mmd 中。已检入的 PNG 文件由相同的图定义以 300-DPI Graphviz 输出 生成，尺寸在数千像素范围内，以便在文档/幻灯片中保持清晰。

重新生成它们：

python3 scripts/render_diagrams.py

渲染器支持本 README 使用的 Mermaid 流程图子集，并且需要 Graphviz dot 可执行文件。

当前 PNG 文件：

• diagrams/architecture.png

• diagrams/workflow.png

• diagrams/validation.png

• diagrams/client-setup.png

测试

原生测试不需要任何外部地理空间后端：

npm test

它们测试：

• CityJSON 解析和摘要生成

• 转换/反量化对象 bbox 计算

• 原生类型/bbox/属性查询

• 包含的示例 JSON

对每个 .mjs 源文件进行语法检查：

npm run check

外部适配器有意作为其官方 CLI 的薄包装器。对于部署环境，请添加固定到您部署的确切后端版本的集成测试。

已知限制 / v0.1 决策

• 原生的 cityjson_open 目前会将常规 CityJSON JSON 文件加载到内存中。对于极大的 CityJSONSeq 流，请使用后端工作流或添加流式适配器。

• 数据集句柄在 MCP 服务器进程的整个生命周期内有效；重启客户端/服务器会使旧的 dataset_id 值失效。重启后请重新打开源文件/已保存文件。

• 派生工作区文件不会自动删除。这是有意为之，以便实现可追溯性，但请定期清理工作区。

• cityjson_query 根据每个 CityObject 上显式存储的几何体计算边界框。它不会自动将所有子几何体合并到父级的边界框中。

• cityjson_spec_read、cityjson_schema_read 以及扩展注册表/模式工具需要出站网络访问才能访问规范的 CityJSON 端点。cityjson_spec_outline 可基于捆绑的索引工作。

• cityjson_to_citygml 有意将目标 CityGML 版本的选择交由已安装的 citygml-tools 默认值处理，而不是依赖未经核实的 CLI 标志。

• val3dity 是 GPL-3.0 软件；本项目以外部后端方式调用该可执行文件，并未将其捆绑在内。请针对您自身的分发/部署模式评估许可影响。

• 所提供的 Docker 基础镜像不包含 val3dity 或 citygml-tools。

上游参考

• CityJSON 规范：https://www.cityjson.org/specs/

• CityJSON 规范仓库：https://github.com/cityjson/specs

• CityJSON 扩展注册表：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

• 现有的仅限规范的 CityJSON MCP：https://github.com/cityjson/cj-mcp

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

• Cursor MCP 文档：https://cursor.com/docs/mcp

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

许可证

本仓库中的代码依据 MIT 许可证提供；请参阅 LICENSE。

外部后端仍是各自许可证下的独立软件。特别是，val3dity 为 GPL-3.0，citygml-tools 为 Apache-2.0，而 cjio/cjval/cjdb 拥有各自的上游许可证文件。本仓库中的任何内容均不会对这些项目重新授权。