Yerevan Land Use MCP Server

Yerevan Land Use MCP Server

A streamable-HTTP MCP server over the Yerevan land-use classification: 28,832 H3 resolution-10 hexagons(429.6 km², ~0.0149 km² each) classified into 8 land-use classes for 2015, 2020 and 2024.

A single shared classifier was applied to all three years, so year-to-year differences reflectthe imagery rather than a change of model. The panel is balanced — every hex exists in everyyear, which is what makes the transition and change tools meaningful.

Install

python3 -m venv --system-site-packages .venv
.venv/bin/pip install -e .

Run

The server speaks streamable HTTP. It is a long-running process — start it, then pointclients at the URL:

./run_server.sh                  # http://127.0.0.1:8000/mcp

yerevan-landuse 1.0.0 | 28832 hexes, 429.552 km2, years 2015, 2020, 2024
  MCP endpoint  http://127.0.0.1:8000/mcp
  health check  http://127.0.0.1:8000/health
  mode          session, SSE responses

The dataset is loaded before the port opens, so a broken or missing CSV fails at startupinstead of on someone's first tool call. Startup takes ~0.7 s; tool calls are then a fewmilliseconds each, and the loaded table is shared across all connected clients.

Two extra HTTP endpoints come along for free: GET /health (liveness + hex count, for aprocess supervisor or container probe) and GET / (points stray browsers at /mcp).

Connect

{
  "mcpServers": {
    "yerevan-landuse": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

• Claude Code — claude mcp add --transport http yerevan-landuse http://127.0.0.1:8000/mcp, or keep the .mcp.json in this folder and open the project.
• Claude Desktop — paste the block above into ~/.config/Claude/claude_desktop_config.json.

The server must already be running before a client connects — unlike stdio, nothinglaunches it for you. If tools do not appear, check curl localhost:8000/health first.

Calling it without an MCP client

In --stateless --json-response mode a tool call is a single POST, no handshake:

./run_server.sh --port 8000 --stateless --json-response &

curl -s -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"change_summary","arguments":{}}}'

That mode is also the right choice behind a load balancer, or for any client thatreconnects often — there is no session to lose. The default session mode is better for asingle interactive client, since it supports streaming and resumable connections.

Exposing it beyond localhost

Binding to 0.0.0.0 serves every tool to anyone who can reach the port — there is noauthentication, and Host validation is off by default for non-loopback binds (the serverprints a warning saying so). Before exposing it:

./run_server.sh --host 0.0.0.0 --allowed-host yerevan.internal:8000

and put a reverse proxy with TLS and auth in front. The tools are read-only — nothing canmodify the CSVs — but export_geojson does write files into outputs/, and run_querywill happily burn CPU on a large scan.

Verify

.venv/bin/python tests/validate_data.py   # data integrity, all 4 CSVs cross-checked
.venv/bin/python tests/smoke_test.py      # every tool in-process

./run_server.sh --port 8765 &
cd tests && ../.venv/bin/python http_smoke_test.py http://127.0.0.1:8765/mcp

The HTTP test drives a real client over the network: it checks /health and /, lists thetools, runs all 23 tool calls, confirms the 7 bad-input cases come back as protocol errors,reads every resource and prompt, re-checks the arithmetic invariants over the wire, andreconnects a second session to prove the server survives a client going away.

Data

The server reads the master file; the single-year files are cross-checked bytests/validate_data.py (verified identical, same hexes in the same order). PointYEREVAN_DATA_DIR elsewhere to swap the data out, YEREVAN_OUTPUT_DIR to redirect exports.

Classes: Industrial, OpenZone, Parking, Residential, Road, Sport, Vegetation, Water.Built-up = Residential + Industrial + Parking + Road.

Two bases — this matters

The classifier is multi-label: each class gets its own probability, and a hex can carryseveral labels or none (1,981 hexes carry no label in 2024). Every tool therefore acceptsa basis:

• dominant (default) — one class per hex, the highest probability. Mutually exclusive,so counts and areas sum to the study area. Use for area statistics.
• labels — the raw binary flags. Counts overlap and do not sum to the study area.Use for co-occurrence and coverage questions.

Distances, rings and compass sectors are measured from Republic Square (40.1776, 44.5126)using a local equirectangular projection — sub-metre error at this extent, and consistentwith the existing Yerevan analysis.

Tools

Orientation| Tool | Purpose ||---|---|| dataset_info | coverage, grid, classes, extent, vocabulary every other tool expects || class_composition | hexes, km² and share per class, per year, either basis || class_cooccurrence | which labels share a hex; label-count distribution || probability_stats | probability distribution + histogram for one class/year |

Change over time| Tool | Purpose ||---|---|| transition_matrix | class-to-class flows between two years, plus stability || change_summary | built-up gain/loss, vegetation lost, net change per class, core vs edge || built_up_by_ring | the centre-to-periphery gradient, per year || directional_growth | which compass sector grew, for the outer city |

Places| Tool | Purpose ||---|---|| hex_at_location | lat/lng → the hexagon there, with everything known about it || hex_detail | one hexagon: geometry, per-year probabilities, labels, change path || hex_neighbors | the k-ring around a hexagon, with a composition profile || area_profile | composition and change for a circular area around a point |

Retrieval and export| Tool | Purpose ||---|---|| query_hexes | filter by class, probability, location, sector and change; paged || run_query | ad-hoc pandas expression / group-by over the full table || export_geojson | write matching hexagons as real polygons to outputs/ |

query_hexes always reports the total match count and area even when returning one page,so it doubles as a counting tool — set limit=1 when you only want the number.

Resources: yerevan://dataset/info, yerevan://dataset/schema, yerevan://dataset/files,yerevan://summary/{year}.Prompts: land_use_report, change_analysis, site_briefing.

What the data says

Figures from change_summary and class_composition, dominant-class basis, 2015 → 2024:

• Built-up share 39.3% → 43.4% (168.7 → 186.5 km²); 33.5 km² densified, 15.6 km²opened up, +17.9 km² net.
• Residential is the biggest gainer (+15.1 km²); OpenZone (−13.8 km²) and Vegetation(−8.1 km²) give up the most. 9.5 km² went directly from vegetation to built-up.
• 77.9% of hexes kept the same dominant class across the nine years.
• Growth is at the edge, not the core: the 0–2 km core moved 78.3% → 80.9% built,while the 6–10 km band moved 36.4% → 42.6%.

Notes and caveats

• These are model outputs, not ground truth. Small class-to-class flows can beclassification noise rather than real change — check a flow against the stable sharebefore reading anything into it, and use probability_stats to see how confident themodel is for a given class.
• Water gaining 4.0 km² between 2015 and 2024 is a good example: it is more likelyseasonal imagery or spectral confusion than new water bodies.
• run_query evaluates pandas expressions against a read-only in-memory copy of thetable. It cannot modify the CSVs, but it is a power tool — the other tools are saferand self-documenting.
• export_geojson writes only into outputs/; the filename is sanitised, so it cannotescape that folder.

Layout

src/yerevan_mcp/
  dataset.py   loading, derived geometry, analytics
  query.py     selection, spatial lookups, GeoJSON export
  server.py    MCP tools, resources, prompts, HTTP routes, CLI
tests/
  validate_data.py     cross-checks all 4 CSVs
  smoke_test.py        exercises every tool in-process
  http_smoke_test.py   the same suite over a real HTTP connection
data/                  the 4 source CSVs
outputs/               GeoJSON exports land here
run_server.sh          launcher; flags pass straight through

Keeping it running

run_server.sh runs in the foreground. For a persistent service, wrap it in a systemduser unit (~/.config/systemd/user/yerevan-mcp.service):

[Service]
ExecStart=/home/hovhannes/Desktop/Yerevan-MCP-Server/run_server.sh
Restart=on-failure

[Install]
WantedBy=default.target

Then systemctl --user enable --now yerevan-mcp.