# Architecture
## Overview
Cesium MCP uses shared contracts and a protocol-neutral browser executor with separate adapters for WebMCP, MCP clients, and IDE assistance. The diagram below shows the MCP runtime path:
AI Agent
Claude, Cursor, VS Code…
stdio / MCP
cesium-mcp-runtime
Node.js MCP Server
WebSocket
cesium-mcp-bridge
Browser SDK
API
CesiumJS Viewer
3D Globe
## Package Roles
### cesium-mcp-contracts (Shared)
The contracts package owns transport-neutral tool names, descriptions, JSON Schemas, defaults, result shapes, and toolset membership. The WebMCP adapter and MCP runtime both consume these definitions. At registration time the runtime converts the canonical JSON Schema to Zod, so MCP validation and WebMCP declarations cannot drift into separate schemas.
### cesium-mcp-bridge (Browser)
The bridge runs **inside the browser** alongside your CesiumJS application. It:
- Executes commands received from WebMCP, function calling, or the MCP runtime
- Can connect to the runtime via WebSocket when that integration path is used
- Executes CesiumJS API calls (camera, layers, entities, etc.)
- Returns structured results to the calling adapter
**Two calling styles:**
- **Type-safe methods**: `bridge.flyTo({ longitude: 2.29, latitude: 48.86, height: 1000 })`
- **JSON command dispatch**: `bridge.execute({ action: 'flyTo', params: { ... } })`
### cesium-mcp-webmcp (Browser Adapter)
The WebMCP package registers the shared contracts on the native `document.modelContext` API. It exposes 15 core tools by default or all 61 browser-safe tools across 12 toolsets. It does not include an AI model, chat UI, MCP server, WebSocket transport, or polyfill.
This adapter is intentionally separate from `cesium-mcp-runtime`; see the [WebMCP integration guide](/guide/webmcp).
### cesium-mcp-runtime (Node.js)
The runtime is a **Node.js MCP server** that acts as a translator between the AI agent and the browser. It:
- Exposes **62 MCP command tools** (organized into **12 toolsets**) + 2 resources via stdio
- Runs a WebSocket + HTTP server (default port 9100)
- Translates MCP tool calls into bridge commands
- Supports multi-session routing for multiple browser tabs
- Provides HTTP Push API (`POST /api/command`) for backend integration
### cesium-mcp-dev (Node.js)
The dev server is a standalone **IDE assistant** that doesn't require a running globe. It provides:
- CesiumJS API documentation lookup (12 core classes)
- Code snippet generation for common patterns
- Entity template builder for generating configurations
## Data Flow
### AI Agent → Globe (Tool Call)
```
1. User: "Add a GeoJSON layer of earthquake data"
2. AI Agent → MCP tool call: addGeoJsonLayer({ url: "...", name: "earthquakes" })
3. Runtime receives tool call via stdio
4. Runtime sends WebSocket command: { action: "addGeoJsonLayer", params: { ... } }
5. Bridge executes: viewer.dataSources.add(Cesium.GeoJsonDataSource.load(...))
6. Bridge returns: { success: true, layerId: "..." }
7. Result flows back: Bridge → Runtime → AI Agent
8. AI Agent: "I've added the earthquake data layer to the map."
```
### Globe → AI Agent (Resource Read)
```
1. AI Agent reads resource: cesium://scene/camera
2. Runtime forwards request to bridge via WebSocket
3. Bridge reads: viewer.camera.positionCartographic
4. Bridge returns: { longitude: 2.29, latitude: 48.86, height: 1000 }
5. AI Agent receives camera state for context-aware decisions
```
## Toolsets & Dynamic Discovery
62 Runtime command tools are organized into **12 toolsets** to manage LLM tool selection complexity:
| Toolset | Tools | Default |
|---------|-------|---------|
| `view` | 7 | Yes |
| `entity` | 9 | Yes |
| `layer` | 6 | Yes |
| `interaction` | 2 | Yes |
| `camera` | 4 | — |
| `entity-ext` | 7 | — |
| `animation` | 8 | — |
| `tiles` | 3 | — |
| `trajectory` | 1 | — |
| `heatmap` | 1 | — |
| `geolocation` | 1 | — |
By default, 4 core toolsets (~24 tools) are enabled. The remaining toolsets can be activated via:
1. **Environment variable**: `CESIUM_TOOLSETS=all` enables everything
2. **Dynamic Discovery**: Two meta-tools (`list_toolsets`, `enable_toolset`) allow the AI agent to discover and activate toolsets at runtime — no user configuration needed
```
AI: "I need to create an animation"
→ calls list_toolsets → sees animation toolset is disabled
→ calls enable_toolset("animation") → 8 animation tools become available
→ calls createAnimation(...)
```
## Session Routing
Multiple browser tabs can connect to the same runtime. Each connection uses a `sessionId`:
```
Browser Tab 1 (sessionId: "project-a") ──┐
├── cesium-mcp-runtime ── AI Agent
Browser Tab 2 (sessionId: "project-b") ──┘
```
For MCP HTTP mode, add `?session=xxx` to the endpoint URL to automatically route all tool calls to the specified browser:
```
http://localhost:3216/mcp?session=project-a
```
Routing priority: tool param `sessionId` > URL `?session=xxx` > `DEFAULT_SESSION_ID` env > first connected browser.
## Version Strategy
The established `cesium-mcp-bridge`, `cesium-mcp-runtime`, and `cesium-mcp-dev` packages share a version number using [changesets](https://github.com/changesets/changesets) with **fixed** versioning mode. The newer `cesium-mcp-contracts` and `cesium-mcp-webmcp` packages use independent semantic versions.
**Major.minor** tracks CesiumJS:
- `cesium-mcp-*@1.143.x` targets the verified `cesium@~1.143.0` baseline
**Patch** versions iterate independently for MCP feature updates.