name	mcp-geo-detailed-os-maps
description	Build or refine user-facing mcp-geo HTML maps with OS vector detail, label-safe overlays, browser-stored OS keys, and real-browser validation.

MCP Geo Detailed OS Maps

Use this skill when a user-facing map in this repo needs precise Ordnance Survey street or building context, especially for report HTML, accessibility mapping, town-centre navigation, or slide-like static map outputs that still benefit from interactive zoom.

Default approach

Prefer a MapLibre underlay with the OS vector Light style: OS_VTS_3857_Light.json.
Keep your thematic overlay separate from the basemap. Do not bake route highlighting into the basemap.
Treat the OS detail layer as progressive enhancement:
- if a browser-held OS Maps API key is available, enable detailed context by default
- if not, keep a simplified fallback view that still works offline or without secrets

Overlay design rules

Preserve OS labels. Use casing, outlines, or translucent edge emphasis instead of thick opaque fills when highlighting roads or paths.
Match the geometry to the mapped object as closely as possible:
- road access overlays should sit on the road segment or pavement edge
- avoid bubbles or large markers that hide the exact segment being discussed
Put long explanations in hover text, sidebars, or perimeter callouts, not on the centre of the map.
If the map is for navigation, remove decorative labels before removing orientation cues such as north arrow, rail line, seafront, river edge, or major anchors.

Browser key pattern

Never hardcode OS keys into generated HTML.
Store the browser-side key locally in browser storage only.
Make the no-key path explicit and usable.
When only the presentation layer changes, prefer regenerating from a saved export rather than refetching live OS data. For the wheelchair report generator, use --reuse-export with the existing dated JSON export.
When switching styles in MapLibre, remember that style changes clear custom sources and layers; rehydrate overlays after style.load if you render them inside the MapLibre stack.

Validation checklist

Open the generated HTML in a real browser.
Check default fit at desktop width with no clipping or hidden sidebars.
Check zoom in/out, mouse wheel zoom, drag pan, and reset behavior.
Check label readability with the detailed OS basemap enabled.
Check that fallback behavior is still clear and usable when no browser key is present.
If the map is intended for a static export, generate a screenshot after the final browser pass.

Useful local references

Generator: scripts/generate_teignmouth_wheelchair_access_map.py
Simple MapLibre lab: ui/simple_map.html
Boundary explorer: ui/boundary_explorer.html
Map proxy/auth handling: server/maps_proxy.py

MCP Geo Detailed OS Maps

Default approach

Prefer a MapLibre underlay with the OS vector Light style: OS_VTS_3857_Light.json.

Keep your thematic overlay separate from the basemap. Do not bake route highlighting into the basemap.

Treat the OS detail layer as progressive enhancement:

if a browser-held OS Maps API key is available, enable detailed context by default
if not, keep a simplified fallback view that still works offline or without secrets

Overlay design rules

Preserve OS labels. Use casing, outlines, or translucent edge emphasis instead of thick opaque fills when highlighting roads or paths.

Match the geometry to the mapped object as closely as possible:

road access overlays should sit on the road segment or pavement edge
avoid bubbles or large markers that hide the exact segment being discussed

Put long explanations in hover text, sidebars, or perimeter callouts, not on the centre of the map.

If the map is for navigation, remove decorative labels before removing orientation cues such as north arrow, rail line, seafront, river edge, or major anchors.

Browser key pattern

Never hardcode OS keys into generated HTML.

Store the browser-side key locally in browser storage only.

Make the no-key path explicit and usable.

When only the presentation layer changes, prefer regenerating from a saved export rather than refetching live OS data. For the wheelchair report generator, use --reuse-export with the existing dated JSON export.

When switching styles in MapLibre, remember that style changes clear custom sources and layers; rehydrate overlays after style.load if you render them inside the MapLibre stack.

Validation checklist

Open the generated HTML in a real browser.

Check default fit at desktop width with no clipping or hidden sidebars.

Check zoom in/out, mouse wheel zoom, drag pan, and reset behavior.

Check label readability with the detailed OS basemap enabled.

Check that fallback behavior is still clear and usable when no browser key is present.

If the map is intended for a static export, generate a screenshot after the final browser pass.

Useful local references

Generator: scripts/generate_teignmouth_wheelchair_access_map.py

Simple MapLibre lab: ui/simple_map.html

Boundary explorer: ui/boundary_explorer.html

Map proxy/auth handling: server/maps_proxy.py

mcp-geo-detailed-os-maps