# 架构概览
## 总览
Cesium MCP 使用共享工具契约和协议无关的浏览器执行层，并为 WebMCP、MCP 客户端和 IDE 辅助提供独立适配层。下图展示 MCP runtime 接入路径：
AI 智能体
Claude, Cursor, VS Code…
cesium-mcp-runtime
Node.js MCP 服务器
WebSocket
cesium-mcp-bridge
浏览器 SDK
## 各包职责
### cesium-mcp-contracts（共享契约）
Contracts 包维护与传输协议无关的工具名称、描述、JSON Schema、默认值、结果结构和工具集归属。WebMCP 直接发布这些定义，Function Calling 将同一输入 Schema 映射为 `function.parameters`，MCP Runtime 则包装为 SDK v2 Standard Schema，并且只增加传输层可选参数 `sessionId`。自动化一致性测试会对照全部 61 个共享工具和 Bridge 的 60 个 Executor，防止名称、描述或输入 Schema 静默漂移。
### cesium-mcp-bridge（浏览器端）
Bridge 运行在**浏览器内部**，与 CesiumJS 应用共存。它：
- 执行来自 WebMCP、function calling 或 MCP runtime 的命令
- 仅在选择 MCP runtime 路径时通过 WebSocket 连接 Runtime
- 执行 CesiumJS API 调用（相机、图层、实体等）
- 将结构化结果返回给调用它的适配层
**两种调用方式：**
- **类型安全方法**：`bridge.flyTo({ longitude: 2.29, latitude: 48.86, height: 1000 })`
- **JSON 命令分发**：`bridge.execute({ action: 'flyTo', params: { ... } })`
### cesium-mcp-webmcp（浏览器适配层）
WebMCP 包把共享契约注册到原生 `document.modelContext` API。默认暴露 15 个核心工具，也可以按 12 个工具集暴露全部 61 个浏览器安全工具。它不包含 AI 模型、聊天界面、MCP 服务、WebSocket 传输层或 polyfill。
该适配层与 `cesium-mcp-runtime` 保持独立，接入步骤见 [WebMCP 浏览器接入](/zh-CN/guide/webmcp)。
### cesium-mcp-runtime（Node.js）
Runtime 是一个 **Node.js MCP 服务器**，充当 AI 智能体和浏览器之间的翻译器。它：
- 通过 stdio 暴露 **62 个 MCP 命令工具**（按 **12 个工具集** 组织）+ 2 个资源
- 运行 WebSocket + HTTP 服务器（默认端口 9100）
- 将 MCP 工具调用转译为 Bridge 命令
- 支持多会话路由以管理多个浏览器标签页
- 提供 HTTP Push API（`POST /api/command`）供后端系统集成
### cesium-mcp-dev（Node.js）
Dev 服务器是独立的 **IDE 助手**，不需要运行中的地球。它提供：
- CesiumJS API 文档查询（12 个核心类）
- 常见模式的代码片段生成
- Entity 模板构建器，用于生成配置
## 数据流
### AI 智能体 → 地球（工具调用）
```
1. 用户："添加一个地震数据的 GeoJSON 图层"
2. AI 智能体 → MCP 工具调用：addGeoJsonLayer({ url: "...", name: "earthquakes" })
3. Runtime 通过 stdio 接收工具调用
4. Runtime 发送 WebSocket 命令：{ action: "addGeoJsonLayer", params: { ... } }
5. Bridge 执行：viewer.dataSources.add(Cesium.GeoJsonDataSource.load(...))
6. Bridge 返回：{ success: true, layerId: "..." }
7. 结果回流：Bridge → Runtime → AI 智能体
8. AI 智能体："我已经把地震数据图层添加到地图上了。"
```
### 地球 → AI 智能体（资源读取）
```
1. AI 智能体读取资源：cesium://scene/camera
2. Runtime 通过 WebSocket 将请求转发给 Bridge
3. Bridge 读取：viewer.camera.positionCartographic
4. Bridge 返回：{ longitude: 2.29, latitude: 48.86, height: 1000 }
5. AI 智能体获取相机状态，用于上下文感知决策
```
## 工具集与动态发现
62 个 Runtime 命令工具按 **12 个工具集** 组织，解决 LLM 工具选择困难：
| 工具集 | 工具数 | 默认启用 |
|--------|--------|----------|
| `view` | 7 | 是 |
| `entity` | 9 | 是 |
| `layer` | 6 | 是 |
| `interaction` | 2 | 是 |
| `camera` | 4 | — |
| `entity-ext` | 7 | — |
| `animation` | 8 | — |
| `tiles` | 3 | — |
| `trajectory` | 1 | — |
| `heatmap` | 1 | — |
| `geolocation` | 1 | — |
默认启用 4 个核心工具集（约 24 个工具）。其余工具集可通过两种方式激活：
1. **环境变量**：`CESIUM_TOOLSETS=all` 启用全部
2. **动态发现**：两个元工具（`list_toolsets`、`enable_toolset`）允许 AI 智能体在运行时自主发现和激活工具集，无需用户手动配置
```
AI："我需要创建一个动画"
→ 调用 list_toolsets → 发现 animation 工具集未启用
→ 调用 enable_toolset("animation") → 8 个动画工具变为可用
→ 调用 createAnimation(...)
```
## 会话路由
多个浏览器标签页可以连接到同一个 Runtime。每个 Bridge 连接使用一个 `sessionId`：
```
浏览器标签页 1 (sessionId: "project-a") ──┐
├── cesium-mcp-runtime ── AI 智能体
浏览器标签页 2 (sessionId: "project-b") ──┘
```
MCP HTTP 模式下，在端点 URL 后添加 `?session=xxx` 可自动将所有工具调用路由到指定浏览器：
```
http://localhost:3216/mcp?session=project-a
```
路由优先级：工具参数 `sessionId` > URL `?session=xxx` > `DEFAULT_SESSION_ID` 环境变量 > 第一个已连接的浏览器。工具参数和 URL 中显式选择的会话必须精确命中；目标会话不可用时 Runtime 会返回错误，不会把命令转发到另一个 Viewer。只有调用方没有显式选择会话时，才会使用默认会话或首个已连接浏览器。每个待处理请求还会绑定到接收命令的 WebSocket，其他浏览器不能代替它返回结果；目标断线时对应请求会立即失败。
## 版本策略
已有的 `cesium-mcp-bridge`、`cesium-mcp-runtime` 和 `cesium-mcp-dev` 使用 [changesets](https://github.com/changesets/changesets) 共享同一版本号（**fixed** 模式）。新增的 `cesium-mcp-contracts` 与 `cesium-mcp-webmcp` 使用独立的语义化版本。
**主版本号.次版本号** 跟踪 CesiumJS：
- `cesium-mcp-*@1.143.x` 对应已验证的 `cesium@~1.143.0` 基线
**修订版本号** 独立迭代，用于 MCP 功能更新。