cesium-mcp

[!IMPORTANT]

📣 El autor está buscando trabajo · Beijing

Desarrollo de aplicaciones de IA · Desarrollo de aplicaciones de agentes · Producto de IA full-stack

Soy Gao Pengbin, con aproximadamente 6 años de experiencia en desarrollo de software. Si su equipo está contratando, no dude en contactarme. ¡También agradezco referencias o reenvíos!

📄 Ver currículum en PDF　·　✉️ Contáctame

Ver mis proyectos y presentación personal → · Correo: 1804287165@qq.com

[!TIP] 📣 ¿Construido con Cesium MCP? / ¿Quién usa Cesium MCP?

¡Comparte tu proyecto, capturas de pantalla o comentarios—trabajos en progreso son bienvenidos! / ¡Bienvenidos a compartir proyectos, capturas de pantalla y comentarios de uso, también se aceptan trabajos en desarrollo!

Compartir → Issue #44 · Discusión

---

Demo

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 JSON Schemas neutrales al 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, iterado activamente	· fuente
cesium-mcp-webmcp	Integración de Viewer en un solo paquete más el adaptador nativo document.modelContext	Integración 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 · demo 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 elegir? Proyecto personal o prueba rápida → browser-agent. Deja que un agente de navegador compatible descubra herramientas de Cesium locales a la página → WebMCP. Aplicación web existente que integra un asistente de IA → bridge + tu propio function calling. Llamadas desde Claude Desktop / Cursor / Dify → runtime 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 adaptadores de protocolo permanecen separados. Elige el controlador que coincida con 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 agregar un transporte MCP ni un servidor backend.

Relación con el ecosistema de IA de CesiumGS

El trabajo de IA más reciente de CesiumGS se divide entre cesiumjs-ai-starter-app, una plantilla de aplicación desplegable, y cesiumjs-skills, orientación en tiempo de desarrollo para agentes de codificación. El repositorio anterior cesium-ai-integrations contiene los experimentos de primera generación y contribuciones de la comunidad que ayudaron a explorar este espacio.

cesium-mcp es un runtime y kit de integración independiente, no una continuación de la arquitectura de referencia anterior solo con WebSocket. Su Bridge reutilizable y contratos compartidos funcionan sin cambios en function calling solo de navegador, WebMCP nativo, MCP estándar sobre stdio/HTTP y shells de escritorio integrados. Un bridge WebSocket local se usa solo cuando un host MCP externo necesita alcanzar un Viewer de navegador en vivo; no es necesario para la demo alojada ni para integraciones locales a la página.

El autor del proyecto fue un contribuyente temprano de CesiumGS/cesium-ai-integrations, contribuyendo con el servidor de Imagery, el servidor de Terrain y el Gateway MCP unificado. Esos experimentos informaron la arquitectura multiprotocolo de este proyecto, mientras que la implementación, el ciclo de lanzamiento y la hoja de ruta permanecen independientes.

Inicio rápido

Ruta 0 — Prueba en 30 segundos (agente de navegador, recomendado)

Abre la demo en vivo y pregunta — el modelo alojado está listo sin clave de API de navegador:

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

Haz 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 más 3 herramientas de recursos locales a la página cuando document.modelContext está disponible. Su chat integrado usa enrutamiento automático de conjuntos de herramientas mientras mantiene los manejadores de recursos disponibles para entradas grandes de GeoJSON/CZML, y aún ofrece modos explícitos de núcleo, conjunto único y todas las 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, 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-mcp-webmcp

import { registerCesiumViewerWebMcp } from 'cesium-mcp-webmcp/viewer'

const registration = await registerCesiumViewerWebMcp(viewer, {
  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 desde el ejemplo de integración WebMCP.

Ruta 2 — Integra en tu propia aplicación web (function calling)

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)

Los usuarios comunes de MCP solo necesitan el paquete Runtime. Incluye el bundle del Bridge de navegador y un Viewer integrado en http://localhost:9100/; instala cesium-mcp-bridge por separado solo al integrar una página personalizada.

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

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

La versión estable sirve a los clientes MCP 2025-11-25 existentes y al nuevo protocolo 2026-07-28 desde la misma entrada stdio/HTTP. Usa el TypeScript SDK v2 estable y pasa 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 núcleo (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. Títulos, anotaciones de comportamiento, descripciones localizadas, valores predeterminados, validación de entrada, esquemas de salida MCP y resultados estructurados provienen todos de los JSON Schemas 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 Runtime)
geolocation	geocode

Ejemplos

Consulta examples/minimal/ para una demo 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:schema-compat
npm run test:routing
npm run test:model-tools
npm run eval:model-tools
npm run test:e2e:packed

test:contracts es la puerta de paridad enfocada para metadatos de Runtime MCP, registro de WebMCP, definiciones de Function Calling, portabilidad de Schema de proveedores y el Registro de Ejecutor del Bridge de 60 herramientas. Ejecuta test:schema-compat directamente para diagnósticos accionables de Schema de OpenAI, Azure, VS Code MCP y WebMCP. 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:model-tools verifica el arnés de puntuación de múltiples turnos neutral al proveedor. eval:model-tools realiza un preflight de enrutamiento sin red por defecto; agrega un proveedor explícito y --live para medir la elección real de herramientas, validez de argumentos y finalización de herramientas requeridas. Consulta Evaluación de herramientas de modelo. test:e2e:packed construye tarballs npm, los instala en un proyecto temporal limpio, abre el Viewer real de Cesium y verifica un viaje de ida y vuelta de comando Runtime-WebSocket-Bridge.

Política de versiones

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

Segmento	Significado	Ejemplo
1.145	Rastrea la versión de CesiumJS — construido y probado contra Cesium ~1.145.0	1.145.0 → Cesium 1.145
.x	Parche MCP — iteraciones independientes para nuevas herramientas, correcciones de errores, documentación	1.145.0 → 1.145.1

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

Proyectos relacionados

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

Comunidad

Este proyecto reconoce a LINUX DO como una comunidad para intercambio de código abierto, discusión técnica y comentarios de desarrolladores.

Historial de estrellas

Licencia

MIT