CityJSON MCP

Локальный сервер Model Context Protocol (MCP) для реальной работы с CityJSON, а не только для чтения спецификации.

Он предоставляет MCP-клиентам, таким как Claude Desktop, Cursor и VS Code, стабильный CityJSON-ориентированный API инструментов, основанный на:

• cjio — манипуляции с CityJSON, фильтрация, операции с CRS, очистка, слияние и экспорт.

• cjval — официальная проверка синтаксиса, схемы и структуры CityJSON/CityJSONSeq.

• val3dity — проверка 3D-геометрической корректности примитивов CityJSON.

• citygml-tools — конвертация CityGML ↔ CityJSON.

• cjdb + PostgreSQL/PostGIS — постоянное хранение/импорт/экспорт CityJSON.

• Спецификация CityJSON 2.0.2, JSON-схемы и реестр расширений — живой канонический справочный доступ для агента.

Сервер предоставляет 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 — высокое разрешение

API, ориентированный на MCP, намеренно не предоставляет произвольные 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 также можно ввести в диалоговом окне Configure model приложения. Учётные данные из диалога хранятся только в памяти сервера для сессии браузера и никогда не возвращаются в браузер и не передаются MCP-инструменту.

MODEL_PROVIDER принимает anthropic или openai, потому что он выбирает протокол API, а не компанию, предоставляющую модель. anthropic использует Messages; openai использует совместимые с OpenAI Chat Completions и, следовательно, также поддерживает совместимые сервисы, такие как DeepSeek, через MODEL_BASE_URL.

Запустите полное приложение. Это поведение по умолчанию, поскольку образ содержит 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 отменяет эту проверку только для намеренной инспекционной разработки.

Автономные MCP-клиенты с полным Docker-рантаймом

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

Вывод должен сообщать OK для cjio, cjval, val3dity, citygml-tools и cjdb.

Настройка входной папки

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

Хост-каталог появляется как /input внутри Docker. Пользователи и агенты ссылаются только на имя файла:

Импортируй 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 автоматически загружает новые слои образа при необходимости после повторного выполнения docker pull yarroudh/cityjson-mcp:latest.

Для сборки из исходников закешируйте два медленных этапа компиляции перед сборкой остального образа:

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_to_cityjson, если ваш источник — CityGML.

citygml-tools

Официальный проект: https://github.com/ciitygml4j/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 требует PostgreSQL с PostGIS. Файл разработки compose включён в docker/docker-compose.postgis.yml.

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 обычно «ничего не делают» при прямом запуске, потому что ожидают MCP JSON-RPC сообщений на stdin. Вы всё равно можете подтвердить запуск с помощью:

npm run doctor
npm test

Затем настройте одного из MCP-клиентов ниже. Предоставленные шаблоны запускают полный Docker-образ. Участники могут заменить команду Docker на абсолютный путь к node src/index.mjs и установить переменные окружения выше.

Добавление в Claude Desktop

Локальные MCP-конфигурации Claude Desktop используют объект 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 нажмите +, откройте Connectors, включите cityjson и разрешите его инструменты в разделе Tool access. Коннектор доступен только в чатах, где он включён. /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. Скопируйте его в .mcp.json в проекте, где вы запускаете Claude Code:

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

Перезапустите Claude Code или переподключите его MCP-серверы после изменения конфигурации.

Добавление в Cursor

Cursor поддерживает локальные stdio MCP-серверы в mcp.json.

Шаблон включён в 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 для этой модели, затем объясни каждую ошибку val3dity, используя спецификацию CityJSON, где это уместно.

Документация 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. Если опустить filename, импорт выполняется автоматически только при наличии ровно одного JSON-файла. Инструмент копирует и проверяет источник перед возвратом дескриптора.

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 МиБ и управляется переменной 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

Фильтр по ограничивающему прямоугольнику — это [minX, minY, maxX, maxY] в системе координат набора данных. Ограничивающие прямоугольники объектов вычисляются по указанным вершинам объекта и transform из CityJSON, если он присутствует.

Проверка

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?

• Согласованы ли ссылки родитель/потомок?

• Существуют ли индексы вершин?

• Структурно согласованы ли массивы семантики/материалов/текстур?

• Корректны ли схемы расширений?

Используйте cityjson_validate_geometry для проверки геометрической корректности примитивов MultiSurface, CompositeSurface, Solid, MultiSolid и CompositeSolid, а также связанных специфических для CityJSON геометрических проверок.

Для обычного запроса пользователя «проверьте этот 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
}

Работа с системой координат

Используйте cityjson_assign_crs только тогда, когда координаты уже выражены в нужной системе координат, а метаданные отсутствуют/неверны. Этот инструмент не преобразует координаты.

Используйте cityjson_reproject, когда координаты действительно нужно преобразовать:

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

Для надёжного перепроецирования исходная модель должна иметь пригодную исходную систему координат.

Экспорт и интероперабельность

Пример экспорта:

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

Обёртка отклоняет SQL, отличный от SELECT, точки с запятой и очевидные изменяющие ключевые слова. Это защитное ограничение, а не граница безопасности 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 в собственном окружении кода.

Проверка перед изменением

Импортируй tile.city.json с помощью cityjson_import. Сообщи мне версию CityJSON, СК, количество CityObject по типам, LoD, имена атрибутов и расширения. Ничего не изменяй.

Ожидаемые инструменты: cityjson_import → cityjson_info.

Проверка и диагностика

Импортируй tile.city.json, затем проверь его с помощью cjval и val3dity. Используй только инструменты коннектора CityJSON. Отдели предупреждения cjval от ошибок, сгруппируй ошибки val3dity по кодам ошибок, определи затронутые идентификаторы CityObject и обратись к спецификации 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 во входной папке извлеки только объекты Building и BuildingPart, пересекающие bbox [85000, 446000, 86000, 447000], сохрани 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 копирует файл из входной папки в управляемое рабочее пространство, проверяет его и возвращает начальный идентификатор набора данных.

• cityjson_open регистрирует явно авторизованный видимый сервером путь для расширенных рабочих процессов.

• cityjson_import_text — это запасной вариант для небольших документов; его устаревший псевдоним cityjson_upload не обрабатывает бинарные вложения.

• Преобразование просит бэкенд записать новый файл внутри CITYJSON_MCP_WORKSPACE.

• Сервер открывает созданный файл и присваивает ему новый случайный dataset_id.

• cityjson_save — это явный шаг, который копирует выбранное состояние в место назначения, выбранное пользователем.

Это значительно упрощает агенту сравнение результатов проверки до/после и предотвращает молчаливую перезапись исходного файла обычными вызовами преобразования.

Модель безопасности

Этот сервер выполняет мощные геопространственные программы локально. Относитесь к установке сервера MCP как к установке локального кода.

Встроенные защитные механизмы:

1. Разрешённые корни — операции с путями хоста должны находиться в пределах CITYJSON_MCP_ALLOWED_ROOTS, CITYJSON_MCP_INPUT или управляемого рабочего пространства. Загрузкам из браузера присваиваются случайные безопасные имена файлов внутри входного каталога.

2. Нет произвольного инструмента оболочки — нет команды run_shell или неограниченного инструмента MCP run_cjio.

3. Нет интерполяции оболочки — внешние программы вызываются с массивами аргументов и shell: false.

4. Типизированные схемы инструментов — Zod ограничивает типы, перечисления, целые числа EPSG, формы bbox, идентификаторы схем базы данных и т. д.

5. Пароль PostgreSQL остаётся в окружении — схемы инструментов базы данных не содержат поля пароля.

6. Защита SQL экспорта БД — принимаются только одиночные строки SELECT без точек с запятой или очевидных изменяющих ключевых слов. Всё равно используйте роль базы данных только с необходимыми правами.

7. Тайм-аут/ограничение вывода команд — для подпроцессов по умолчанию установлен тайм-аут 120 секунд и ограниченный захваченный вывод. Установите CITYJSON_MCP_COMMAND_TIMEOUT_MS для больших задач.

Для общих или производственных сред запускайте 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.

Настройте репозиторий GitHub в разделе Settings → Secrets and variables → Actions:

• Переменная 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 использует стабильную линию v2 официального TypeScript SDK сервера Model Context Protocol и транспорт stdio.

Диаграммы

Все исходники Mermaid хранятся в diagrams/*.mmd. Проверенные PNG-файлы генерируются из тех же определений графов при выводе Graphviz с разрешением 300 DPI, с размерами в диапазоне нескольких тысяч пикселей, чтобы они оставались чёткими в документах/слайдах.

Перегенерируйте их:

python3 scripts/render_diagrams.py

Рендерер поддерживает подмножество блок-схем Mermaid, используемое в этом README, и требует исполняемый файл 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 в настоящее время загружает обычный JSON-файл CityJSON в память. Для чрезвычайно больших потоков CityJSONSeq используйте серверные рабочие процессы или добавьте потоковый адаптер.

• Дескрипторы наборов данных существуют в течение всего времени жизни процесса MCP-сервера; перезапуск клиента/сервера делает старые значения dataset_id недействительными. После перезапуска повторно открывайте исходные/сохранённые файлы.

• Производные файлы рабочей области не удаляются автоматически. Это сделано намеренно для прослеживаемости, но периодически очищайте рабочую область.

• cityjson_query вычисляет ограничивающие прямоугольники (bbox) на основе геометрии, явно хранящейся на каждом CityObject. Он не объединяет автоматически всю дочернюю геометрию в bbox родительского объекта.

• 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 имеют собственные файлы лицензий вышестоящих проектов. Ничто в этом репозитории не перелицензирует эти проекты.