| Filename | Latest commit message | Latest commit date |
|---|---|---|
023f1fd233* fix(map-server): simplify location update message format * fix(say-server): pass host to streamable_http_app for non-localhost deployments * refactor(pdf-server): simplify to stateless range-query architecture - Remove caching/indexing in favor of direct HTTP Range requests - Use HEAD requests to get file size (no full download) - Use Range requests to proxy byte chunks (no caching) - Local files: fs.read with offset/length - Remote files: HTTP Range header - Zero memory footprint (no PDF caching) - Truly stateless (no session management needed) - Single server.ts (~350 lines) + main.ts CLI entry point - Instant startup (no preloading) - Security: whitelist local files, allowed origins Removed files: - src/pdf-indexer.ts - src/pdf-loader.ts - src/types.ts * feat(pdf-server): add dark mode support - Add CSS variables with light-dark() function for automatic theme switching - Sync theme with host via applyDocumentTheme() - Apply host CSS variables via applyHostStyleVariables() * feat(pdf-server): add list_pdfs tool back Lists local files and allowed remote origins. Also moves CHUNK_SIZE to module level constant. * feat(pdf-server): improve tool descriptions and increase context limit - display_pdf: list all allowed domains in description - Increase MAX_MODEL_CONTEXT_LENGTH to 15000 - Move CHUNK_SIZE to module level constant * chore(say-server): remove deployment docs from repo Keep server.py fix for non-localhost deployments. Deployment docs kept locally but not in repo. * refactor(pdf-server): simplify updateModelContext format - Add widget ID for multi-widget disambiguation - Use concise header: 'PDF viewer (id) | title | Current Page: X/Y' - Add 'Page content:' prefix before text - Keep selection markers (<pdf-selection>...</pdf-selection>) * refactor: rename widgetUUID to viewUUID for consistency Aligns with main's standardization on 'view' terminology (PR #325). Also dynamically generate allowed domains in display_pdf description. * viewUUID * fix(map-server): fix syntax error in location update message * fix(pdf-server): restore package.json, improve server docs - Restore --external pdfjs-dist in build - Rewrite server.ts header for newcomers (list tools, not implementation details) - Minimize main.ts diff * chore(pdf-server): remove unused addAllowedOrigin/addAllowedLocalFile * docs(pdf-server): update README for new architecture * docs(pdf-server): restore full README, add theming section, remove get_pdf_info * rm * fix(pdf-server): restore createMcpExpressApp and error handling - Use createMcpExpressApp for DNS rebinding protection - Restore error callback in app.listen() * fix(say-server): pass host to streamable_http_app for non-localhost deployments * chore(say-server): remove deployment docs from repo * widgetId->tool id * fix(map-server): add null check for center in location update chore(pdf-server): dedupe and sort allowed origins * fix(map-server): use transparent background for rounded corners * prettier |
||
| .. | ||
| src | ||
| .gitignore | ||
| grid-cell.png | ||
| main.ts | ||
| mcp-app.html | ||
| package.json | ||
| README.md | ||
| screenshot.png | ||
| server.ts | ||
| test-standalone.html | ||
| tsconfig.json | ||
| tsconfig.server.json | ||
| vite.config.ts | ||
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-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