cesium-mcp

[!IMPORTANT]

📣 O autor está em busca de emprego · Pequim

Desenvolvimento de aplicações de IA · Desenvolvimento de aplicações de Agente · Full-stack de produtos de IA

Sou Gao Pengbin, com cerca de 6 anos de experiência em desenvolvimento de software. Se o seu time está contratando, fique à vontade para entrar em contato. Agradeço também por indicações ou compartilhamentos!

📄 Ver currículo em PDF　·　✉️ Fale comigo

Ver meus projetos e apresentação pessoal → · E-mail: 1804287165@qq.com

[!TIP] 📣 Construído com Cesium MCP? / Quem está usando o Cesium MCP?

Compartilhe seu projeto, capturas de tela ou feedback—trabalhos em andamento são bem-vindos! / 欢迎分享项目、截图和使用反馈，开发中的作品也欢迎！

Compartilhar / 分享 → Issue #44 · Discussão / 讨论区

---

Demonstração

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

Pacotes e Pontos de Entrada

Módulo	Função	Status	Links
cesium-mcp-contracts	Nomes, descrições e JSON Schemas neutros de transporte para ferramentas de navegador	Nova camada compartilhada	source
cesium-mcp-bridge	Executor de comandos Cesium sem protocolo e transporte (mais de 60 comandos)	Linha principal, iterado ativamente	· source
cesium-mcp-webmcp	Integração de Viewer em pacote único mais o adaptador nativo document.modelContext	Integração de navegador	source
examples/webmcp-integration	Integração npm + Vite focada, sem interface de chat ou servidor MCP	Exemplo para desenvolvedores	example
examples/browser-agent	Agente de IA somente de navegador com exposição automática via WebMCP	Recomendado	example · live demo
cesium-mcp-runtime	Servidor MCP (stdio + HTTP)	SDK MCP v2 estável	· source
cesium-mcp-dev	Base de conhecimento da API CesiumJS para assistentes de codificação	Mantido	· source

Qual usar? Projeto pessoal ou teste rápido → browser-agent. Deixe um agente de navegador compatível descobrir ferramentas Cesium locais à página → WebMCP. Aplicativo web existente incorporando um assistente de IA → bridge + seu próprio function calling. Chamadas a partir de Claude Desktop / Cursor / Dify → runtime MCP.

Arquitetura

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

O bridge continua sendo o núcleo de execução, enquanto contratos e adaptadores de protocolo permanecem separados. Escolha o driver que corresponda ao seu cenário — todos alcançam a mesma camada de comandos Cesium. Em navegadores compatíveis com WebMCP, o cesium-mcp-webmcp pode expor 61 comandos seguros de navegador em 12 conjuntos de ferramentas selecionáveis por meio de document.modelContext sem adicionar transporte MCP ou servidor backend.

Relação com o ecossistema de IA da CesiumGS

O trabalho mais recente de IA da CesiumGS está dividido entre cesiumjs-ai-starter-app, um modelo de aplicativo implantável, e cesiumjs-skills, orientação em tempo de desenvolvimento para agentes de codificação. O repositório anterior cesium-ai-integrations contém os experimentos de primeira geração e contribuições da comunidade que ajudaram a explorar esse espaço.

cesium-mcp é um runtime independente e um kit de ferramentas de integração, não uma continuação da arquitetura de referência anterior somente WebSocket. Seu Bridge reutilizável e contratos compartilhados funcionam inalterados em function calling somente de navegador, WebMCP nativo, MCP padrão via stdio/HTTP e shells desktop incorporados. Um bridge WebSocket local é usado apenas quando um host MCP externo precisa alcançar um Viewer de navegador ao vivo; não é necessário para a demonstração hospedada ou integrações locais à página.

O autor do projeto foi um contribuidor inicial do CesiumGS/cesium-ai-integrations, contribuindo com o servidor de Imagery, o servidor de Terrain e o Gateway MCP unificado. Esses experimentos informaram a arquitetura multiprotocolo deste projeto, enquanto a implementação, o ciclo de lançamento e o roteiro permanecem independentes.

Início Rápido

Caminho 0 — Experimente em 30 segundos (agente de navegador, recomendado)

Abra a demonstração ao vivo e pergunte—o modelo hospedado está pronto sem chave de API de navegador:

"Voe até a Torre Eiffel e solte um marcador vermelho"

Faça um fork da pasta examples/browser-agent para implantar o seu próprio.

Caminho 1 — Exponha ferramentas Cesium via WebMCP (Chrome 149+ experimental)

O exemplo de agente de navegador registra automaticamente todas as 61 ferramentas de página seguras para navegador, além de 3 ferramentas de recursos locais à página, quando document.modelContext está disponível. Seu chat integrado usa roteamento automático de conjuntos de ferramentas, mantendo os identificadores de recursos disponíveis para entradas grandes de GeoJSON/CZML, e ainda oferece modos explícitos de núcleo, conjunto único e todas as ferramentas:

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

Abra http://localhost:4173/examples/browser-agent/, clique em Iniciar e inspecione ou execute as ferramentas em DevTools → Application → WebMCP. Habilite #enable-webmcp-testing e #devtools-webmcp-support em chrome://flags para testes locais.

Desenvolvedores de aplicativos instalam o adaptador separadamente. Usuários finais apenas abrem o site integrado; eles não instalam pacotes npm nem executam um 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()

Consulte a API do adaptador WebMCP para integrações personalizadas. Para um aplicativo npm + Vite completo, comece pelo exemplo de integração WebMCP.

Caminho 2 — Incorpore no seu próprio aplicativo 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).

Consulte examples/browser-agent/index.html para um loop completo com APIs compatíveis com OpenAI.

Caminho 3 — Use a partir de Claude Desktop / Cursor / Dify (MCP)

Usuários comuns de MCP precisam apenas do pacote Runtime. Ele inclui o bundle do Bridge de navegador e um Viewer integrado em http://localhost:9100/; instale cesium-mcp-bridge separadamente apenas ao integrar uma 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

A versão estável atende aos clientes MCP 2025-11-25 existentes e ao novo protocolo 2026-07-28 a partir da mesma entrada stdio/HTTP. Ela usa o TypeScript SDK v2 estável e passa no cenário de conformidade oficial server-stateless (28/28).

Configuração do cliente MCP:

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

62 Ferramentas de Comando Disponíveis

As ferramentas estão organizadas em 12 conjuntos de ferramentas. O modo padrão habilita 4 conjuntos principais (30 ferramentas). Defina CESIUM_TOOLSETS=all para tudo, ou deixe a IA descobrir e ativar conjuntos de ferramentas dinamicamente em tempo de execução.

Contratos canônicos: As descrições das ferramentas são em inglês por padrão; defina CESIUM_LOCALE=zh-CN para chinês. Títulos, anotações de comportamento, descrições localizadas, padrões, validação de entrada, esquemas de saída MCP e resultados estruturados vêm todos dos JSON Schemas compartilhados em cesium-mcp-contracts. Texto content permanece disponível para clientes mais antigos.

Conjunto de ferramentas	Ferramentas
view (padrão)	flyTo, setView, getView, zoomToExtent, saveViewpoint, loadViewpoint, listViewpoints, exportScene
entity (padrão)	addMarker, addLabel, addModel, addPolygon, addPolyline, updateEntity, removeEntity, batchAddEntities, queryEntities, getEntityProperties
layer (padrão)	addGeoJsonLayer, addGeoJsonPrimitive, listLayers, removeLayer, clearAll, setLayerVisibility, updateLayerStyle, getLayerSchema, setBasemap
interaction (padrão)	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 (somente Runtime)
geolocation	geocode

Exemplos

Consulte examples/minimal/ para uma demonstração completa e funcional.

Desenvolvimento

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 é o portão de paridade focado para metadados do Runtime MCP, registro WebMCP, definições de Function Calling, portabilidade de Schema do provedor e o Registro do Executor Bridge com 60 ferramentas. Execute test:schema-compat diretamente para diagnósticos acionáveis de Schema OpenAI, Azure, VS Code MCP e WebMCP. test:routing avalia solicitações de Agente de Navegador bilíngues e de múltiplas intenções em todos os 12 conjuntos de ferramentas, verificando a recuperação de ferramentas necessárias e o orçamento de roteamento automático de 20 ferramentas. test:model-tools verifica o harness de pontuação multi-turno neutro ao provedor. eval:model-tools executa um preflight de roteamento sem rede por padrão; adicione um provedor explícito e --live para medir a escolha real de ferramentas, validade de argumentos e conclusão de ferramentas necessárias. Consulte Avaliação de Ferramentas de Modelo. test:e2e:packed compila tarballs npm, instala-os em um projeto temporário limpo, abre o Viewer Cesium real e verifica um round trip de comando Runtime-WebSocket-Bridge.

Política de Versão

Formato da versão: {CesiumMajor}.{CesiumMinor}.{MCPPatch}

Segmento	Significado	Exemplo
1.145	Acompanha a versão do CesiumJS — compilado e testado contra Cesium ~1.145.0	1.145.0 → Cesium 1.145
.x	Patch MCP — iterações independentes para novas ferramentas, correções de bugs, documentação	1.145.0 → 1.145.1

Lançamentos oficiais do CesiumJS são revisados antes que a linha de base de compatibilidade seja atualizada; o projeto não reivindica automaticamente suporte para uma versão mais recente sem verificação do Bridge.

Projetos Relacionados

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

Comunidade

Este projeto reconhece o LINUX DO como uma comunidade para intercâmbio de código aberto, discussão técnica e feedback de desenvolvedores.

Histórico de Estrelas

Licença

MIT