Type an address, get a pictogram map. Korean-style 약도, auto-generated, anywhere in the world.
Part of: Human-Controlled AI Systems — the MCP server stays a tool, never an agent. Curation is a deterministic heuristic; an LLM only enters the loop when the host (Claude Code, Cursor, Codex CLI, …) chooses to compose it.
Most maps are too accurate to be useful. Korean 약도 (yakdo) and Japanese 略地図 are wayfinding diagrams: a handful of landmarks, simple arrows, a station exit number. They're easier to read at a glance than any GPS screenshot — exactly what a business card, wedding invitation, or shop flyer needs.
cairn brings that pictogram-first approach to anywhere with OpenStreetMap coverage.
- 5 MCP tools over stdio:
generate_map(address → SVG + editable document),render_document(patch + re-render without network access),geocode(address → coords via Nominatim),find_landmarks(coords → POI list via Overpass), andfind_roads(coords → simplified road polylines via Overpass). - Chat-first wayfinding skill in
skills/create-wayfinding-map— teaches compatible AI hosts to generate, visually inspect, patch, and re-render a map instead of accepting the first SVG draft. - Zero-API-key path. OSM Nominatim + Overpass only. No Mapbox / Google keys, no account, no quota signup.
- Works anywhere OSM does. Place names come back exactly as OpenStreetMap has them, because a 약도 should read like the signs around it —
Rue de Rivolistays French. Only the labels cairn generates take a language, and that follows the destination's country: Seoul renders여기/3번 출구, BerlinHier/Ausgang 3, StockholmHär. Override with--language. The projection applies a cos(latitude) correction and a single uniform scale, so a Stockholm map keeps its true proportions instead of being stretched horizontally. POI lookups cover tram stops, ferry piers, supermarkets, and pharmacies, and query ways and relations so the polygon-mapped parks, hospitals, and schools common outside East Asia are visible. - Cache, offline, and mirrors. Responses are cached on disk, so iterating on one address costs one set of network calls (a cold London render takes 5.2s, a warm one 0.27s, byte-identical).
--offlinerenders from cache alone,--refreshre-fetches, and transient 429/5xx responses from the public endpoints retry with backoff.--nominatim-url/--overpass-urlpoint at a self-hosted or mirrored deployment; endpoints are CLI/environment settings only, never MCP tool arguments, so a host LLM can't aim cairn at an arbitrary URL. - Road skeleton in src/roads.ts — fetches nearby roads, classifies them by importance tier (primary / secondary / tertiary / residential), and simplifies each polyline with Douglas-Peucker (src/geometry.ts). This is what turns the output from a scatter of points into an actual 약도: a few roads you navigate along, with the major ones labeled.
- Deterministic curation heuristic in src/curate.ts — weights importance (transit > civic > shop), targets a ~150 m sweet-spot distance, enforces category diversity, caps at the requested
limit(default 5). - Pictogram SVG renderer — curated road bands, category-specific SVG pictograms, coalesced station/exit labels, route-aware final-approach arrows, deduped road-name labels, destination callouts, and visible OSM attribution tuned for print-style 약도 output. Connected visible road axes produce an explicitly marked
inferred-roadcue; it is a diagram heuristic, not certified pedestrian routing. - CLI with file output, label override, independent template/theme selection, and a
--no-roadstoggle:node dist/cli.js "서울 강남구 테헤란로 152" -o office.svg --label "스튜디오" node dist/cli.js "서울 강남구 테헤란로 152" -o office-compact.svg --template compact --theme civic node dist/cli.js "서울 강남구 테헤란로 152" -o office-badge.svg --template badge --theme invitation node dist/cli.js "서울 강남구 테헤란로 152" -o office-focus.svg --focus node dist/cli.js "Shibuya Crossing, Tokyo" -o shibuya.svg --layout geographic node dist/cli.js "Brandenburger Tor, Berlin" -o berlin.svg --language de node dist/cli.js "Sergels torg, Stockholm" -o stockholm.svg --offline node dist/cli.js "서울 강남구 테헤란로 152" -o office.svg --save-document office.json node dist/cli.js render office.json -o office-revised.svg node dist/cli.js render office.json -o office-print.pdf node dist/cli.js render office.json -o office-preview.png
- Local export —
.svg,.png, and.pdfoutput is selected by the filename extension without a paid conversion service. SVG remains the canonical vector artifact; PDF embeds a 4× local raster for reliable print delivery. - Layout modes —
diagramis the default 약도 layout, keeping only the navigational structure;geographicpreserves raw road geometry more closely for inspection/debugging. - Composition templates —
standard(default) keeps the full curated 약도,compactbecomes an approach-focused mini-map,minimaluses a route strip,schematicturns roads into right-angle axes, andbadgerenders a destination-first inset. - Visual themes —
paper(default),mono,civic, andinvitationindependently change color, typography, roads, markers, and callouts without changing the chosen composition. - Editable document model —
DiagramDocument v1stores the source map, canvas, template, theme, explicit approach landmark, hidden/relabelled elements, and normalized manual landmark positions. The same JSON survives multiple chat revisions and can also back optional visual editors without changing the rendering core. - Destination focus (opt-in
--focus/focus: true) — a radial fisheye that magnifies the area around the destination and compresses the periphery, so the crucial last block reads larger. It applies to the map-skeleton diagram presets (standard,compact,schematic); route-strip and badge templates keep their fixed composition. - Bounded inputs on public tool/CLI parameters — search radii max out at 5 km, internal radius expansion is clamped back to that same ceiling, and SVG canvas dimensions at 4000 px keep public OSM services and the single-process renderer healthy.
- HTTP rate-limiting, retries, and timeouts on outbound calls — 1.1s minimum spacing to Nominatim, 1 req/s to Overpass per their usage policies, with the gate re-acquired on every retry. Spacing is configurable for a server you host yourself, where those policies don't apply.
- Tests: the full vitest suite runs on every push, on Node 22 and 24. No coverage threshold is enforced.
- Visual audit harness:
npm run visual:auditrebuilds the package, renders 2 deterministic city/campus fixtures across all 5 templates and 4 themes (40 combinations), and fails on marker-road overlap, duplicate transit clusters, illegible approach cues, UI-like label chrome, color drift, or excessive road density.
- More chat-driven document patches and export formats. A visual editor remains optional rather than the primary product surface.
- Stronger automatic composition and label layout, using the editor document as an escape hatch when heuristics are not enough.
- npm publish automation for future releases.
- More domain templates for campuses, events, invitations, and indoor/game wayfinding.
- Optional Mapbox / Google geocoder adapters (opt-in only; the default stays zero-key).
- Figma plugin import/export for
DiagramDocument.
- Fewer landmarks by design. A good cairn is one stone stacked carefully, not a quarry. Every extra element costs cognitive load, so the default heuristic picks fewer landmarks than you'd expect — and that's the point.
- Granular and high-level tools, side by side.
generate_mapis convenient;geocode+find_landmarks+find_roadsexist so a host LLM can compose smarter pipelines than any single one-shot ever could. - No server-side LLM calls. The MCP server is a tool, not an agent: curation is deterministic, so it's debuggable, testable, and doesn't push token costs onto the user. Any LLM-powered refinement happens in the host process.
- Domain-neutral by design. Business cards are the primary use case, but the render pipeline doesn't lock to that domain — wedding invitations, real estate listings, and event flyers all reuse the same primitives.
- Map-source-neutral renderer. Address lookup currently uses OSM, but the renderer consumes
MapLayout. Campus plans, indoor graphs, or game-world topology can use the same engine once adapted into that structure. - Single-file MCP server style (anvil / AirMCP pattern): minimal dependencies, single-responsibility modules, easy to audit end-to-end.
cairn sends the address you type to two OpenStreetMap services in order to do its job: Nominatim for geocoding and Overpass for landmark and road lookup. Both run on the OSM Foundation's public infrastructure and follow the OSMF privacy policy. cairn has no telemetry, no account, and reads no credentials from the environment.
It does cache upstream responses on local disk by default, so a repeated
address is answered without another request. That cache holds the raw
Nominatim and Overpass bodies for your queries, unencrypted, under
~/.cache/cairn (or $XDG_CACHE_HOME/cairn) for 7 days. If the address is
sensitive, disable it with --no-cache or CAIRN_CACHE_MODE=off, or point
cairn at a self-hosted Nominatim / Overpass instance with --nominatim-url /
--overpass-url.
- A hosted frontend coupled to the engine. A visual editor is useful, but the renderer and document format stay headless and local-first. Web, desktop, and plugin shells are interchangeable clients rather than a required account-backed service.
- Paid geocoders as the default. Mapbox / Google may ship as opt-in adapters; the zero-config
npxpath will always work without a key. - Server-side LLM calls. No model invocation happens inside cairn — not for curation, not for label translation, not anywhere. LLM use is the host's responsibility.
- A custom domain language. Wedding-invitation, real-estate, etc. variants will share the same render primitives, not fork into bespoke pipelines.
Status: cairn is published as
cairn-sketch. Install from npm with the snippets below, or install from source withnpm install && npm run buildand runnode dist/cli.js.
{
"mcpServers": {
"cairn": {
"command": "npx",
"args": ["-y", "-p", "cairn-sketch", "cairn-mcp"]
}
}
}Then ask the assistant:
Make a pictogram map for 서울 강남구 테헤란로 152, label it "스튜디오". Inspect the result, remove low-value landmarks that hurt readability, and return the final SVG and editable document.
The npm package ships the canonical create-wayfinding-map skill. Install it
into the local skills directory used by your compatible AI host:
npx -p cairn-sketch cairn install-skill <skills-directory>The installer refuses to overwrite an existing copy. Remove or rename the old folder explicitly before upgrading it.
npx -p cairn-sketch cairn "서울 강남구 테헤란로 152" -o office.svg
npx -p cairn-sketch cairn "1600 Amphitheatre Pkwy, Mountain View" --label "Office" --template compact --theme mono
npx -p cairn-sketch cairn "서울 강남구 테헤란로 152" -o office.svg --save-document office.json
npx -p cairn-sketch cairn render office.json -o office-revised.svg
npx -p cairn-sketch cairn render office.json -o office-print.pdfimport {
createDiagramDocument,
renderDiagramDocument,
} from "cairn-sketch/document";
const document = createDiagramDocument(mapLayout, {
template: "schematic",
theme: "civic",
overrides: {
landmarks: {
"main-gate": { position: { x: 0.22, y: 0.36 }, locked: true },
},
},
});
const savedJson = JSON.stringify(document);
const svg = renderDiagramDocument(JSON.parse(savedJson));- Geocode the address (Nominatim — no API key).
- Find landmarks within a configurable radius (Overpass): transit stations, subway exits, schools, parks, recognizable shops, distinctive buildings.
- Find roads in the same area (Overpass), classify them by importance tier, and simplify each polyline (Douglas-Peucker).
- Curate up to
limitlandmarks with the heuristic above (default 5). Category diversity caps each category at two, so a sparse or single-category area yields fewer rather than padding the map. - Render a pictogram SVG: road skeleton underneath, nearby station/exit markers coalesced, landmark labels kept clear, and an inferred visible-road approach or direct fallback leading to the destination callout.
- Output vector SVG, ready for print or digital embed.
| Tool | What it does |
|---|---|
generate_map |
Address → SVG + editable document (set roads: false to skip the skeleton) |
render_document |
Apply a minimal patch to an editable document and return revised SVG + document |
geocode |
Address → coordinates |
find_landmarks |
Coordinates → nearby points of interest |
find_roads |
Coordinates → simplified road polylines, classified by tier |
Granular tools let an LLM compose smarter pipelines — for example, "find landmarks and roads, keep the two biggest roads and the three most recognizable landmarks, render with those."
generate_map accepts layout: "diagram" | "geographic",
template: "standard" | "compact" | "minimal" | "schematic" | "badge", and
theme: "paper" | "mono" | "civic" | "invitation". The old preset field
remains an alias for template; template wins when both are supplied.
A cairn is a stack of stones hikers use to mark trails through complex terrain — just enough to say "you're on the path." Cousins exist across cultures: Korean 돌탑, Mongolian ovoo, Scottish cairns. All of them solve the same problem: simplify wayfinding by leaving only what matters.
MIT © heznpc