Watch

History

Repository files (latest commit first)
Filename	Latest commit message	Latest commit date
Olivier Chafik cce8d5c7a3 docs: add MCP client configuration to example READMEs Add stdio transport configuration snippets near the top of each example README to help users quickly set up the servers in their MCP clients. - Node.js examples use npx with the published npm packages - Python qr-server uses uv with local path - Removed Claude Desktop-specific references from qr-server		2026-01-16 14:00:57 +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	docs: add MCP client configuration to example READMEs	2026-01-16 14:00:57 +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

Interactive 3D globe viewer using CesiumJS with OpenStreetMap tiles. Demonstrates geocoding integration and full MCP App capabilities.

MCP Client Configuration

Add to your MCP client configuration (stdio transport):

{
  "mcpServers": {
    "map": {
      "command": "npx",
      "args": [
        "-y",
        "--silent",
        "--registry=https://registry.npmjs.org/",
        "@modelcontextprotocol/server-map",
        "--stdio"
      ]
    }
  }
}

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-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

server.ts - MCP server with geocode and show-map tools
mcp-app.html / src/mcp-app.ts - CesiumJS globe UI
server-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