Xweather Template — Storm Explorer MCP App

A deployable MCP Apps template built with mcp-use@2.5.1, React, @xweather/mapsgl@1.10.1 and maplibre-gl@6.10.0.

A map-only weather app with live storm cells, lightning, forecast layers and up to five monitored places. Search, scene presets, storm details, legend, timeline and assistant follow-up all float over the map. The view requests prefersBorder: true, uses the host's --border-radius-xl, and combines blurred glass surfaces with pill-shaped Fluid Functionalism controls. See business value and use cases.

Live demo

Open Storm Explorer in Manufact Cloud Tools (requires sign-in and access to the Xweather organization) and execute show-weather-dashboard for the three-site view, or show-weather-map to choose a location. You can also connect the public MCP endpoint below to an MCP Apps-compatible client.

MCP endpoint: https://xweather.run.mcp-use.com/mcp
Hosted by: Xweather on Manufact

The shared demo uses a quota-limited Xweather Developer account. Deploy your own copy with your own credentials for continued use. The Xweather logo is bundled in public/xweather.png; deployed apps serve their own copy.

Related MCP server: Weather MCP Service

Deploy to Manufact

The button opens Manufact Cloud, clones this public template into your GitHub account, and starts deployment. Choose your organization and repository name. The template builds with npm run build and starts with npm start -- --host 0.0.0.0 on port 3000. Production serves the MCP endpoint and app assets without mounting the embedded Inspector. Preview the app in your server's Manufact Cloud Tools tab; local development includes the Inspector.

A deployment without Xweather credentials starts in labelled sample mode. To enable live weather, add these environment variables in the server's Environment Variables settings and redeploy:

Create credentials in the Xweather Developer Portal. Restrict the browser credential to the MCP host iframe origins you intend to support. Manufact Cloud's Tools preview uses manufact.com, which needs its own allowed-domain entry. Local development uses localhost and 127.0.0.1. Previous credential rejections can remain cached by Xweather's map service for ten minutes after a domain change; reload the preview after that cache expires. Never put server credentials in the browser fields or commit credentials to GitHub. Deployment environment variables stay in Manufact, outside the repository.

To deploy from the CLI instead:

npm ci
npx mcp-use login
npx mcp-use org list
npx mcp-use deploy --org YOUR_ORG_SLUG --name xweather \
  --env-file .env \
  --build-command 'npm run build' \
  --start-command 'npm start -- --host 0.0.0.0'

Manufact stores the project link in ignored .mcp-use/project.json. Subsequent npx mcp-use deploy runs target that server. Set an available custom slug under the server's domain settings, then redeploy to activate it.

Client preferences

Both apps follow the host's light/dark theme, including the basemap, glass controls, popovers, tooltips and legend text. Theme changes retain the current map view and playback state. The host locale formats dates, times, numbers and map labels, and sets the initial metric/imperial units; the units button remains an explicit override. Controls are translated into English, German, French, Italian and Spanish, with English fallback for other languages. Provider condition descriptions and official alerts retain their source wording. Times remain local to the displayed place, with its timezone shown on the timeline.

Omit location / locations to use the approximate location supplied in tool-call _meta["openai/userLocation"], read through ctx.client.user(). Valid latitude/longitude takes priority over a city/region/country hint. Explicit tool arguments always win. With no usable location hint, the map falls back to Dallas and the multi-place view to Dallas/Arlington/Plano. The app does not request browser geolocation or infer location from the locale/timezone. The request's openai/locale is used until the app host supplies its locale.

Official Xweather proxy demo

A separate Xweather Official server in Manufact proxies https://mcp.api.xweather.com/mcp through Manufact's native external-server gateway. It preserves Xweather's own 19 tools and raster-map MCP App. This template's MapsGL views are a separate implementation.

Proxy endpoint: https://fast-steel-rlb8y.run.mcp-use.com/mcp. Xweather authentication is still required by the upstream service. The signed-in Cloud demo uses the configured demo account. No upstream service code is copied or redeployed.

Run locally

Requires Node.js 22.22.2 or newer.

npm ci
# On a new checkout only; preserve an existing configured .env:
cp .env.example .env
npm run dev

Open the Inspector. Execute either map tool without location arguments to use client-supplied location hints. With no hints, show-weather-dashboard shows Dallas, Arlington and Plano, and show-weather-map shows Dallas. Supply location arguments to choose other places. Both render the same map-only app. MCP endpoint: http://localhost:3000/mcp.

Keep any configured .env private; the repository contains only .env.example.

Explore

• Storms: radar, observed lightning, storm cells and official alerts. Select a cell for reflectivity, hail probability, movement, observation time and any supplied forecast track/cone.

• Next hour: forecast radar plus lightning and hail threat layers. The timeline spans two hours of history through one hour ahead and explicitly distinguishes observations from forecasts.

• Wind / Satellite: wind particles with temperature shading, or geocolor satellite with alerts.

• Places: numbered pins with current weather, official alert details and intersection with available fresh storm forecast cones. A single-city map opens that city's details automatically; searching recenters the map and opens the new city's details when its weather loads. Click the map to add a pin, up to five.

• Explain this view: sends the selected place/cell, time, layers and visible bounds to the host assistant, with uncertainty and snapshot/playback distinctions.

Nine supported layer IDs: radar, satellite-geocolor, temperatures, wind-particles, alerts, lightning-strikes, stormcells, lightning-threats, hail-threats. Coverage and entitlement vary. Observed-only layers are hidden in future playback; the latest custom cell pins are also hidden in historical playback. Lightning outlook requires a future time.

Storm lookup returns at most 30 cells within 400 km. Place exposure considers only fresh, unexpired supplied forecast cones. Missing tracks produce assessment unavailable, never a safety claim. The sampled live cells lacked forecast geometry; geometry handling has unit coverage but was not verified against a live cone.

Credentials and data

Set WEATHER_MODE=live, XWEATHER_CLIENT_ID, and XWEATHER_CLIENT_SECRET for the server-side Weather API. The adapter calls places, conditions, forecasts, alerts, and stormcells directly; it does not proxy Xweather's upstream MCP. Live failures never silently become samples. Partial data failures are labelled. Weather data is cached for five minutes and places for one hour, so Refresh may retain cached observations.

The MapsGL browser needs a separate restricted credential:

XWEATHER_MAPSGL_CLIENT_ID=your_browser_client_id
XWEATHER_MAPSGL_CLIENT_SECRET=your_browser_client_secret
XWEATHER_MAPSGL_RESTRICTED=true

Configure allowed domains in Xweather before setting that flag. Local Inspector uses localhost and 127.0.0.1. The flag is an operator assertion, not an API restriction check. Browser credentials are visible to the browser but travel only in tool-result _meta, outside model-visible content and structuredContent. Unrestricted server credentials never fall back into browser configuration. Keep .env ignored and mode 0600.

Without credentials, WEATHER_MODE=demo shows labelled sample place weather for Dallas, Arlington, Plano, Miami, Tampa, Orlando, Zurich, Milan and Munich. It never fabricates storm observations. The map shows only the basemap until a restricted MapsGL credential is configured.

UI and map integration

• Official Fluid Functionalism Button, Slider and shape/context primitives are installed as source under views/shared/fluid/; provenance is in its README. Tailwind generates their utilities through npm run styles. ShapeProvider selects pill shapes.

• OpenFreeMap vector tiles provide the dark basemap; OpenFreeMap, OpenMapTiles, OpenStreetMap and Xweather attribution stays inside the map.

• npm run prepare:assets copies the pinned MapLibre module workers to public/maplibre/ as .js, preserving the correct JavaScript MIME type. The view sets an explicit worker URL so MCP view bundling does not break worker resolution. predev and prebuild run this plus style generation automatically.

• MapsGL 1.10.1 reads the old map.transform property. A read-only getter bridges it to MapLibre 6's painter.transform. Reverify the bridge and workers before upgrading either package.

• CSP includes the four explicit MapsGL shard hosts used by the pinned SDK, Xweather/Aeris weather hosts, OpenFreeMap assets and blob: connections required by MapsGL workers. Explicit shard names avoid host implementations that URL-encode wildcard domains. Deployment needs the actual host's credential origins and sandbox validation.

• Timeline dates use whole seconds because MapsGL truncates milliseconds. Slow connections may show gaps while frames load.

• MapsGL usage is 150 accesses per five-minute wall-clock session bucket. The Developer plan used for this PoC has 15,000 monthly accesses. Close unused map views.

• Map libraries load dynamically. Builds pass with large-chunk warnings.

Validation

npm run typecheck
npm test
npm run build
# Requires the running dev server and live credentials:
npm run test:live

Thirteen focused tests cover sample/live separation, sanitized failures, missing data, timestamps, credential separation, storm normalization, cone boundaries, client-location precedence, locale defaults and basemap themes. Live smoke checks four tools/two resources, live place weather/storm cells, timeline configuration, invalid input, credential redaction, client-location defaults for both tools and explicit-location precedence. Visual rendering is checked separately in the Inspector.

See verification evidence for the checks performed and their limits. ChatGPT/Claude execution requires separate host validation.

Layout

• index.ts: tools, schemas, view metadata and CSP.

• src/weather.ts, src/storms.ts: provider normalization, caching, storm context and cone intersection.

• views/shared/WeatherMap.tsx: shared map-only experience used by both view entries.

• views/shared/basemap.ts, app.css, fluid/: map style and rounded glass UI.

• scripts/prepare-assets.mjs, smoke.ts: worker preparation and live protocol checks.

• tests/: focused data and credential tests.