cesium-mcp

---

Demostración

https://github.com/user-attachments/assets/8a40565a-fcdd-47bf-ae67-bc870611c908

Paquetes y puntos de entrada

Módulo	Rol	Estado	Enlaces
cesium-mcp-contracts	Nombres, descripciones y esquemas JSON neutrales de transporte para herramientas de navegador	Nueva capa compartida	fuente
cesium-mcp-bridge	Ejecutor de comandos de Cesium sin protocolo ni transporte (más de 60 comandos)	Línea principal, iterada activamente	· fuente
cesium-mcp-webmcp	Adaptador nativo document.modelContext para contratos de herramientas de Cesium	Nuevo adaptador de navegador	fuente
examples/webmcp-integration	Integración enfocada de npm + Vite sin interfaz de chat ni servidor MCP	Ejemplo para desarrolladores	ejemplo
examples/browser-agent	Agente de IA solo de navegador con exposición automática de WebMCP	Recomendado	ejemplo · demostración en vivo
cesium-mcp-runtime	Servidor MCP (stdio + HTTP)	SDK MCP v2 estable	· fuente
cesium-mcp-dev	Base de conocimiento de la API de CesiumJS para asistentes de codificación	Mantenido	· fuente

¿Cuál? Proyecto personal o prueba rápida → browser-agent. Deja que un agente de navegador compatible descubra herramientas de Cesium locales de la página → WebMCP. Aplicación web existente que integra un asistente de IA → bridge + tu propia llamada a funciones. Llamadas desde Claude Desktop / Cursor / Dify → tiempo de ejecución de MCP.

Arquitectura

flowchart LR
  subgraph clients ["AI Drivers (pick one)"]
    BA["Browser Agent\n(in the same page)"]
    WM["WebMCP Agent\n(browser-provided)"]
    FC["Your web app\nfunction calling"]
    MCP["Claude / Cursor / Dify\nvia MCP runtime"]
  end

  CONTRACTS["cesium-mcp-contracts\ntool definitions"]
  WEBMCP["cesium-mcp-webmcp\nnative adapter"]

  subgraph core ["cesium-mcp-bridge (browser)"]
    B["60+ tools\nprotocol-agnostic dispatcher"]
    C["CesiumJS Viewer"]
  end

  CONTRACTS -.-> BA
  CONTRACTS -.-> WEBMCP
  BA -- "in-page call" --> B
  WM -- "document.modelContext" --> WEBMCP
  WEBMCP --> B
  FC -- "in-page call" --> B
  MCP -- "WebSocket / JSON-RPC" --> B
  B --> C

  style clients fill:#1e293b,stroke:#528bff,color:#e2e8f0
  style core fill:#1e293b,stroke:#12B76A,color:#e2e8f0

El bridge sigue siendo el núcleo de ejecución, mientras que los contratos y los adaptadores de protocolo permanecen separados. Elige el controlador que se ajuste a tu escenario: todos llegan a la misma capa de comandos de Cesium. En navegadores compatibles con WebMCP, cesium-mcp-webmcp puede exponer 61 comandos seguros para navegador en 12 conjuntos de herramientas seleccionables a través de document.modelContext sin añadir un transporte MCP ni un servidor backend.

Inicio rápido

Ruta 0 — Pruébalo en 30 segundos (agente de navegador, recomendado)

Abre la demostración en vivo y pregunta: el modelo alojado está listo sin una clave de API de navegador:

"Vuela a la Torre Eiffel y deja un marcador rojo"

Haz un fork de la carpeta examples/browser-agent para desplegar la tuya.

Ruta 1 — Expón herramientas de Cesium a través de WebMCP (Chrome 149+ experimental)

El ejemplo de browser-agent registra automáticamente las 61 herramientas de página seguras para navegador cuando document.modelContext está disponible. Su chat integrado utiliza enrutamiento automático de conjuntos de herramientas para mantener cada solicitud normal en 20 herramientas o menos, mientras sigue ofreciendo modos explícitos de núcleo, conjunto único y las 61 herramientas:

npm run build -w packages/cesium-mcp-bridge
npm run build -w packages/cesium-mcp-webmcp
npx serve . -l 4173

Abre http://localhost:4173/examples/browser-agent/, haz clic en Iniciar y luego inspecciona o ejecuta las herramientas en DevTools → Application → WebMCP. Habilita #enable-webmcp-testing y #devtools-webmcp-support en chrome://flags para pruebas locales.

Los desarrolladores de aplicaciones instalan el adaptador por separado. Los usuarios finales solo abren el sitio web integrado; no instalan paquetes npm ni ejecutan un servidor MCP.

npm install cesium cesium-mcp-bridge cesium-mcp-webmcp

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

const bridge = new CesiumBridge(viewer)
const registration = await registerCesiumWebMcp(bridge, {
  toolsets: 'all',
  excludeTools: ['geocode'], // add your own browser geocoder to expose this tool
})

// Later, if the page is unmounted:
registration.unregister()

Consulta la API del adaptador WebMCP para integraciones personalizadas. Para una aplicación completa de npm + Vite, comienza con el ejemplo de integración WebMCP.

Ruta 2 — Incrusta en tu propia aplicación web (llamada a funciones)

npm install cesium-mcp-bridge

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

const bridge = new CesiumBridge(viewer);
// Then: send the bridge's tool schema to any LLM that supports function/tool calling,
// route the model's tool calls to bridge.execute(name, params).

Consulta examples/browser-agent/index.html para un bucle completo con APIs compatibles con OpenAI.

Ruta 3 — Usa desde Claude Desktop / Cursor / Dify (MCP)

Instala el bridge como en la Ruta 2 y luego inicia el tiempo de ejecución de MCP:

# Stable channel — npm latest, MCP SDK v2
npx cesium-mcp-runtime

# HTTP mode
npx cesium-mcp-runtime --transport http --port 3000

La versión estable atiende a los clientes MCP 2025-11-25 existentes y al nuevo protocolo 2026-07-28 desde la misma entrada stdio/HTTP. Utiliza el SDK de TypeScript v2 estable y supera el escenario de conformidad oficial server-stateless (28/28).

Configuración del cliente MCP:

{
  "mcpServers": {
    "cesium": {
      "command": "npx",
      "args": ["-y", "cesium-mcp-runtime"]
    }
  }
}

62 herramientas de comando disponibles

Las herramientas están organizadas en 12 conjuntos de herramientas. El modo predeterminado habilita 4 conjuntos de herramientas principales (30 herramientas). Establece CESIUM_TOOLSETS=all para todo, o deja que la IA descubra y active conjuntos de herramientas dinámicamente en tiempo de ejecución.

Contratos canónicos: Las descripciones de herramientas están en inglés por defecto; establece CESIUM_LOCALE=zh-CN para chino. Los títulos, anotaciones de comportamiento, descripciones localizadas, valores predeterminados, validación de entrada, esquemas de salida MCP y resultados estructurados provienen de los esquemas JSON compartidos en cesium-mcp-contracts. El texto content sigue disponible para clientes más antiguos.

Conjunto de herramientas	Herramientas
view (predeterminado)	flyTo, setView, getView, zoomToExtent, saveViewpoint, loadViewpoint, listViewpoints, exportScene
entity (predeterminado)	addMarker, addLabel, addModel, addPolygon, addPolyline, updateEntity, removeEntity, batchAddEntities, queryEntities, getEntityProperties
layer (predeterminado)	addGeoJsonLayer, addGeoJsonPrimitive, listLayers, removeLayer, clearAll, setLayerVisibility, updateLayerStyle, getLayerSchema, setBasemap
interaction (predeterminado)	screenshot, highlight, measure
camera	lookAtTransform, startOrbit, stopOrbit, setCameraOptions
entity-ext	addBillboard, addBox, addCorridor, addCylinder, addEllipse, addRectangle, addWall
animation	createAnimation, controlAnimation, removeAnimation, listAnimations, updateAnimationPath, trackEntity, controlClock, setGlobeLighting
tiles	load3dTiles, load3dGaussianSplat, loadTerrain, loadImageryService, loadCzml, loadKml, setEdgeDisplayMode
trajectory	playTrajectory
heatmap	addHeatmap
scene	setSceneOptions, setPostProcess, setIonToken (Solo en tiempo de ejecución)
geolocation	geocode

Relación con los servidores MCP oficiales de CesiumGS: Los conjuntos de herramientas camera, entity-ext y animation fusionan de forma nativa las capacidades de CesiumGS/cesium-mcp-server (Camera Server, Entity Server, Animation Server) en la arquitectura de bridge unificada de este proyecto. Esto significa que obtienes toda la funcionalidad oficial más herramientas adicionales, en un solo servidor MCP, sin ejecutar múltiples procesos.

Ejemplos

Consulta examples/minimal/ para una demostración completa y funcional.

Desarrollo

git clone https://github.com/gaopengbin/cesium-mcp.git
cd cesium-mcp
npm install
npm run build
npm test
npm run test:contracts
npm run test:routing
npm run test:e2e:packed

test:contracts es la puerta de paridad enfocada para los metadatos del tiempo de ejecución de MCP, el registro de WebMCP, las definiciones de llamada a funciones y el registro del ejecutor de bridge de 60 herramientas. test:routing evalúa solicitudes bilingües y de múltiples intenciones del agente de navegador en los 12 conjuntos de herramientas, verificando el recuerdo de herramientas requeridas y el presupuesto de enrutamiento automático de 20 herramientas. test:e2e:packed construye paquetes npm, los instala en un proyecto temporal limpio, abre el visor real de Cesium y verifica un viaje de ida y vuelta de comandos Runtime-WebSocket-Bridge.

Política de versiones

Formato de versión: {CesiumMajor}.{CesiumMinor}.{MCPPatch}

Segmento	Significado	Ejemplo
1.143	Sigue la versión de CesiumJS: construido y probado contra Cesium ~1.143.0	1.143.0 → Cesium 1.143
.x	Parche de MCP: iteraciones independientes para nuevas herramientas, correcciones de errores, documentación	1.143.0 → 1.143.1

Los lanzamientos oficiales de CesiumJS se revisan antes de aumentar la línea base de compatibilidad; el proyecto no reclama automáticamente soporte para una versión más reciente sin verificación del Bridge.

Proyectos relacionados

• mapbox-mcp — Control de IA para Mapbox GL JS
• openlayers-mcp — Control de IA para OpenLayers

Historial de estrellas

Licencia

MIT