Semantic City — Shared-World WebMCP Simulator

A playable city-management sandbox where humans and agents share one live city. WebMCP exposes traffic, budgets, and utilities so every agent action is visible, validated, and reversible.

Comment 1

The idea

Most websites expose pixels, buttons, and forms for people. When an AI agent needs to help, it often has to infer meaning from that visual surface or operate through a separate API the person cannot see.

Semantic City asks a different question:

What if a website exposed the meaning of its live interface directly to agents?

A city simulator is an ideal proving ground. A person sees roads, congestion, utilities, budgets, and tradeoffs. An agent needs those same concepts as structured objects, metrics, constraints, and legal actions. Both should work on one world.

What I built

Semantic City is a playable, deterministic city-management sandbox on a 24 × 18 grid. A human can build and upgrade roads; place residential, commercial, industrial, park, and power buildings; manage taxes and a city budget; advance simulation ticks; demolish; undo; and save or load locally.

The simulation tracks population, jobs, happiness, traffic, pollution, power coverage, cash flow, construction spend, and challenge constraints. Its rules are deliberately understandable and deterministic, so interventions have reproducible causes and results.

Why WebMCP is essential

WebMCP is the product interface, not an automation wrapper.

The page registers 14 domain tools through document.modelContext.registerTool(...), including city and metric reads, area, traffic, and budget inspections, building and road mutations, tax changes, deterministic simulation, undo, challenge evaluation, and non-committing intervention previews.

Every tool is connected to the same authoritative, revisioned CityStore used by the React interface. There is no hidden "agent city" or scripted winning state. Human clicks and WebMCP calls dispatch the same validated commands.

Mutations require the latest observed revision and return affected objects and cells, direct cost, metric deltas, constraint results, world ID, state hash, and rules version. This makes agent actions safe, deterministic, and verifiable.

Making agent behavior visible

Semantic View reveals what the page exposes semantically: stable object IDs, road connectivity, traffic and capacity, neighborhood boundaries, building effects, utility coverage, pollution, happiness, costs, and placement constraints.

When an inspection tool returns roads, buildings, or cells, those exact entities light up on the visible map. Before a mutation, affected cells are hatched as a preview without advancing the city revision. After a commit, the map, metrics, constraints, revision, hash, undo history, and activity timeline update together.

The timeline records the selected tool, arguments, affected objects, cost, metric changes, execution time, and before-and-after proof. The human can see exactly what the agent inspected, intended, and changed.

The Rivergate challenge

The featured goal is:

Reduce traffic below 50%, maintain happiness above 70%, and spend no more than $400,000, without raising taxes or demolishing homes.

Rivergate starts at 83.80% traffic. The agent first inspects the authoritative city, traffic hotspots, and budget, then previews and commits a seven-cell avenue upgrade. Traffic falls to 58.44% - better, but still failing.

Instead of assuming success, the agent inspects revision one, finds the remaining bottleneck, previews and commits a second five-cell upgrade, advances one deterministic tick, and verifies the new world.

The final state reaches 48.06% traffic with $204,000 spent, happiness above 70%, no tax increase, no demolished homes, and 5/5 constraints passed. The first intervention is deliberately insufficient, forcing an inspect - act - observe - iterate loop rather than a one-shot macro.

How it was built

Semantic City uses React, TypeScript, and Vite. A pure domain engine owns CityWorld; derived systems recompute connectivity, traffic, power, pollution, jobs, happiness, cash flow, and constraints.

Commands validate complete building footprints and road paths atomically, reject stale revisions, enforce available cash and hard scenario rules, and return structured success or error envelopes. Canonical serialization produces a deterministic state hash.

The WebMCP adapter translates strict snake_case tool inputs into the same commands used by human controls. Unit and Playwright tests cover the engine, shared store, revisions, undo, tool registration, semantic highlighting, previews, the two-step Rivergate solution, activity evidence, and responsive UI. I also rehearsed the complete flow against the public deployment using a native WebMCP-enabled browser.

Challenges and lessons

The hardest problem was guaranteeing that there is only one world. A tool mutation must become visible immediately, while a human action must be readable by the next agent inspection. One store, one dispatcher, revision checks, and hashes make that guarantee explicit.

Traffic also needed to create meaningful tradeoffs without becoming a research-scale simulation. Deterministic weighted paths, fixed capacities, aggregate commuter and freight loads, and stable tie-breaking create explainable congestion.

The larger lesson is that agent transparency can be a product feature. Domain tools, exact inspection highlights, previews, and audit trails let a person collaborate with an agent instead of trusting opaque UI automation.

Accomplishments

  • Built a real playable simulator rather than a WebMCP mockup
  • Exposed 14 meaningful tools over one authoritative live world
  • Added deterministic metrics, stale-revision protection, and world proofs
  • Added exact inspection highlighting and non-committing previews
  • Added placement validation, hard constraints, demolition, undo, and local persistence
  • Created a two-step scenario that visibly requires iteration
  • Made every agent action legible through a semantic overlay and activity timeline

What’s next

The same shared-semantic-world pattern can extend to operational dashboards, logistics networks, infrastructure simulations, planning canvases, and digital twins, any interface where people need to inspect, preview, and audit agent changes to live state.

Future versions could add scenario authoring, richer utility networks, shareable saves, more challenge prompts, and additional semantic layers without changing the one-store architecture.

Built With

  • ai
  • artificial
  • city
  • css3
  • deterministic
  • developer
  • html5
  • human-ai
  • localstorage
  • openai
  • playwright
  • react
  • simulation
  • typescript
  • vercel
  • vite
  • vitest
  • webmcp
Share this project:

Updates