# cesium-mcp-runtime

AI-powered 3D globe control via MCP — 59 tools for camera, layers, entities, animation, scene, interaction, heatmap, trajectory, and geocoding with CesiumJS.

## Quick Start

```bash
# Connect this server (installs CLI if needed)
npx -y @smithery/cli@latest mcp add gaopengbin/cesium-mcp-runtime

# Browse available tools
npx -y @smithery/cli@latest tool list gaopengbin/cesium-mcp-runtime

# Get full schema for a tool
npx -y @smithery/cli@latest tool get gaopengbin/cesium-mcp-runtime flyTo

# Call a tool
npx -y @smithery/cli@latest tool call gaopengbin/cesium-mcp-runtime flyTo '{}'
```

## Direct MCP Connection

Endpoint: `https://cesium-mcp-runtime--gaopengbin.run.tools`

**Optional config:**
- `toolsets` (query) — Comma-separated toolset names to enable on startup (e.g. 'camera,bindbindEntity,bindLayer'). If not set, all toolsets are enabled by default.

## Tools (43)

- `flyTo` — 飞行到指定经纬度位置（带动画过渡）
- `addGeoJsonLayer` — 添加 GeoJSON 图层到地图（支持 Point/Line/Polygon，可配置颜色/分级/分类渲染）
- `addLabel` — 为 GeoJSON 要素添加文本标注（显示属性值）
- `addHeatmap` — 添加热力图图层（基于 GeoJSON 点数据生成热力可视化）
- `removeLayer` — 从地图上移除指定图层（按图层ID）
- `setBasemap` — 切换底图风格（暗色/卫星影像/标准）
- `screenshot` — 截取当前地图视图（返回 base64 PNG）
- `highlight` — 高亮指定图层的要素
- `setView` — 瞬间切换到指定经纬度视角（无动画）
- `getView` — 获取当前相机视角信息（经纬度、高度、角度）
- `zoomToExtent` — 缩放到指定地理范围
- `addMarker` — 在指定经纬度添加标注点，返回 layerId 供后续操作
- `addPolyline` — 在地图上添加折线（路径、线段），返回 entityId
- `addPolygon` — 在地图上添加多边形区域（面积、边界），返回 entityId
- `addModel` — 在指定经纬度放置 3D 模型（glTF/GLB），返回 entityId
- `updateEntity` — 更新已有实体的属性（位置、颜色、标签、缩放、可见性）
- `removeEntity` — 移除单个实体（通过 entityId）
- `setLayerVisibility` — 设置图层可见性
- `listLayers` — 获取当前所有图层列表（含 ID、名称、类型、可见性）
- `updateLayerStyle` — 修改已有图层的样式（颜色、透明度、标注样式等）
- `playTrajectory` — 播放移动轨迹动画
- `load3dTiles` — 加载 3D Tiles 数据集（如建筑白膜、城市模型）
- `loadTerrain` — 加载或切换地形（平坦/ArcGIS/CesiumIon/自定义 URL）
- `loadImageryService` — 加载影像服务图层（WMS/WMTS/XYZ/ArcGIS MapServer）
- `lookAtTransform` — 环绕式相机注视某位置（ENU变换 + 朝向/俯仰/距离）
- `startOrbit` — 开始相机环绕当前中心旋转
- `stopOrbit` — 停止环绕动画
- `setCameraOptions` — 配置相机控制器（启用/禁用旋转、缩放、倾斜等）
- `addBillboard` — 在指定位置添加图片图标
- `addBox` — 添加带尺寸和材质的3D盒体
- `addCorridor` — 添加走廊（带宽度的路径）
- `addCylinder` — 添加圆柱体或圆锥体
- `addEllipse` — 添加椭圆
- `addRectangle` — 按地理范围添加矩形
- `addWall` — 沿路径添加墙体
- `createAnimation` — 创建基于时间的路径动画（实体沿路径运动）
- `controlAnimation` — 播放或暂停动画
- `removeAnimation` — 删除动画实体
- `listAnimations` — 列出所有活跃的动画
- `updateAnimationPath` — 更新动画路径的可视属性
- `trackEntity` — 相机追踪实体
- `controlClock` — 配置Cesium时钟（时间范围、速度、动画状态）
- `setGlobeLighting` — 启用/禁用地球光照和大气效果

```bash
# Get full input/output schema for a tool
npx -y @smithery/cli@latest tool get gaopengbin/cesium-mcp-runtime <tool-name>
```

## Resources

- `cesium://scene/camera` — 当前相机状态（经纬度、高度、角度）
- `cesium://scene/layers` — 当前已加载的图层列表（ID、名称、类型、可见性）