plateau-creative-mcp

_{真实的涩谷街区——从 PLATEAU 加载、编辑，并由 export_glb 工具导出为一个 .glb 文件，此处使用 three.js 渲染。与你的大模型移交给 Blender / Unity / Unreal 的几何体相同。数据 © Project PLATEAU / MLIT（CC BY 4.0）。}

此服务提供工具。工作流编排由你的大模型负责——让 Claude / Cursor / 任意 MCP 客户端连接此服务，同时连接 Blender MCP / Unity MCP / Unreal MCP，即可由它组合工作流。

PLATEAU 有官方 MCP 服务用于数据访问（目录、规范、CityGML、属性）。本项目补上缺失的创作、场景编辑和 DCC 导出环节：加载东京的一个街区，删除所有摩天大楼，将一片街区缩放至 3 倍高度，并生成可用于 Blender / Unity / Unreal 的 .glb 文件——所有操作都由工具调用驱动。

flowchart LR
  CLIENT["Claude / Cursor<br/>(any MCP client)"] -->|tool calls| MCP["plateau-creative-mcp"]
  MCP -->|download_area| DATA["plateau-bridge<br/>artifact index + bundles"]
  MCP -->|"load → filter → edit"| SCENE["scene_id<br/>(in-memory)"]
  MCP -->|export_glb| OUT[".glb + LICENSE.txt"]
  OUT --> DCC["Blender / Unity / Unreal"]

状态

**v0.1.0——首次公开发布。**提供 10 个 MCP 工具（包括按需下载资源——无需克隆数据），支持多边形占地挤出并合并网格，可导出不超过 1 km² 的单个 GLB（约 40% gltf-transform 压缩），更大区域则提供 scene_manifest 3D Tiles 回退方案；支持三种数据访问模式（TS+duckdb 资源 / Python 子进程 / 通过 JSON-RPC 接入上游 MCP）、Overpass POI 关联，以及可选的 BlenderMCP 跨 MCP 桥接。通过 MCP 实现厂商中立——Claude、Cursor 和任意客户端均可使用。

工具

工具	用途
download_area	从 plateau-bridge 构件索引获取并缓存预构建的城市数据包（解析 slug、下载 .tar.zst、验证 sha256、提取 buildings.parquet 和 manifest.json），这样无需克隆数据流水线即可使用 load_area。
load_area	将城市、bbox 和 LOD 加载到新的 scene_id。
filter_buildings	按高度 / 年份 / 用途 / 分区 / 洪水深度查询场景中的 building_uid[]。
delete_buildings	反事实编辑——标记要移除的建筑。
extrude_buildings	按比例缩放建筑高度。
compose_scene	设置渲染提示（时间、天气、摄像机）。
export_glb	输出 .glb（single_glb，采用 parquet 中的真实几何数据）或引用 3D Tiles 的 scene_manifest。scene_manifest 需要使用本地构建的 3D Tiles 来丰富内容；下载的城市会生成不含瓦片的清单（包含编辑内容、bbox 和署名信息），并附带 tileset_note。
link_buildings_to_pois	将建筑与附近的 OSM POI（Overpass）关联。
get_attribution	获取场景的完整数据集 / 许可证 / URL 元数据。
render_via_blender	将场景导出为 GLB，并可选择通过 JSON-RPC 连接到兼容 BlenderMCP 的 HTTP MCP 服务。试运行会返回建议的跨 MCP 调用序列。

当 PLATEAU_UPSTREAM_ENABLED=true 时，服务还会暴露 13 个由官方 Project PLATEAU MCP 服务代理的工具：plateau_spec_outline、plateau_spec_read、plateau_get_metadata、plateau_search_areas、plateau_get_area、plateau_search_datasets、plateau_get_dataset、plateau_list_dataset_types、plateau_citygml_get_attributes、plateau_citygml_get_features、plateau_citygml_get_geoid_height、plateau_get_citygml_files、plateau_explain_spatial_id。大模型客户端会在单个目录中看到 23 个工具，无需连接两个独立的 MCP 服务。

每个工具都会返回 { result, attribution_metadata }。export_glb 会将 asset.extras.attribution 写入 GLB，并在旁边生成 LICENSE.txt。任何衍生视频、图像或资产都必须保留该署名信息。

快速开始

npm install
npm run build

有两种方式可以准备好城市数据。

选项 A — 零配置（推荐）

完全无需克隆数据流水线。服务开箱即用，会读取公开的 plateau-bridge 构件索引，因此 download_area 无需配置即可使用——它会获取城市的预构建数据包、验证其 sha256，并在本地缓存：

export PLATEAU_AUTO_DOWNLOAD=true     # load_area auto-fetches a missing city (optional)
export PLATEAU_OUTPUT_DIR=./out
npx @yodolabs/plateau-creative-mcp             # stdio MCP server

调用一次 download_area(city="shibuya")（或者设置 PLATEAU_AUTO_DOWNLOAD=true，然后直接调用 load_area，它会先获取缺失的城市数据）。只会提取 buildings.parquet 和 manifest.json；数据包缓存在 PLATEAU_ARTIFACT_DIR 下（默认为 ~/.cache/plateau-creative-mcp/artifacts），因此每个城市只需下载一次。将 PLATEAU_ARTIFACT_INDEX_URL 指向其他索引即可使用自己的镜像。

下载的数据包不包含 3D Tiles（每个城市的数据量可达数 GB）。所有功能都可基于 parquet 使用——load_area、所有编辑操作，以及 export_glb 的 single_glb（真实几何数据，≤ 1 km² / ≤ 5000 栋建筑）。只有下载城市的 scene_manifest 导出会失去瓦片引用（仍会输出编辑列表、bbox 和署名信息，并附带 tileset_note，建议缩小范围改用 single_glb 或运行本地构建）。要导出较大区域的完整几何数据，请使用选项 B 进行本地构建。

对于 Claude Desktop，请添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "plateau-creative": {
      "command": "npx",
      "args": ["-y", "@yodolabs/plateau-creative-mcp"],
      "env": {
        "PLATEAU_AUTO_DOWNLOAD": "true",
        "PLATEAU_OUTPUT_DIR": "/Users/you/plateau-out"
      }
    }
  }
}

选项 B — 使用自己的构件

如果你已有 plateau-bridge 生成的 out_<city>/ 输出目录，可直接指向它们：

export PLATEAU_ARTIFACT_DIR=/path/to/plateau-bridge
export PLATEAU_OUTPUT_DIR=./out
npx @yodolabs/plateau-creative-mcp        # stdio MCP server

{
  "mcpServers": {
    "plateau-creative": {
      "command": "npx",
      "args": ["-y", "@yodolabs/plateau-creative-mcp"],
      "env": {
        "PLATEAU_ARTIFACT_DIR": "/path/to/plateau-bridge",
        "PLATEAU_OUTPUT_DIR": "/Users/you/plateau-out"
      }
    }
  }
}

不使用 MCP 客户端进行冒烟测试：

npx tsx scripts/smoke-load-area.ts

示例工作流

1. 赛博朋克涩谷飞行漫游（跨 MCP）

load_area(city="shibuya", bbox=[139.6975,35.6555,139.7045,35.6605], lod=2)
  -> compose_scene(time="19:30", weather="rain")
  -> export_glb()              # to ./out/<scene>_v3.glb
=> BlenderMCP: import_glb + cyberpunk shader + render

flowchart LR
  LLM(("LLM")) --> A["plateau-creative-mcp<br/>load · edit · export_glb"]
  LLM --> B["Blender MCP<br/>import · shade · render"]
  A -->|".glb + sidecar"| B

2. 没有摩天大楼的东京

load_area(...)
  -> filter_buildings({height_min: 100})
  -> delete_buildings(filter={height_min: 100})
  -> export_glb()

3. 办公楼草稿（要求制品中包含分区字段）

load_area(...)
  -> filter_buildings({zoning_use: ["commercial"], far_max_min: 400})
=> SketchUp MCP: design a new building inside those parcels

架构

src/
  server/   MCP protocol entry, tool registry, unified envelope
  tools/    10 MCP tool handlers
  schemas/  Zod schemas + JSON Schema export
  scene/    scene_id LRU + lock + optional disk persistence
  data/     Artifact (duckdb) access layer + on-demand bundle downloader
  export/   three.js scene builder + GLTFExporter + manifest fallback
  attribution/  Envelope wrapping, attribution merge
  rateLimit/    Token bucket per (client, tool)
  errors/   Stable error codes + AppError
  config/   Env-driven config
  utils/    ids, bbox, paths, logger

• scene_id 是唯一的共享状态。所有变更／导出工具都必须引用它。ID 由服务端生成，格式为 ULID。
• building_uid 是唯一的规范引用。不提供 gml_id 或批次索引作为替代项。
• export_glb 硬性限制：single_glb 的边界框面积必须 ≤ 1 km²，且建筑数量必须 ≤ 5000。超出限制的场景会返回 EXPORT_LIMIT_EXCEEDED，并建议切换到 scene_manifest。
• 归属信息由执行器层包装——任何处理程序都无法返回不含归属信息的结果。

配置

环境变量	默认值	含义
PLATEAU_ARTIFACT_DIR	~/.cache/plateau-creative-mcp/artifacts	包含 out_<city>/buildings.parquet 的目录。默认为缓存目录（download_area 的写入位置）；将其设为指向现有的 plateau-bridge 检出目录。
PLATEAU_ARTIFACT_INDEX_URL	plateau-bridge distribution/index.json	缓存索引（JSON），列出每个城市的捆绑包 URL 和 sha256。默认为公共镜像；可覆盖以使用自己的镜像。
PLATEAU_ARTIFACT_DOWNLOAD_TIMEOUT_MS	300000	每次下载的超时时间，以毫秒为单位（5s–30min）。
PLATEAU_AUTO_DOWNLOAD	false	设为 true 时，load_area 会在加载前从索引自动获取缺失的城市数据。
PLATEAU_OUTPUT_DIR	./out	写入 .glb / LICENSE.txt / 清单的位置。
PLATEAU_DATA_MODE	artifact	artifact（TS + duckdb）或 subprocess（Python 助手脚本）。
PLATEAU_PYTHON_BIN	python3	subprocess 模式使用的 Python 解释器（必须已安装 duckdb）。
PLATEAU_SUBPROCESS_SCRIPT	捆绑的 python/plateau_query.py	覆盖 JSON-stdio 助手脚本的路径。
PLATEAU_SCENE_DIR	./.scene-store	启用场景持久化时使用的磁盘目录。
PLATEAU_PERSIST_SCENES	false	设为 true 时，在调用之间将场景序列化到磁盘。
PLATEAU_MAX_SCENES	64	内存中场景的 LRU 上限。
PLATEAU_SCENE_TTL_MS	3600000	场景的 TTL，以毫秒为单位。
OSM_OVERPASS_URL	未设置	设置后可启用 link_buildings_to_pois（例如 https://overpass-api.de/api/interpreter）。
OSM_OVERPASS_TIMEOUT_MS	25000	Overpass 请求超时时间。
PLATEAU_UPSTREAM_ENABLED	false	设为 true 时，会注册 13 个代理到托管版 PLATEAU MCP 的官方 plateau_* 工具。
OFFICIAL_PLATEAU_MCP_URL	托管版默认值	覆盖官方 PLATEAU MCP 端点（很少需要）。

请参阅 .env.example 获取可直接复制粘贴的模板。

建筑轮廓几何体与方盒回退方案

默认启用通过 DuckDB spatial 扩展进行多边形拉伸；首次运行时会自动安装该扩展。如果安装／加载失败（CI 离线或环境受限），导出器会平稳回退，为每栋建筑生成以质心为锚点的 12 m × 12 m 方盒。若启用高精度路径，load_area 的响应中的 available_attributes 会包含 footprint_polygon。

网格合并与旁路索引

single_glb 导出会将每栋建筑合并到一个 BufferGeometry 中——只需一次绘制调用，并大幅减少 GLB JSON 开销。为保留每栋建筑的身份信息，供下游编辑工具使用，每次导出都会在 GLB 旁边写入一个旁路文件 <basename>.buildings.json：

{
  "scene_id": "scene_01...",
  "version": 4,
  "merged": true,
  "total_triangles": 73482,
  "ranges": {
    "<building_uid>": [{"triangle_start": 0, "triangle_count": 18}]
  }
}

scene_manifest 模式

当导出内容超出 single-GLB 限制（1 km² / 5000 栋建筑）时，可以请求 mode: "scene_manifest"。该清单会关联对应的 3D Tiles tileset.json，并列出边界区域与场景边界框相交的叶子瓦片内容 URI——下游使用者可以按需延迟加载所需瓦片：

{
  "scene_id": "scene_01...",
  "mode": "scene_manifest",
  "bbox": [139.69, 35.65, 139.72, 35.67],
  "tileset": "/abs/path/out_shibuya/3dtiles/tileset.json",
  "tileset_available": true,
  "tiles": [
    {
      "url": "/abs/path/out_shibuya/3dtiles/15/29096/4943_bldg_Building.glb",
      "relative_uri": "15/29096/4943_bldg_Building.glb",
      "bbox": [139.6984, 35.6577, 139.7060, 35.6644],
      "min_height_m": 39.3,
      "max_height_m": 332.3
    }
  ],
  "edits": { "deleted_building_uids": [], "extrusions": [] },
  "attribution": { "license": "CC BY 4.0" }
}

3D Tiles 由本地构建生成，不包含在按需下载的捆绑包中。对于已下载的城市，scene_manifest 会返回不含瓦片的清单（包含编辑内容、边界框和归属信息），并附带 tileset_note。

POI 关联

link_buildings_to_pois 需要设置 OSM_OVERPASS_URL。设置后，该工具会向 Overpass 发送 POST 请求，查询场景边界框内 amenity / shop / office / tourism / leisure 节点，然后将每个有名称的 POI 与 max_distance_m 范围内最近的建筑质心进行匹配。ODbL 署名信息会自动合并到返回的封装中。

有意不在范围内的内容

• export_3dgs — Gaussian-splat 往返转换属于未来工作。
• export_usd — 这是一个独立的 Isaac Sim 项目。
• simulate_earthquake / simulate_flood — 这是独立的风险分析工作。
• 通用 OSM 查询 — 属于 OSM-MCP 的范围。
• 跨 MCP 自动编排 — 由你的 LLM 负责。

署名与许可

• 软件： MIT（本仓库）。
• 数据： PLATEAU 采用 CC BY 4.0（© Project PLATEAU / MLIT）。OSM POI 采用 ODbL 1.0。
• 每个工具响应都包含 attribution_metadata。export_glb 会将其注入 asset.extras.attribution，并在 GLB 旁写入一个 LICENSE.txt。请将该文件与 GLB 一同保留，并在任何衍生视频 / 截图中注明 PLATEAU。

GLB 压缩

在 export_glb 上设置 options.compress: true，即可应用 gltf-transform 流水线（去重 → 焊接 → 剪枝 → 量化）。来自 0.4 km² 涩谷区域（507 栋建筑、138k 个三角形）的实际数据：9.94 MB → 6.05 MB（缩小约 40%），无可感知的损失。输出采用标准的 KHR_mesh_quantization 扩展——Blender、Unity、Unreal 和 three.js 均可原生解码。

与上游 MCP 服务通信

JsonRpcMcpClient 是一个精简的 MCP-over-HTTP 客户端（tools/list + tools/call），作为上游集成的构建模块提供。

OfficialPlateauMcpClient 是 官方 PLATEAU MCP 服务（托管于 https://api.plateauview.mlit.go.jp/mcp）的类型化封装。它涵盖全部 13 个上游工具：

• 规范： specOutline、specRead
• 目录： getMetadata、searchAreas、getArea、searchDatasets、getDataset、listDatasetTypes
• CityGML： citygmlGetAttributes、citygmlGetFeatures、citygmlGetGeoidHeight、getCityGmlFiles
• 辅助工具： explainSpatialId

import { OfficialPlateauMcpClient } from "@yodolabs/plateau-creative-mcp";

const upstream = new OfficialPlateauMcpClient();
const meta = await upstream.getMetadata();
const datasets = await upstream.searchDatasets({ area_codes: ["13113"], year: 2023 });

响应结构使用 [k: string]: unknown 索引签名，因为上游规范仍在演进——如果需要严格类型，请在调用处进行验证。

示例

可复现的工作流配方位于 examples/——Claude Desktop 提示词（examples/claude-prompts.md）、Cursor .cursorrules（examples/cursor-rules.md）、展示合并 GLB 与旁置文件交接的 Blender Python 代码片段（examples/blender-mcp-handoff.py），以及完整的赛博朋克涩谷演练（examples/cyberpunk-shibuya.md）。

贡献

欢迎提交问题和 PR——请参阅 CONTRIBUTING.md。提交 PR 前请运行 npm run lint && npm run typecheck && npm test。

包含内容

10 个自有 MCP 工具 + 来自官方 PLATEAU MCP 的 13 个代理工具（当 PLATEAU_UPSTREAM_ENABLED=true 时，合并为包含 23 个工具的目录）；按需下载制品（download_area + 可选的 load_area 自动获取），无需克隆数据；多边形占地轮廓拉伸（DuckDB spatial），并提供盒体回退方案；网格合并 + 旁置身份索引；GLB 压缩（缩小约 40%）；支持 3D Tiles 瓦片增强的 scene_manifest 模式；Overpass POI 关联；三种数据访问模式（TS+duckdb 制品 / Python 子进程 / 上游 MCP-over-HTTP）；以及一个由允许列表控制、可连接到 BlenderMCP 兼容服务的跨 MCP 桥接器。

---