feat: add imagery-server with imagery_add, imagery_remove, imagery_list tools by gaopengbin · Pull Request #22 · CesiumGS/cesium-ai-integrations

gaopengbin · 2026-03-18T08:01:57Z

Summary

Adds a new imagery-server MCP server that provides 3 tools for managing CesiumJS imagery layers through AI interactions.

imagery_server.mp4

New Tools

Tool	Description
`imagery_add`	Add imagery layers with 10 provider types
`imagery_remove`	Remove layers by index, name, or remove all
`imagery_list`	List all current imagery layers with details

Supported Provider Types

UrlTemplate, WMS, WMTS, ArcGisMapServer, BingMaps, TileMapService, OpenStreetMap, SingleTile, Ion, MapboxStyle

Architecture

Server-side (servers/imagery-server/): Full MCP server with Zod v4 schema validation, WebSocket communication on port 3005
Client-side (test-applications/):
- ImageryManager in client-core handles all 3 commands in the browser
- Supports both sync constructors and async fromUrl() factory patterns (CesiumJS 1.134+)
- Registered alongside existing Camera, Entity, and Animation managers
- Web-app configured with MCP_IMAGERY_PORT=3005

Quality

68 unit tests with coverage: 100% statements / 96.42% branches / 100% functions / 100% lines
Zero ESLint errors, Prettier formatted
TypeScript strict mode — zero compilation errors
End-to-end tested: WebSocket connection verified, all 3 commands tested in live CesiumJS browser environment

Files Changed

Server (19 new files):

servers/imagery-server/ — package.json, tsconfig, vitest config
src/index.ts — Server entry point (port 3005)
src/schemas/ — Zod v4 schemas for providers, tools, responses
src/tools/ — imagery-add, imagery-remove, imagery-list handlers
src/utils/ — Type definitions
test/ — 4 test files covering schemas, add, remove, list

Client (6 modified/new files):

client-core/src/managers/imagery-manager.ts — NEW: Browser-side handler
client-core/src/cesium-app.ts — Register ImageryManager
web-app/src/app.ts — Add Imagery Server to MCP server list
web-app/.env.example — Add MCP_IMAGERY_PORT
web-app/esbuild.config.cjs — Add port define

Port Allocation

Server	Port
Camera	3002
Entity	3003
Animation	3004
Imagery	3005

MKartaviciute · 2026-03-19T09:13:15Z

Could you add README.md for this mcp server to match other mcp servers, also list a new mcp server under those READMEs: https://github.com/CesiumGS/cesium-ai-integrations/blob/main/mcp/README.md
https://github.com/CesiumGS/cesium-ai-integrations/blob/main/mcp/cesium-js/README.md

MKartaviciute · 2026-03-19T09:18:16Z

There are some formatting issues: https://github.com/CesiumGS/cesium-ai-integrations/actions/runs/23234847210/job/67715534364?pr=22
You can run pnpm run format for formatting and pnpm run check to check if it pass formatting and linting

gaopengbin · 2026-03-19T09:57:22Z

Thanks for the review feedback! All issues have been addressed:

Commit 69a43f7:

Added servers/imagery-server/README.md with full tool documentation (3 tools, 10 provider types, MCP client config, environment variables)
Listed imagery-server in mcp/README.md (table, getting started, architecture tree)
Listed imagery-server in mcp/cesium-js/README.md (packages, tools, structure, build/run commands, MCP config)
Fixed Prettier formatting in imagery-manager.ts

Commit 79aad8b:

Fixed Prettier table column alignment in mcp/cesium-js/README.md

All 3 CI checks are now passing. Thanks for the reminder about running pnpm run format and pnpm run check — I'll make sure to do that before pushing in the future!

MKartaviciute · 2026-03-19T12:24:19Z

+  Rectangle,
+} from "cesium";
+
+export interface ImageryAddResult extends MCPCommandResult {


move interfaces into separate file under types folder

gaopengbin · 2026-03-19T16:04:40Z

Hi @MKartaviciute, all 6 comments addressed in this push:

Provider type names — switch cases now use the full schema names (UrlTemplateImageryProvider, etc.) and getProviderTypeName() returns consistent names too.
Interfaces — moved to types/imagery-types.ts.
Unit tests — added 23 tests for imagery-manager (all providers, add/remove/list, edge cases).
assetId & key — added both to ImageryAddInputSchema and wired through the tool handler.
url & ready — listImagery() now populates them from the layer/provider.
.env.example — done, same pattern as other servers.

Also updated the README to document assetId and key params.

…st tools Server-side (servers/imagery-server/): - 3 MCP tools: imagery_add, imagery_remove, imagery_list - 10 imagery provider types: UrlTemplate, WMS, WMTS, ArcGisMapServer, BingMaps, TileMapService, OpenStreetMap, SingleTile, Ion, MapboxStyle - Zod v4 schema validation for all tool inputs - WebSocket communication on port 3005 - 68 unit tests with 100%/96%/100%/100% coverage - ESLint and Prettier clean Client-side (test-applications/): - ImageryManager in client-core: handles imagery_add/remove/list commands - Supports both sync constructors and async fromUrl() factory patterns - Registered in cesium-app.ts alongside existing managers - web-app configured with MCP_IMAGERY_PORT=3005 Port fix: changed default from 3004 to 3005 to avoid conflict with Animation Server

- Add README.md for imagery-server with full tool documentation - Add imagery-server to mcp/README.md (table, getting started, architecture) - Add imagery-server to mcp/cesium-js/README.md (packages, tools, build, run, config) - Fix prettier formatting in imagery-manager.ts

…nd missing fields - Align switch cases with ImageryProviderTypeSchema full names - Extract interfaces to types/imagery-types.ts - Add 23 unit tests for imagery-manager - Add assetId and key fields to ImageryAddInputSchema - Populate url and ready in listImagery response - Add .env.example for imagery-server - Update README with assetId and key params

gaopengbin · 2026-03-20T08:33:09Z

Hi @MKartaviciute 👋

I've rebased to the latest main and all review feedback has been addressed in the previous commit (fix: address code review feedback). Summary of changes:

✅ Provider type names aligned (IonImageryProvider → IonImageryProviderConfig, etc.)
✅ Interfaces extracted to types/ directory
✅ 68 unit tests with full coverage (100% statements / 96.42% branches / 100% functions / 100% lines)
✅ assetId / key included in schema definitions
✅ url / ready properly populated in imagery_list response
✅ .env.example includes all 5 standard environment variables

All CI checks are green. Would appreciate a re-review when you have a moment. Thanks! 🙏

MKartaviciute · 2026-03-23T08:14:12Z

Hi @gaopengbin — I’ve left a few more comments.
Thanks for helping add this functionality!

- Use buildSuccessResponse helper in imagery-list for consistency - Fix removedCount reporting 1 on empty removeAll (now returns 0) - Make url field optional in schema (not required for IonImageryProvider) - Replace GoogleEarthEnterpriseImageryProvider fallback with proper fromMetadata implementation and add to getProviderTypeName detection - Add unit tests for empty removeAll and GoogleEarthEnterprise provider - Update affected tests for new response format and optional url

MKartaviciute · 2026-03-23T12:54:12Z

@gaopengbin Looks good!. Approved PR.

MKartaviciute self-requested a review March 19, 2026 09:49

MKartaviciute reviewed Mar 19, 2026

View reviewed changes

gaopengbin added 4 commits March 20, 2026 16:25

style: fix prettier table alignment in cesium-js README

da017ee

gaopengbin force-pushed the feat/imagery-server branch from d6b7fc3 to 07ae80a Compare March 20, 2026 08:30

MKartaviciute reviewed Mar 23, 2026

View reviewed changes

gaopengbin force-pushed the feat/imagery-server branch 2 times, most recently from 412c943 to a01cfb3 Compare March 23, 2026 10:17

gaopengbin force-pushed the feat/imagery-server branch from a01cfb3 to 1ab32ed Compare March 23, 2026 10:25

MKartaviciute approved these changes Mar 23, 2026

View reviewed changes

MKartaviciute merged commit d20e554 into CesiumGS:main Mar 23, 2026
3 checks passed

gaopengbin mentioned this pull request Mar 29, 2026

Add Terrain Management mcp server #29

Closed

Conversation

gaopengbin commented Mar 18, 2026 • edited by MKartaviciute Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

New Tools

Supported Provider Types

Architecture

Quality

Files Changed

Port Allocation

Uh oh!

MKartaviciute commented Mar 19, 2026

Uh oh!

MKartaviciute commented Mar 19, 2026

Uh oh!

gaopengbin commented Mar 19, 2026

Uh oh!

Uh oh!

MKartaviciute Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

gaopengbin commented Mar 19, 2026

Uh oh!

gaopengbin commented Mar 20, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MKartaviciute commented Mar 23, 2026

Uh oh!

MKartaviciute commented Mar 23, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gaopengbin commented Mar 18, 2026 •

edited by MKartaviciute

Loading