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 reflect the imagery rather than a change of model. The panel is balanced — every hex exists in every year, which is what makes the transition and change tools meaningful.

Install

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

Related MCP server: mcp-arcgis-henderson

Run

The server speaks streamable HTTP. It is a long-running process — start it, then point clients 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 startup instead of on someone's first tool call. Startup takes ~0.7 s; tool calls are then a few milliseconds 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 a process 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, nothing launches 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 that reconnects often — there is no session to lose. The default session mode is better for a single 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 no authentication, and Host validation is off by default for non-loopback binds (the server prints 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 can modify the CSVs — but export_geojson does write files into outputs/, and run_query will 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 the tools, 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, and reconnects 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 by tests/validate_data.py (verified identical, same hexes in the same order). Point YEREVAN_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 carry several labels or none (1,981 hexes carry no label in 2024). Every tool therefore accepts a 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 consistent with the existing Yerevan analysis.

Tools

Orientation

Change over time

Places

Retrieval and export

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 be classification noise rather than real change — check a flow against the stable share before reading anything into it, and use probability_stats to see how confident the model is for a given class.

• Water gaining 4.0 km² between 2015 and 2024 is a good example: it is more likely seasonal imagery or spectral confusion than new water bodies.

• run_query evaluates pandas expressions against a read-only in-memory copy of the table. It cannot modify the CSVs, but it is a power tool — the other tools are safer and self-documenting.

• export_geojson writes only into outputs/; the filename is sanitised, so it cannot escape 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 systemd user 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.