366aa9b66e* feat: Add CesiumJS map server example A WebGL-based 3D globe example that demonstrates: - CesiumJS integration with MCP Apps - CSP configuration for external tile servers - worker-src directive usage for tile decoding Tools: - geocode: Search places via OpenStreetMap Nominatim - show-map: Display interactive 3D globe at coordinates 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * comment out app.registerTool call for now * prettier * fix error handling in server-utils.ts * refactor: rename cesium-map-server to map-server - Rename examples/cesium-map-server to examples/map-server - Update package name to @modelcontextprotocol/server-map - Add README.md with documentation * style: add min-height of 400px to map container * feat(map-server): add fullscreen support, clean UI, sharp rendering - Add fullscreen toggle button (only shown if host supports it) - Use autoResize: false and manually send height of 400px - Hide Cesium UI controls (home, scene mode picker) - Remove location label (gets stale quickly) - Use full device pixel ratio for sharp rendering on high-DPI displays - Resize Cesium viewer when display mode changes * feat(map-server): add reverse geocoding (logging only) and rounded corners - Add camera move end listener for reverse geocoding - Debounce Nominatim API calls (1.5s) to respect rate limits - Log location name to console on camera move - Add nominatim.openstreetmap.org to CSP connectDomains - Add 8px rounded corners to map container * fix(map-server): fix pixelated rendering on high-DPI displays - Set canvas imageRendering to 'auto' (CesiumJS defaults to pixelated) - Set resolutionScale to window.devicePixelRatio for native resolution * tweaks * update model context w/ current location * fix(map-server): improve rendering quality and add visible extent logging Rendering fixes: - Remove incorrect resolutionScale = devicePixelRatio which was doubling the scaling factor on Retina displays (2x2=4x), causing blurriness - Disable FXAA anti-aliasing which can cause blurriness on high-DPI displays - Keep useBrowserRecommendedResolution: false to use native devicePixelRatio Reverse geocoding improvements: - Add getVisibleExtent() using camera.computeViewRectangle() to get the visible bounding box (west, south, east, north) - Add getScaleDimensions() to calculate visible area in km - Add calculateNominatimZoom() to map visible extent to appropriate Nominatim zoom level (3=country to 18=building) - Log visible extent with dimensions on each camera move - Pass zoom parameter to Nominatim for context-aware geocoding results - Update model context with visible area dimensions * fix(map-server): direct positioning + wait for tiles before showing Changes: - Remove zoom granularity logic from reverse geocoding (was not working) - Keep extent logging in both console and model context - Replace flyTo animation with instant setView positioning - Add waitForTilesLoaded() to detect when tiles finish loading - Keep loading spinner visible until: 1. Tool input positions camera to destination 2. Tiles at destination are fully loaded - Add 5-second fallback timeout if no tool input received - Add 10-second timeout for tile loading to prevent infinite wait * feat(map-server): use viewbox search to find visible places Replace center-point reverse geocoding with Nominatim viewbox search: - Add searchPlacesInBox() that queries Nominatim with bounded viewbox - Uses layer=address&featuretype=settlement to find cities/towns - Returns up to 5 visible places in the current view - Update model context with 'Visible places: City1, City2, ...' - Still includes center coordinates and extent dimensions This provides better context about what's actually visible on the map rather than just the address at the center point. * fix(map-server): use CARTO @2x retina tiles for sharp rendering Root cause: Standard OSM tiles are 256x256 pixels. On Retina displays (devicePixelRatio=2), these get scaled up 2x, making them look pixelated. Solution: Switch to CARTO Voyager tiles which provide @2x retina support: - Detect high-DPI displays using window.devicePixelRatio - Use 512x512 tiles with @2x suffix on Retina displays - Use 256x256 tiles on standard displays - Set tileWidth/tileHeight to match actual tile size - Use CARTO subdomains (a,b,c,d) for load balancing - Update CSP to allow CARTO tile domains CARTO Voyager provides clean OSM-based tiles with free @2x retina support, no API key required. * fix(map-server): use OSM tiles and fix reverse geocoding - Switch back from CARTO to standard OSM tiles (tile.openstreetmap.org) for better detail and label rendering - Fix geocoding: use reverse geocode API instead of search API (search API requires a q= parameter, returns 400 without it) - Update CSP domains for OSM tile server * fix(map-server): use *.openstreetmap.org wildcard in CSP Simplify CSP to use wildcard for both tiles and geocoding: - connectDomains: *.openstreetmap.org covers tile.* and nominatim.* - resourceDomains: *.openstreetmap.org for tile images * feat(map-server): multi-point sampling for visible places - Sample multiple points in visible extent to discover places - Adaptive sampling based on extent size: - < 30km: center only (city zoom) - 30-100km: center + 2 corners - > 100km: center + 4 quadrants - Proper rate limiting for Nominatim (1.1s between requests) - Shows 'Visible places: City1, City2, ...' in model context - Fix: move geocode tool registration inside createServer() * format * fix(map-server): fix Express listen callback + add e2e tests - Fix incorrect Express listen() callback signature (err param doesn't exist) - Add map-server to e2e test suite with SLOW_SERVERS timeout (5s for tiles) - Improve comment about experimental ui/update-model-context API 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2.3 KiB
2.3 KiB
Example: Interactive Map
Interactive 3D globe viewer using CesiumJS with OpenStreetMap tiles. Demonstrates geocoding integration and full MCP App capabilities.
Features
- 3D Globe Rendering: Interactive CesiumJS globe with rotation, zoom, and 3D perspective
- Geocoding: Search for places using OpenStreetMap Nominatim (no API key required)
- OpenStreetMap Tiles: Uses free OSM tile server (no Cesium Ion token needed)
- Dynamic Loading: CesiumJS loaded from CDN at runtime for smaller bundle size
Running
-
Install dependencies:
npm install -
Build and start the server:
npm run start:http # for Streamable HTTP transport # OR npm run start:stdio # for stdio transport -
View using the
basic-hostexample or another MCP Apps-compatible host.
Tools
geocode
Search for places by name or address. Returns coordinates and bounding boxes.
{
"query": "Eiffel Tower"
}
Returns up to 5 matches with lat/lon coordinates and bounding boxes.
show-map
Display the 3D globe zoomed to a bounding box.
{
"west": 2.29,
"south": 48.85,
"east": 2.3,
"north": 48.86,
"label": "Eiffel Tower"
}
Defaults to London if no coordinates provided.
Architecture
Server (server.ts)
Exposes two tools:
geocode- Queries OpenStreetMap Nominatim API with rate limitingshow-map- Renders the CesiumJS globe UI at a specified location
Configures Content Security Policy to allow fetching tiles from OSM and Cesium CDN.
App (src/mcp-app.ts)
Vanilla TypeScript app that:
- Dynamically loads CesiumJS from CDN
- Initializes globe with OpenStreetMap imagery (no Ion token)
- Receives tool inputs via the MCP App SDK
- Handles camera navigation to specified bounding boxes
Key Files
server.ts- MCP server with geocode and show-map toolsmcp-app.html/src/mcp-app.ts- CesiumJS globe UIserver-utils.ts- HTTP server utilities
Notes
- Rate limiting is applied to Nominatim requests (1 request per second per their usage policy)
- The globe works in sandboxed iframes with appropriate CSP configuration
- No external API keys required - uses only open data sources