cesium-mcp-bridge

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

安装

npm install cesium-mcp-bridge

Peer 依赖：cesium@~1.139.0

初始化

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

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

命令（58 个）

视图控制

命令	描述	关键参数
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
listLayers	列出所有已加载图层	—
removeLayer	按 ID 移除图层	layerId
clearAll	移除所有图层、实体和数据源	—
setLayerVisibility	显示/隐藏图层	layerId, visible
updateLayerStyle	修改图层样式	layerId, style, 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
loadTerrain	设置地形提供者	url, provider
loadImageryService	添加影像图层	url/serviceType 或 ionAssetId, name
loadCzml	加载 CZML 时间动态数据	data 或 url, name
loadKml	加载 KML/KMZ 数据	data 或 url, name

交互

命令	描述	关键参数
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'