cesium-mcp-bridge

浏览器 SDK — 嵌入到 CesiumJS 应用中，通过 WebSocket 接收命令。

安装

npm install cesium-mcp-bridge

Peer 依赖：cesium@~1.143.0

初始化

import { CesiumBridge } from 'cesium-mcp-bridge'

const viewer = new Cesium.Viewer('cesiumContainer')
const bridge = new CesiumBridge(viewer)

JSON 命令在执行前会使用共享工具契约校验参数。可以只覆盖一个 Executor，其余命令继续使用默认实现：

const bridge = new CesiumBridge(viewer, {
  executors: {
    load3dTiles: async (params, bridge) => {
      return loadAuthorizedTileset(bridge.viewer, params)
    },
  },
})

JSON 命令分发会在执行前校验共享输入契约，并在执行后校验输出契约。确实需要扩展返回结构的自定义集成可设置 validateOutputs: false；输入侧也保留 validateInputs: false 兼容开关。

全部 60 个浏览器安全 Executor 已按领域组织，并与共享契约进行完整性校验。公开的 execute() 和单命令覆盖契约保持不变；敏感的 setIonToken 兼容命令不会进入共享 AI 工具面。

集成卸载时调用 bridge.dispose()。它会取消相机飞行和待完成截图，释放 Bridge 管理的动画、页面状态、Cesium 对象引用、Executor 和事件处理器，但不会销毁应用拥有的 Viewer 或场景内容。重复调用是安全的；销毁后的 execute() 会返回已销毁错误。

命令（60 个）

视图控制

命令	描述	关键参数
flyTo	相机飞行动画到指定位置	longitude, latitude, height, heading, pitch, roll, duration
setView	立即设置相机位置	longitude, latitude, height, heading, pitch, roll
getView	获取当前相机状态	—
zoomToExtent	缩放到地理范围	west, south, east, north
saveViewpoint	保存当前视角为命名书签	name
loadViewpoint	恢复已保存的视点书签	name, duration
listViewpoints	列出所有视点书签	—
exportScene	导出场景为结构化 JSON 快照	—

实体

命令	描述	关键参数
addMarker	添加点标记	longitude, latitude, label, color, size
addLabel	添加文字标注	data, field, style
addPolyline	添加折线（路径/线段）	coordinates, color, width, clampToGround
addPolygon	添加多边形区域	coordinates, color, outlineColor, opacity, extrudedHeight
addModel	放置 3D 模型 (glTF/GLB)	longitude, latitude, url, scale, heading, pitch, roll
updateEntity	更新实体属性	entityId, position, color, label, scale, show
removeEntity	移除单个实体	entityId
batchAddEntities	批量添加多个实体	entities（类型化定义数组）
queryEntities	搜索/筛选场景中的实体	name, type, bbox
getEntityProperties	获取实体的所有属性	entityId

图层管理

命令	描述	关键参数
addGeoJsonLayer	加载 GeoJSON 数据	url 或 data, name, style
addGeoJsonPrimitive	使用 Primitive 加载大规模 GeoJSON	url 或 data, name, allowPicking
listLayers	列出所有已加载图层	—
removeLayer	按 ID 移除图层	layerId
clearAll	移除所有图层、实体和数据源	—
setLayerVisibility	显示/隐藏图层	layerId, visible
updateLayerStyle	修改图层样式	layerId, layerStyle, imageryStyle, primitiveStyle, tileStyle
getLayerSchema	获取图层属性字段结构	layerId
setBasemap	切换底图影像	provider, url

高级相机

命令	描述	关键参数
lookAtTransform	环绕式相机注视	longitude, latitude, height, heading, pitch, range
startOrbit	开始相机环绕旋转	speed, direction
stopOrbit	停止环绕动画	—
setCameraOptions	配置相机控制器	enableRotate, enableZoom, enableTilt

扩展实体类型

命令	描述	关键参数
addBillboard	添加图片图标	longitude, latitude, image, scale
addBox	添加 3D 盒体	position, dimensions, material
addCorridor	添加走廊	positions, width, material
addCylinder	添加圆柱体/圆锥体	position, length, topRadius, bottomRadius
addEllipse	添加椭圆	position, semiMajorAxis, semiMinorAxis
addRectangle	添加矩形	west, south, east, north, material
addWall	添加墙体	positions, maximumHeights, minimumHeights

动画

命令	描述	关键参数
createAnimation	创建路径动画	entityId, waypoints, model
controlAnimation	播放/暂停动画	entityId, action
removeAnimation	删除动画实体	entityId
listAnimations	列出活跃动画	—
updateAnimationPath	更新路径可视属性	entityId, show, width, color
trackEntity	相机追踪实体	entityId
controlClock	配置时钟	startTime, stopTime, multiplier
setGlobeLighting	地球光照控制	enableLighting, enableFog

3D 场景

命令	描述	关键参数
load3dTiles	加载 3D Tileset	url 或 ionAssetId, name, maximumScreenSpaceError
load3dGaussianSplat	加载 3D 高斯泼溅数据集	url, name, maximumScreenSpaceError
loadTerrain	设置地形提供者	url, provider
loadImageryService	添加影像图层	url/serviceType 或 ionAssetId, name
loadCzml	加载 CZML 时间动态数据	data 或 url, name
loadKml	加载 KML/KMZ 数据	data 或 url, name
setEdgeDisplayMode	设置 3D Tiles 表面/边缘显示模式	tilesetId, mode

交互

命令	描述	关键参数
screenshot	截取当前视图	width, height, format
highlight	高亮要素	layerId, featureId, color
measure	测量距离或面积	type, coordinates

其他

命令	描述	关键参数
playTrajectory	沿路径播放动画	positions, duration, loop
addHeatmap	创建热力图可视化	points, name, radius, gradient

场景

命令	描述	关键参数
setSceneOptions	配置场景环境	fogEnabled, shadowsEnabled, sunShow, backgroundColor
setPostProcess	配置后处理效果	bloom, ambientOcclusion, fxaa

两种调用方式

方式一：类型安全方法

const result = await bridge.flyTo({
  longitude: 116.4,
  latitude: 39.9,
  height: 5000,
  duration: 2,
})

方式二：JSON 命令分发

const result = await bridge.execute({
  action: 'flyTo',
  params: {
    longitude: 116.4,
    latitude: 39.9,
    height: 5000,
    duration: 2,
  },
})

事件

bridge.on('layerAdded', (layer) => console.log('图层已添加:', layer))
bridge.on('layerRemoved', (layerId) => console.log('已移除:', layerId))
bridge.on('error', (err) => console.error('Bridge 错误:', err))

TypeScript 类型

import type {
  BridgeCommand,
  BridgeResult,
  FlyToParams,
  SetViewParams,
  AddGeoJsonLayerParams,
  AddHeatmapParams,
  Load3dTilesParams,
  PlayTrajectoryParams,
  LayerInfo,
  HighlightParams,
  // 相机
  LookAtTransformParams,
  StartOrbitParams,
  SetCameraOptionsParams,
  // 扩展实体类型
  AddBillboardParams,
  AddBoxParams,
  AddCorridorParams,
  AddCylinderParams,
  AddEllipseParams,
  AddRectangleParams,
  AddWallParams,
  MaterialSpec,
  MaterialInput,
  OrientationInput,
  PositionDegrees,
  // 动画
  CreateAnimationParams,
  ControlAnimationParams,
  RemoveAnimationParams,
  UpdateAnimationPathParams,
  TrackEntityParams,
  ControlClockParams,
  SetGlobeLightingParams,
  AnimationWaypoint,
  AnimationInfo,
  // 图层 Schema 与样式
  GetLayerSchemaParams,
  LayerSchemaResult,
  LayerSchemaField,
  UpdateLayerStyleParams,
  // 场景
  SetSceneOptionsParams,
  SetPostProcessParams,
  // 数据格式
  LoadCzmlParams,
  LoadKmlParams,
  // 交互
  MeasureParams,
} from 'cesium-mcp-bridge'