CityJSON MCP

CityJSONを実際に操作するためのローカルなModel Context Protocol (MCP)サーバーであり、仕様を読むだけのものではありません。

Claude Desktop、Cursor、VS CodeなどのMCPクライアントに、以下を基盤とした安定したCityJSON指向のツールAPIを提供します。

• cjio — CityJSONの操作、フィルタリング、CRS操作、クリーンアップ、マージ、エクスポート。

• cjval — 公式のCityJSON/CityJSONSeq構文、スキーマ、構造検証。

• val3dity — CityJSONプリミティブの3D幾何学的妥当性チェック。

• 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をダウンロード — 高解像度

MCP向けAPIは、run_cjio("...")のような任意のシェルコマンドを意図的に公開しません。各MCPツールには型付き入力スキーマがあります。コマンドはspawn(..., { shell: false })で呼び出され、エージェント向けの契約を安定させ、シェル文字列のインターポーレーションを回避します。

典型的なエージェントワークフロー

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から読み取ります。それ以外の場合、アプリケーションはモデル設定ダイアログを開きます。

5つの実行可能ファイルがすべてホストにインストールされている開発環境では、npm run chat:hostを使用します。ホストモードはバックエンドの準備完了チェックを実行し、機能しないツールボックスを宣伝することを拒否します。CHAT_ALLOW_PARTIAL_BACKENDS=trueは、意図的な検査専用開発の場合にのみそのチェックを上書きします。

完全なDockerランタイムを使用したスタンドアロンMCPクライアント

DockerイメージにはMCPサーバーと5つのバックエンドすべてが含まれています。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は必要に応じて新しいイメージレイヤーを自動的にプルします。

ソースからビルドするには、残りのイメージをビルドする前に、2つの遅いコンパイラステージをキャッシュします。

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

後のレイヤーが失敗した場合、最終コマンドを再実行すると、完了したval3dityおよびcjvalレイヤーが再利用され、最初からコンパイルされません。

オプション: Dockerなしで実行

以下のセクションは、完全なDockerイメージの代わりにnode src/index.mjsを直接実行する場合にのみ必要です。

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が必要です。開発用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の場合、MCP引数に置く代わりに、PostgreSQLパスワードをプロセス環境に設定します。

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チャットで、**+**をクリックし、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にあります。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は、トップレベルのキーがserversであるmcp.jsonを使用します。

テンプレートは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ファイルがちょうど1つ存在する場合にのみ自動的にインポートされる。このツールは、ハンドルを返す前にソースをコピーして検証する。

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 リソースを受け取る。このインラインパスは、デフォルトで CITYJSON_MCP_MAX_DOWNLOAD_BYTES によって制御される25 MiBの制限がある。

代表的な結果:

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

ハンドルはファイルを指すインメモリのメタデータであり、CityJSONドキュメント自体は開くだけでコピーされるわけではない。

検査とクエリ

cityjson_query は、CityJSONドキュメント全体をモデルコンテキストに送信せずに、LLMが大きなモデルを検査できるようにするための推奨方法である。

例:

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

bboxフィルターは、データセットの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

変換と操作

このセクションのすべてのツールは、新しいデータセットハンドル を返す。

サブセットの例

bbox内の建物:

{
  "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の処理

cityjson_assign_crs は、座標がすでに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リファレンスインデックスをバンドルします。これにより、2番目のMCPプロセスとバージョンずれの障害モードを回避します。

将来のアダプターは、公開されているMCPツール名を変更せずにcityjson_spec_readをcj-mcpに委任できる可能性があります。

推奨プロンプト/レシピ

これらのプロンプトは、ホストファイルディレクトリが入力インボックスとして設定されていることを前提としています。エージェントはファイル名を使用し、自身のコード環境で/inputをチェックしません。

変更前の検査

tile.city.jsonをcityjson_importでインポートしてください。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. 任意のシェルツールなし — run_shellコマンドや無制限のrun_cjio MCPツールはありません。

3. シェル補間なし — 外部プログラムは引数配列とshell: falseで呼び出されます。

4. 型付きツールスキーマ — Zodが型、列挙型、EPSG整数、bbox形状、データベーススキーマ識別子などを制限します。

5. PostgreSQLパスワードは環境に保持 — データベースツールスキーマにはパスワードフィールドがありません。

6. DBエクスポート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

ローカルソースビルドの場合は、残りをビルドする前に2つの高コストなコンパイラステージをキャッシュしてください:

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を実行して5つの実行可能ファイルすべてを検証してください。

GitHub Actionsからの公開

.github/workflows/docker-publish.ymlのワークフローは、ネイティブランナーでlinux/amd64とlinux/arm64イメージをビルドし、1つのマルチプラットフォームマニフェストを作成して、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プロトコルレイヤーは、公式の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 に明示的に格納されたジオメトリから bbox を計算します。子ジオメトリを親の bbox に自動的に統合することはありません。

• cityjson_spec_read、cityjson_schema_read、および拡張機能レジストリ/スキーマツールは、正規の CityJSON エンドポイントへのアウトバウンドネットワークアクセスを必要とします。cityjson_spec_outline はバンドルされたインデックスから動作します。

• cityjson_to_citygml は、検証されていない CLI フラグに依存するのではなく、意図的にターゲットの CityGML バージョン選択をインストール済みの citygml-tools のデフォルトに委ねます。

• val3dity は GPL-3.0 ソフトウェアです。このプロジェクトは実行可能ファイルを外部バックエンドとして呼び出すものであり、ベンダリングは行いません。ご自身の配布/デプロイモデルにおけるライセンスの影響を確認してください。

• 提供される Docker ベースイメージには val3dity も citygml-tools も含まれていません。

アップストリーム参照

• CityJSON 仕様: https://www.cityjson.org/specs/

• CityJSON 仕様リポジトリ: https://github.com/cityjson/specs

• CityJSON Extensions レジストリ: 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 はそれぞれ独自のアップストリームライセンスファイルを持っています。このリポジトリ内のいかなるものも、それらのプロジェクトを再ライセンスするものではありません。