WebMCP 浏览器接入

当你希望兼容 WebMCP 的浏览器智能体发现并调用当前页面里的 Cesium 工具时，使用 WebMCP。工具仍然通过 cesium-mcp-bridge 执行，但不需要启动 cesium-mcp-runtime、WebSocket 服务或桌面 MCP 客户端。

WebMCP 目前仍是 Chrome 实验功能。在线演示已加入 Chrome 149–156 Origin Trial；本地开发需要开启下文所列的测试开关。

在线体验

使用 Chrome 打开 Cesium Agent Lab。状态面板应显示 WebMCP 已就绪 — 已注册 61 个页面工具。

演示中有两条彼此独立的 AI 路径：

兼容的浏览器智能体可以发现页面注册的 WebMCP 工具。
内置聊天演示托管的 function calling 智能体，在 WebMCP 不可用时仍可使用。

内置聊天只是在线演示提供的便利功能，并不是在自己的应用中使用 cesium-mcp-webmcp 的必要条件。

HTTPS 在线演示还为明确批准的 HTTP 测试数据配置了一个保持目录结构的窄范围代理。它属于应用基础设施，不属于 WebMCP 包。其他 HTTP 地址会得到清晰的 Mixed Content 提示；生产应用应优先使用 HTTPS 数据源，或自行维护服务端白名单。

接入已有 Cesium 应用

bash

npm install cesium-mcp-webmcp

宿主应用已经拥有 cesium 和 Viewer。Bridge 与共享契约会作为依赖自动安装，因此已有 CesiumJS 应用只需增加一个包。

创建 Cesium Viewer 后注册工具：

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

const registration = isWebMcpSupported()
  ? await registerCesiumViewerWebMcp(viewer, {
      toolsets: 'all',
      excludeTools: ['geocode'],
    })
  : undefined

// 页面或组件卸载时调用。
registration?.unregister()

registerCesiumViewerWebMcp() 默认注册包含 15 个工具的 core 选择。使用 toolsets: 'all' 可注册全部 61 个浏览器安全工具，也可以只选择页面需要的工具集：

await registerCesiumViewerWebMcp(viewer, {
  toolsets: ['view', 'entity', 'layer'],
})

12 个可用工具集为：view、entity、layer、camera、entity-ext、animation、scene、tiles、interaction、trajectory、heatmap 和 geolocation。

应用自行负责的能力

Bridge 可以直接执行 61 个浏览器安全契约中的 60 个。geocode 会访问外部服务，因此需要应用提供处理函数：

await registerCesiumViewerWebMcp(viewer, {
  toolsets: 'all',
  bridgeOptions: {
    executors: {
      geocode: params => yourGeocoder(params),
    },
  },
})

setIonToken 有意不作为页面工具暴露。Cesium ion token 和模型服务 API key 都应由应用管理。不要把私钥放入工具 schema、工具结果或浏览器存储中。

本地测试

打开 chrome://flags/#enable-webmcp-testing，启用 WebMCP 测试功能。
启用 chrome://flags/#devtools-webmcp-support，用于在 DevTools 中检查工具。
重启 Chrome。
运行独立接入示例：

bash

npm install
npm run build
npm run dev -w examples/webmcp-integration

打开本地地址，在 DevTools → Application → WebMCP 中检查和执行工具。

Origin Trial 期间，如果要部署到 HTTPS 生产环境，需要为最终使用的准确 origin 申请 Chrome WebMCP Origin Trial，并通过页面元数据或响应头提供 token。

能力检测与清理

并非所有浏览器都支持 WebMCP。应用应在没有 WebMCP 时仍能正常使用，把工具注册作为渐进增强：

if (isWebMcpSupported()) {
  const registration = await registerCesiumViewerWebMcp(viewer)
  // 保存 registration，并在页面销毁时取消注册。
}

该包只面向原生 document.modelContext API，不会安装 polyfill。

在 React StrictMode 中，应从组件生命周期传入独立的取消信号。组件清理时，它会立即注销已经注册的工具，并阻止尚未完成的批量注册继续占用同名工具：

useEffect(() => {
  if (!viewer || !isWebMcpSupported()) return

  const controller = new AbortController()
  void registerCesiumViewerWebMcp(viewer, {
    toolsets: 'all',
    signal: controller.signal,
  }).catch(error => {
    if (!controller.signal.aborted) console.error(error)
  })

  return () => controller.abort()
}, [viewer])

如果只想检查最终生成的工具对象而不立即注册，或者应用需要自行调用 document.modelContext.registerTool() 并传入额外选项，可以使用 buildCesiumWebMcpTools()。

这个包不包含什么

不包含后端 MCP 服务
不包含 WebSocket 传输层
不包含 AI 模型或聊天界面
不打包 CesiumJS runtime
不负责凭据管理

如果要从 Claude Desktop、Cursor 或 VS Code 调用 Cesium，请使用 cesium-mcp-runtime。完整的 npm + Vite 接入可参考 examples/webmcp-integration。

WebMCP 浏览器接入 ​

在线体验 ​

接入已有 Cesium 应用 ​

应用自行负责的能力 ​

本地测试 ​

能力检测与清理 ​

这个包不包含什么 ​