modelcontextprotocol/ext-apps
Watch
1
0
Fork
You've already forked ext-apps
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ext-apps/examples/map-server
History
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Olivier Chafik 8c3b1daf7e
 chore: bump version to 0.4.1 (#282)
2026-01-15 16:11:53 +00:00
..
src fix(examples): improve updateModelContext with structured YAML frontmatter (#271) 2026-01-14 22:08:09 +00:00
.gitignore Improve consistency and organization of examples for AI learning 2026-01-13 20:48:02 -06:00
grid-cell.png feat(basic-host): URL params, fullscreen mode, unified layout (#266) 2026-01-14 22:09:41 +00:00
main.ts feat: compile example servers to JavaScript for npm consumption (#259) 2026-01-14 23:46:17 +00:00
mcp-app.html examples: Add CesiumJS Map App example (#235) 2026-01-12 12:13:56 +00:00
package.json chore: bump version to 0.4.1 (#282) 2026-01-15 16:11:53 +00:00
README.md feat: add example gallery with auto-generated screenshots (#253) 2026-01-13 15:12:18 +00:00
screenshot.png feat(basic-host): URL params, fullscreen mode, unified layout (#266) 2026-01-14 22:09:41 +00:00
server.ts fix(examples): resolve DIST_DIR path for npm package execution (#277) 2026-01-15 12:23:13 +00:00
test-standalone.html examples: Add CesiumJS Map App example (#235) 2026-01-12 12:13:56 +00:00
tsconfig.json examples: Add CesiumJS Map App example (#235) 2026-01-12 12:13:56 +00:00
tsconfig.server.json feat: compile example servers to JavaScript for npm consumption (#259) 2026-01-14 23:46:17 +00:00
vite.config.ts examples: Add CesiumJS Map App example (#235) 2026-01-12 12:13:56 +00:00

README.md

Example: Interactive Map

Screenshot

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

  1. Install dependencies:

    npm install

  2. Build and start the server:

    npm run start:http  # for Streamable HTTP transport
# OR
npm run start:stdio  # for stdio transport

  3. View using the basic-host example 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 limiting
  • show-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

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