三维 GIS Agent 的一次失败，可能发生在模型尚未调用 flyTo、加载瓦片或绘制多边形之前：客户端在发现工具时就拒绝整个目录。cesium-mcp-contracts 0.6.1 的官方发布修复了一个典型互操作问题。项目原有的坐标元组 schema 使用现代 JSON Schema 的 prefixItems，但 VS Code 等严格 MCP 客户端还要求每个 type: array 都显式拥有 items。补丁为所有对外声明的数组加上 items，同时保留元组约束，并用递归测试审计 61 个浏览器安全工具的输入 schema。

这不是一个只属于 JavaScript 的格式细节。三维 GIS 工具会传入坐标序列、轨迹、边界框、GeoJSON 坐标和 CZML packet 数组；若工具目录不能被客户端加载，模型无法到达任何地理操作。把 schema 当成发布工件并在多客户端上验收，才能让“工具可发现”成为可复现的合同。

可核查事实

  • cesium-mcp-contracts 0.6.1 于 2026 年 8 月 18 日发布；Release 将其标为 patch change。

  • Release 说明为每个 advertised input array schema 增加 items，目标是兼容 VS Code 和其他严格 MCP client，同时保留通过 prefixItems 表达的 tuple constraints。

  • 关联 PR #37 的标题是“Fix strict MCP client validation for array schemas”，于 2026 年 8 月 18 日合并；该 PR 修改 4 个文件，增加 31 行、删除 1 行。

  • PR 说明根因是 VS Code 的 MCP tool validator 会拒绝没有显式 items 的 type: array schema；虽然若干坐标元组使用有效的 prefixItems，严格客户端仍会在任何模型或浏览器命令运行前拒绝工具目录。

  • PR 将 measure.positions 标为最先报告的路径，并指出同一兼容缺口影响 13 个嵌套 array 位置。

  • PR 说明修复影响 measure、polyline、polygon、trajectory、bounding box、GeoJSON coordinates 与 CZML packets 的工具发现。

  • PR 为 inline CZML arrays 写明 object packets 的描述，并加入递归 regression test；修复前审计发现 13 个缺少 items 的条目，修复后为 0。

  • PR 报告执行了 npm test（27 个文件、350 个测试）、typecheck、lint、contracts test、MCP conformance 28/28，以及真实 Viewer 的 packed e2e 测试。

这些是项目对自身版本的发布和测试证据。它们不证明每一个 MCP 客户端会以相同方式解释 JSON Schema，却足以说明工具 schema 需要和运行代码一样进入兼容性回归。

核心机制

工具调用在执行之前有一道发现门。服务把名称、说明和 input schema 公告给客户端；客户端据此验证工具、构建表单或让模型生成结构化参数。若 validator 在这一门拒绝一个嵌套数组，后端命令本身即使完全正确也不会被到达。对于 Cesium 这类 3D GIS 工具，数组既可能表示“允许任意多个对象”，也可能表示“固定长度且各元素语义不同的坐标元组”。两种约束必须同时表达。

prefixItems 适合描述 tuple 的前几个位置，例如经度、纬度和高度各自应满足的类型或范围；items 则表达数组后续元素或通用元素的规则。此版本的补丁没有用宽松 schema 替换 tuple，而是在每个 advertised array 上补齐 items 并保留 prefixItems。实际团队应将这理解为双重验收：既确认严格 client 能发现工具，也确认 client 生成的坐标数组没有因兼容修复失去长度、类型或单位约束。

GIS 场景

假设一个浏览器中的三维应急态势图向 Agent 暴露测量、绘线、绘面、轨迹和加载 GeoJSON 的工具。用户要求“沿河道画一条撤离路线，再量出与水位站的距离”。这条请求会经过多层数组：路线坐标、面边界、measure positions 或 GeoJSON 的嵌套 coordinates。若目录加载失败，前端不应悄悄退回成自然语言回答；应记录 tool_discovery_failed、客户端名称和 schema 版本，并明确提示可用能力未建立。

目录通过验证后，仍不能把 schema 合格等同于空间结果合格。输入 schema 应标记坐标顺序、CRS 假设、允许的高度单位、最少点数、最大点数和 AOI 上限；服务执行后再验证 Viewer 中实际产生的实体、相机范围或距离单位。这样可以区分两类故障：一类是客户端在发现层不接受 JSON Schema，另一类是工具已运行但经纬度顺序、地形高度或数据服务参数错误。

技术路径

将工具定义作为可版本化工件发布。每次改动 contracts 时，导出实际会被 MCP server 或 WebMCP adapter 公告的完整 schema manifest；对每个 type: array 递归检查是否存在 items，并针对使用 prefixItems 的坐标元组验证长度、元素类型和额外元素策略。测试不能只读取 TypeScript 类型，因为最终被客户端消费的是序列化后的 JSON Schema。

建立客户端矩阵，至少覆盖团队实际使用的 IDE/桌面 MCP host、浏览器 adapter 和独立协议检查器。每个环境运行“列出工具—选择含数组参数的工具—提交合法最小输入—提交非法长度、非法类型和过大数组”的回归。结果应记录 client 版本、schema manifest hash、工具名、错误类别与响应摘要。发现层失败要阻断发布；执行层失败则进入功能回归，避免把协议兼容与 3D 渲染问题混为一谈。

对 GeoJSON 与 CZML 等大数组还要设置资源边界。schema 可约束基本结构，服务端仍要限制顶点数、payload 字节、几何有效性、坐标范围和请求频率。对于超过前端即时渲染预算的轨迹或面，返回可追踪的异步任务，而不是让 Agent 反复重试同一个巨型工具调用。

风险边界

PR #37 的 13 个位置和 61 个浏览器安全工具属于该仓库当时的实现范围，不能外推到任意 Cesium 插件或 MCP server。不同 validator 对 JSON Schema draft、prefixItems、items 和未知关键字的支持仍可能不同。目录可发现也不意味着工具有权访问影像、地形、Ion token、私有图层或生产实体；认证、授权、输入限额、操作确认和渲染结果验证必须独立实施。任何会写入共享场景或加载不受控 URL 的工具，都需额外的最小权限与审核边界。

检查清单

  1. 导出真实公告给客户端的 schema manifest，而不是只检查源码类型。

  2. 递归审计所有 type: array，确认有 items；使用 prefixItems 的坐标元组同时验证长度和元素语义。

  3. 对 measure、polyline、polygon、trajectory、bbox、GeoJSON 和 CZML 各保留一个合法与一个非法回归输入。

  4. 在每种实际 MCP client 与浏览器 adapter 上执行工具发现，记录 client 版本和 manifest hash。

  5. 将发现失败、参数校验失败、命令执行失败和 Viewer 结果错误分为独立错误类别。

  6. 在 schema 之外限制顶点数、payload 字节、坐标范围、CRS、几何有效性和调用频率。

  7. 对场景写入、私有数据访问和大体量渲染保留授权、确认、异步任务与审计记录。

结论

3D GIS Agent 的工具目录不是辅助说明，而是客户端进入空间能力的第一道接口。cesium-mcp-contracts 0.6.1 的数组 schema 修复表明：兼容性测试应覆盖实际公告的 JSON Schema、严格客户端的发现行为和带坐标数组的最小调用。先让工具被正确发现，再验证空间操作被正确执行，三维 Agent 才有可审计的互操作基础。

参考来源

  1. cesium-mcp-contracts 0.6.1 Release：https://github.com/gaopengbin/cesium-mcp/releases/tag/cesium-mcp-contracts%400.6.1

  2. cesium-mcp PR #37：https://github.com/gaopengbin/cesium-mcp/pull/37