{
  "markdown": "> [!IMPORTANT]\n> ## 📣 作者正在求职 · 北京\n>\n> **AI 应用开发 · Agent 应用开发 · AI 产品全栈**\n>\n> 我是高鹏彬，有约 6 年软件开发经验。如果你们团队正在招人，欢迎联系，也感谢帮忙内推或转发！\n>\n> ### [📄 查看简历 PDF](https://laogao.xyz/platform-api/public/resume/gaopengbin-ai-20260906.pdf)　·　[✉️ 联系我](mailto:1804287165@qq.com)\n>\n> [查看我的项目与个人介绍 →](https://github.com/gaopengbin) · 邮箱：**1804287165@qq.com**\n\n> [!TIP]\n> **📣 Built with Cesium MCP? / 谁在使用 Cesium MCP？**\n>\n> Share your project, screenshots, or feedback—work in progress is welcome! / 欢迎分享项目、截图和使用反馈，开发中的作品也欢迎！\n>\n> **[Share / 分享 → Issue #44](https://github.com/gaopengbin/cesium-mcp/issues/44)** · [Discussion / 讨论区](https://github.com/gaopengbin/cesium-mcp/discussions/43)\n\n<img width=\"2172\" height=\"724\" alt=\"ChatGPT Image 2026年7月5日 22_13_19\" src=\"https://github.com/user-attachments/assets/098dcbef-e0bc-4214-8adf-b80a29e50e65\" />\n<div align=\"center\">\n  <p><strong>A protocol-agnostic Cesium AI control runtime for MCP, WebMCP, function calling, and browser agents</strong></p>\n\n  <p><a href=\"packages/cesium-mcp-bridge/\">cesium-mcp-bridge</a> is the protocol-agnostic Cesium command executor. Separate adapters expose it to <strong>browser-only agents</strong>, <strong>WebMCP browser agents</strong>, <strong>function calling</strong>, or <strong>MCP</strong> — your choice.</p>\n\n  <p>Four integration paths: <a href=\"examples/browser-agent/\">Browser Agent</a> (simplest, zero backend) · WebMCP (page-local browser tools) · function calling (embed in your web app) · <a href=\"packages/cesium-mcp-runtime/\">MCP runtime</a> (Claude Desktop / Cursor / Dify)</p>\n\n  <p>The local Runtime is only required for external MCP hosts. Browser Agent, WebMCP, and function-calling integrations execute the same commands directly in the web application.</p>\n\n  <p><a href=\"https://cesium-browser-agent.pages.dev/\"><strong>Try it now</strong></a> — open the live browser demo, no install, no signup.</p>\n\n  <p>\n    <a href=\"https://gaopengbin.github.io/cesium-mcp/\">Website</a> &middot;\n    <a href=\"README.zh-CN.md\">中文</a> &middot;\n    <a href=\"https://gaopengbin.github.io/cesium-mcp/guide/getting-started.html\">Getting Started</a> &middot;\n    <a href=\"https://gaopengbin.github.io/cesium-mcp/api/bridge.html\">API Reference</a>\n  </p>\n\n  <p>\n    <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-155EEF?style=flat-square\" alt=\"License: MIT\"></a>\n    <a href=\"https://github.com/gaopengbin/cesium-mcp/actions/workflows/ci.yml\"><img src=\"https://img.shields.io/github/actions/workflow/status/gaopengbin/cesium-mcp/ci.yml?branch=main&label=CI&style=flat-square\" alt=\"CI\"></a>\n    <a href=\"https://github.com/gaopengbin/cesium-mcp/stargazers\"><img src=\"https://img.shields.io/github/stars/gaopengbin/cesium-mcp?style=flat-square\" alt=\"GitHub stars\"></a>\n    <a href=\"https://www.npmjs.com/package/cesium-mcp-runtime\"><img src=\"https://img.shields.io/npm/dm/cesium-mcp-runtime?label=runtime%20downloads&style=flat-square\" alt=\"Runtime downloads\"></a>\n  </p>\n\n  <p>\n    <a href=\"https://www.npmjs.com/package/cesium-mcp-bridge\"><img src=\"https://img.shields.io/badge/bridge-npm-528bff?style=for-the-badge&logo=npm&logoColor=white\" alt=\"bridge npm\"></a>\n    <a href=\"https://www.npmjs.com/package/cesium-mcp-runtime\"><img src=\"https://img.shields.io/badge/runtime-npm-155EEF?style=for-the-badge&logo=npm&logoColor=white\" alt=\"runtime npm\"></a>\n    <a href=\"https://www.npmjs.com/package/cesium-mcp-dev\"><img src=\"https://img.shields.io/badge/dev-npm-364fc7?style=for-the-badge&logo=npm&logoColor=white\" alt=\"dev npm\"></a>\n  </p>\n</div>\n\n---\n\n## Demo\n\nhttps://github.com/user-attachments/assets/8a40565a-fcdd-47bf-ae67-bc870611c908\n\n## Packages & Entry Points\n\n| Module | Role | Status | Links |\n|--------|------|--------|-------|\n| **cesium-mcp-contracts** | Transport-neutral names, descriptions, and JSON Schemas for browser tools | New shared layer | [source](packages/cesium-mcp-contracts/) |\n| **cesium-mcp-bridge** | Protocol- and transport-free Cesium command executor (60+ commands) | Mainline, actively iterated | [![npm](https://img.shields.io/npm/v/cesium-mcp-bridge)](https://www.npmjs.com/package/cesium-mcp-bridge) · [source](packages/cesium-mcp-bridge/) |\n| **cesium-mcp-webmcp** | One-package Viewer integration plus the native `document.modelContext` adapter | Browser integration | [source](packages/cesium-mcp-webmcp/) |\n| **examples/webmcp-integration** | Focused npm + Vite integration without a chat UI or MCP server | Developer example | [example](examples/webmcp-integration/) |\n| **examples/browser-agent** | Browser-only AI agent with automatic WebMCP exposure | Recommended | [example](examples/browser-agent/) · [live demo](https://cesium-browser-agent.pages.dev/) |\n| **cesium-mcp-runtime** | MCP server (stdio + HTTP) | Stable MCP SDK v2 | [![npm](https://img.shields.io/npm/v/cesium-mcp-runtime)](https://www.npmjs.com/package/cesium-mcp-runtime) · [source](packages/cesium-mcp-runtime/) |\n| **cesium-mcp-dev** | CesiumJS API knowledge base for coding assistants | Maintained | [![npm](https://img.shields.io/npm/v/cesium-mcp-dev)](https://www.npmjs.com/package/cesium-mcp-dev) · [source](packages/cesium-mcp-dev/) |\n\n> **Which one?** Personal project or quick try → browser-agent. Let a compatible browser agent discover page-local Cesium tools → WebMCP. Existing web app embedding an AI assistant → bridge + your own function calling. Calling from Claude Desktop / Cursor / Dify → MCP runtime.\n\n## Architecture\n\n```mermaid\nflowchart LR\n  subgraph clients [\"AI Drivers (pick one)\"]\n    BA[\"Browser Agent\\n(in the same page)\"]\n    WM[\"WebMCP Agent\\n(browser-provided)\"]\n    FC[\"Your web app\\nfunction calling\"]\n    MCP[\"Claude / Cursor / Dify\\nvia MCP runtime\"]\n  end\n\n  CONTRACTS[\"cesium-mcp-contracts\\ntool definitions\"]\n  WEBMCP[\"cesium-mcp-webmcp\\nnative adapter\"]\n\n  subgraph core [\"cesium-mcp-bridge (browser)\"]\n    B[\"60+ tools\\nprotocol-agnostic dispatcher\"]\n    C[\"CesiumJS Viewer\"]\n  end\n\n  CONTRACTS -.-> BA\n  CONTRACTS -.-> WEBMCP\n  BA -- \"in-page call\" --> B\n  WM -- \"document.modelContext\" --> WEBMCP\n  WEBMCP --> B\n  FC -- \"in-page call\" --> B\n  MCP -- \"WebSocket / JSON-RPC\" --> B\n  B --> C\n\n  style clients fill:#1e293b,stroke:#528bff,color:#e2e8f0\n  style core fill:#1e293b,stroke:#12B76A,color:#e2e8f0\n```\n\nThe bridge remains the execution core, while contracts and protocol adapters stay separate. Pick whichever driver matches your scenario — they all reach the same Cesium command layer. On WebMCP-capable browsers, `cesium-mcp-webmcp` can expose 61 browser-safe commands in 12 selectable toolsets through `document.modelContext` without adding an MCP transport or backend server.\n\n### Relationship to the CesiumGS AI ecosystem\n\nCesiumGS's newer AI work is split between [`cesiumjs-ai-starter-app`](https://github.com/CesiumGS/cesiumjs-ai-starter-app), a deployable application template, and [`cesiumjs-skills`](https://github.com/CesiumGS/cesiumjs-skills), development-time guidance for coding agents. The earlier [`cesium-ai-integrations`](https://github.com/CesiumGS/cesium-ai-integrations) repository contains the first-generation experiments and community contributions that helped explore this space.\n\n`cesium-mcp` is an independent runtime and integration toolkit, not a continuation of the earlier WebSocket-only reference architecture. Its reusable Bridge and shared contracts work unchanged across browser-only function calling, native WebMCP, standard MCP over stdio/HTTP, and embedded desktop shells. A local WebSocket bridge is used only when an external MCP host needs to reach a live browser Viewer; it is not required for the hosted demo or page-local integrations.\n\nThe project author was an early contributor to `CesiumGS/cesium-ai-integrations`, contributing the Imagery server, Terrain server, and unified MCP Gateway. Those experiments informed this project's multi-protocol architecture, while the implementation, release lifecycle, and roadmap remain independent.\n\n## Quick Start\n\n### Path 0 — Try in 30 seconds (browser agent, recommended)\n\nOpen the [live demo](https://cesium-browser-agent.pages.dev/) and ask—the hosted model is ready without a browser API key:\n> *\"Fly to the Eiffel Tower and drop a red marker\"*\n\nFork the [examples/browser-agent](examples/browser-agent/) folder to deploy your own.\n\n### Path 1 — Expose Cesium tools through WebMCP (Chrome 149+ experimental)\n\nThe browser-agent example automatically registers all 61 browser-safe page tools when `document.modelContext` is available. Its built-in chat uses automatic toolset routing to keep each normal request at 20 tools or fewer, while still offering explicit core, single-toolset, and all-61 modes:\n\n```bash\nnpm run build -w packages/cesium-mcp-bridge\nnpm run build -w packages/cesium-mcp-webmcp\nnpx serve . -l 4173\n```\n\nOpen `http://localhost:4173/examples/browser-agent/`, click **Start**, then inspect or execute the tools in DevTools → Application → WebMCP. Enable `#enable-webmcp-testing` and `#devtools-webmcp-support` in `chrome://flags` for local testing.\n\nApplication developers install the adapter separately. End users only open the integrated website; they do not install npm packages or run an MCP server.\n\n```bash\nnpm install cesium-mcp-webmcp\n```\n\n```js\nimport { registerCesiumViewerWebMcp } from 'cesium-mcp-webmcp/viewer'\n\nconst registration = await registerCesiumViewerWebMcp(viewer, {\n  toolsets: 'all',\n  excludeTools: ['geocode'], // add your own browser geocoder to expose this tool\n})\n\n// Later, if the page is unmounted:\nregistration.unregister()\n```\n\nSee the [WebMCP adapter API](packages/cesium-mcp-webmcp/README.md) for custom integrations.\nFor a complete npm + Vite application, start from the [WebMCP integration example](examples/webmcp-integration/).\n\n### Path 2 — Embed in your own web app (function calling)\n\n```bash\nnpm install cesium-mcp-bridge\n```\n\n```js\nimport { CesiumBridge } from 'cesium-mcp-bridge';\n\nconst bridge = new CesiumBridge(viewer);\n// Then: send the bridge's tool schema to any LLM that supports function/tool calling,\n// route the model's tool calls to bridge.execute(name, params).\n```\n\nSee [examples/browser-agent/index.html](examples/browser-agent/index.html) for a complete loop with OpenAI-compatible APIs.\n\n### Path 3 — Use from Claude Desktop / Cursor / Dify (MCP)\n\nOrdinary MCP users need only the Runtime package. It includes the browser Bridge bundle and a built-in Viewer at `http://localhost:9100/`; install `cesium-mcp-bridge` separately only when integrating a custom page.\n\n```bash\n# Stable channel — npm latest, MCP SDK v2\nnpx -y cesium-mcp-runtime\n\n# HTTP mode\nnpx -y cesium-mcp-runtime --transport http --port 3000\n```\n\nThe stable release serves existing MCP `2025-11-25` clients and the new\n`2026-07-28` protocol from the same stdio/HTTP entry. It uses the stable\nTypeScript SDK v2 and passes the official `server-stateless` conformance\nscenario (28/28).\n\nMCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"cesium\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"cesium-mcp-runtime\"]\n    }\n  }\n}\n```\n\n## 62 Available Command Tools\n\nTools are organized into **12 toolsets**. Default mode enables 4 core toolsets (30 tools). Set `CESIUM_TOOLSETS=all` for everything, or let the AI discover and activate toolsets dynamically at runtime.\n\n> **Canonical contracts**: Tool descriptions default to English; set `CESIUM_LOCALE=zh-CN` for Chinese. Titles, behavior annotations, localized descriptions, defaults, input validation, MCP output schemas, and structured results all come from the shared JSON Schemas in `cesium-mcp-contracts`. Text `content` remains available for older clients.\n\n| Toolset | Tools |\n|---------|-------|\n| **view** (default) | `flyTo`, `setView`, `getView`, `zoomToExtent`, `saveViewpoint`, `loadViewpoint`, `listViewpoints`, `exportScene` |\n| **entity** (default) | `addMarker`, `addLabel`, `addModel`, `addPolygon`, `addPolyline`, `updateEntity`, `removeEntity`, `batchAddEntities`, `queryEntities`, `getEntityProperties` |\n| **layer** (default) | `addGeoJsonLayer`, `addGeoJsonPrimitive`, `listLayers`, `removeLayer`, `clearAll`, `setLayerVisibility`, `updateLayerStyle`, `getLayerSchema`, `setBasemap` |\n| **interaction** (default) | `screenshot`, `highlight`, `measure` |\n| camera | `lookAtTransform`, `startOrbit`, `stopOrbit`, `setCameraOptions` |\n| entity-ext | `addBillboard`, `addBox`, `addCorridor`, `addCylinder`, `addEllipse`, `addRectangle`, `addWall` |\n| animation | `createAnimation`, `controlAnimation`, `removeAnimation`, `listAnimations`, `updateAnimationPath`, `trackEntity`, `controlClock`, `setGlobeLighting` |\n| tiles | `load3dTiles`, `load3dGaussianSplat`, `loadTerrain`, `loadImageryService`, `loadCzml`, `loadKml`, `setEdgeDisplayMode` |\n| trajectory | `playTrajectory` |\n| heatmap | `addHeatmap` |\n| scene | `setSceneOptions`, `setPostProcess`, `setIonToken` (Runtime only) |\n| geolocation | `geocode` |\n\n## Examples\n\nSee [examples/minimal/](examples/minimal/) for a complete working demo.\n\n## Development\n\n```bash\ngit clone https://github.com/gaopengbin/cesium-mcp.git\ncd cesium-mcp\nnpm install\nnpm run build\nnpm test\nnpm run test:contracts\nnpm run test:schema-compat\nnpm run test:routing\nnpm run test:model-tools\nnpm run eval:model-tools\nnpm run test:e2e:packed\n```\n\n`test:contracts` is the focused parity gate for MCP Runtime metadata, WebMCP registration, Function Calling definitions, provider Schema portability, and the 60-tool Bridge Executor Registry. Run `test:schema-compat` directly for actionable OpenAI, Azure, VS Code MCP, and WebMCP Schema diagnostics.\n`test:routing` evaluates bilingual and multi-intent Browser Agent requests across all 12 toolsets, checking required-tool recall and the 20-tool automatic-routing budget.\n`test:model-tools` verifies the provider-neutral multi-turn scoring harness. `eval:model-tools` performs a no-network routing preflight by default; add an explicit provider and `--live` to measure real tool choice, argument validity, and required-tool completion. See [Model Tool Evaluation](docs/guide/model-tool-evaluation.md).\n`test:e2e:packed` builds npm tarballs, installs them in a clean temporary project, opens the real Cesium Viewer, and verifies a Runtime-WebSocket-Bridge command round trip.\n\n## Version Policy\n\nVersion format: `{CesiumMajor}.{CesiumMinor}.{MCPPatch}`\n\n| Segment | Meaning | Example |\n|---------|---------|--------|\n| `1.143` | Tracks CesiumJS version — built & tested against Cesium `~1.143.0` | `1.143.0` → Cesium 1.143 |\n| `.x` | MCP patch — independent iterations for new tools, bug fixes, docs | `1.143.0` → `1.143.1` |\n\nOfficial CesiumJS releases are reviewed before the compatibility baseline is bumped; the project does not automatically claim support for a newer release without Bridge verification.\n\n## Related Projects\n\n- [mapbox-mcp](https://github.com/gaopengbin/mapbox-mcp) — AI control for Mapbox GL JS\n- [openlayers-mcp](https://github.com/gaopengbin/openlayers-mcp) — AI control for OpenLayers\n\n## Community\n\nThis project recognizes [LINUX DO](https://linux.do/) as a community for open-source exchange, technical discussion, and developer feedback.\n\n## Star History\n\n[![Star History Chart](https://raw.githubusercontent.com/gaopengbin/cesium-mcp/star-history-data/.github/star-history/chart.svg)](https://github.com/gaopengbin/cesium-mcp)\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 15320,
  "sha": "efc3ec413c42d0d13a69b84b6a87585e2407d86f4b20e07840601303c0a74d5e",
  "repo_slug": "gaopengbin/cesium-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_gaopengbin_cesium_mcp_runtime_9b1eb0df/readme"
}