# jagan-shanmugam/open-streetmap-mcp architecture

> Architecture diagram of the GitHub repository jagan-shanmugam/open-streetmap-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jagan-shanmugam/open-streetmap-mcp
- Repository: https://github.com/jagan-shanmugam/open-streetmap-mcp

## Overview

##### Project type and purpose
- This is a standalone MCP (Model Context Protocol) server written in Python. It acts as a middleware between an LLM-based host (e.g., Claude Desktop, Cursor) and OpenStreetMap (OSM) data sources. The server exposes “tools” (geocode, reverse geocode, route, etc.) and “resources” (tile endpoints) over the MCP protocol via stdio or HTTP (using the UVX runner).

##### File structure
- Top-level:
- `.github/workflows/publish-to-pypi.yml`: CI/CD to publish the package
- `pyproject.toml` & `uv.lock`: build and dependency management
- `LICENSE`, `.gitignore`, `README.md`
- `demo` and `examples`: usage walkthroughs and sample clients
- `src/osm_mcp_server/`
- `server.py`: entry point that registers MCP tools and resource handlers
- `__init__.py`: package metadata
- There are no separate “frontend” or “database” directories, confirming it’s a single server process.

##### README for additional insights
- The server implements two categories:
a. **Resources** under `location://…` for map tiles and place lookups
b. **Tools** (geocode, find_nearby_places, suggest_meeting_point, etc.)
- It runs via the `osm-mcp-server` console script, listening over stdio/HTTP, and communicates with external OSM APIs.

a. **Main Components**
1. **MCP Host / Client** – e.g., Claude Desktop or a custom Python client
2. **MCP Protocol Layer** – stdio or HTTP adapter (UVX runner)
3. **OSM MCP Server Process**
- **Tool Registry & Dispatcher** – maps MCP calls to Python handlers
- **Resource Handlers** – tile server endpoints, place lookup
- **Core Services** – geocoding, routing, POI search, neighborhood analysis
- **Request/Response Serializer** – JSON over stdio/HTTP
4. **External Services**
- OpenStreetMap Overpass API (places, POIs)
- Tile servers (map tiles)
- (Optional) Caching layer or local tile cache
b. **Relationships & Interactions**
- The MCP Host sends JSON RPC requests to the MCP Protocol Layer.
- The Protocol Layer forwards to the Tool Registry in the Server Process.
- Tool handlers call external OSM services (Overpass, tile servers) and process results.
- Responses flow back up: Handlers → Protocol Layer → MCP Host.
- Example clients in `examples/` illustrate usage of this flow.
c. **Architectural Patterns & Principles**
- **Pipe & Filter**: each tool is a filter that transforms input parameters into geospatial data
- **Adapter**: the Protocol Layer adapts stdio/HTTP to internal function calls
- **Registry/Dispatcher**: dynamic registration of tools and resources at startup
- **Separation of Concerns**: tools (business logic) vs. protocol vs. external I/O
d. **Key Technologies & Frameworks**
- Python 3 with `uv` command runner (UVX)
- MCP protocol spec for tool/resource invocation
- Requests or HTTPX for external OSM API calls
- JSON serialization

## Diagram (Mermaid)

```mermaid
graph TB
    %% Clients and Documentation
    ClientEs["Client<br/>(examples/client.py)"]:::external
    ClientLA["Location Assistant Client<br/>(examples/location_assistant_client.py)"]:::external
    demo["Demo Usage<br/>(demo/)"]:::docs
    pyproject["pyproject.toml"]:::docs
    uvlock["uv.lock"]:::docs
    workflow["CI/CD Workflow<br/>(publish-to-pypi.yml)"]:::docs
    license["LICENSE"]:::docs
    readme["README.md"]:::docs
    gitignore[".gitignore"]:::docs
    init["__init__.py"]:::docs

    %% Protocol Adapter and Server Process
    Adapter["MCP Protocol Adapter<br/>(stdio • HTTP)"]:::adapter

    subgraph "OSM MCP Server Process"
        Registry["Tool Registry & Dispatcher"]:::registry
        Serializer["Request/Response Serializer<br/>(JSON RPC)"]:::service
        GeoHandler["Geocode Handler"]:::service
        RouteHandler["Route Handler"]:::service
        POIHandler["POI Search Handler"]:::service
        NeighborhoodHandler["Neighborhood Analysis Handler"]:::service
        TileHandler["Tile Resource Handler"]:::service
        Cache["Cache<br/>(Redis/Local)"]:::service
    end

    %% External Services
    Overpass["OpenStreetMap Overpass API"]:::external
    TileServer["Tile Server"]:::external

    %% Data Flow
    demo --> ClientEs
    ClientEs --> Adapter
    ClientLA --> Adapter
    Adapter --> Registry
    Registry --> Serializer

    Serializer --> GeoHandler
    Serializer --> RouteHandler
    Serializer --> POIHandler
    Serializer --> NeighborhoodHandler
    Serializer --> TileHandler

    GeoHandler --> Cache
    RouteHandler --> Cache
    POIHandler --> Cache
    NeighborhoodHandler --> Cache
    TileHandler --> Cache

    Cache --> Overpass
    Cache --> TileServer

    Overpass --> Cache
    TileServer --> Cache

    Cache --> GeoHandler
    Cache --> RouteHandler
    Cache --> POIHandler
    Cache --> NeighborhoodHandler
    Cache --> TileHandler

    GeoHandler --> Serializer
    RouteHandler --> Serializer
    POIHandler --> Serializer
    NeighborhoodHandler --> Serializer
    TileHandler --> Serializer

    Serializer --> Adapter
    Adapter --> ClientEs
    Adapter --> ClientLA

    %% Click Events
    click ClientEs "https://github.com/jagan-shanmugam/open-streetmap-mcp/blob/main/examples/client.py"
    click ClientLA "https://github.com/jagan-shanmugam/open-streetmap-mcp/blob/main/examples/location_assistant_client.py"
    click demo "https://github.com/jagan-shanmugam/open-streetmap-mcp/tree/main/demo/"
    click Adapter "https://github.com/jagan-shanmugam/open-streetmap-mcp/blob/main/src/osm_mcp_server/server.py"
    click Registry "https://github.com/jagan-shanmugam/open-streetmap-mcp/blob/main/src/osm_mcp_server/server.py"
    click Serializer "https://github.com/jagan-shanmugam/open-streetmap-mcp/blob/main/src/osm_mcp_server/server.py"
    click GeoHandler "https://github.com/jagan-shanmugam/open-streetmap-mcp/blob/main/src/osm_mcp_server/server.py"
    click RouteHandler "https://github.com/jagan-shanmugam/open-streetmap-mcp/blob/main/src/osm_mcp_server/server.py"
    click POIHandler "https://github.com/jagan-shanmugam/open-streetmap-mcp/blob/main/src/osm_mcp_server/server.py"
    click NeighborhoodHandler "https://github.com/jagan-shanmugam/open-streetmap-mcp/blob/main/src/osm_mcp_server/server.py"
    click TileHandler "https://github.com/jagan-shanmugam/open-streetmap-mcp/blob/main/src/osm_mcp_server/server.py"
    click pyproject "https://github.com/jagan-shanmugam/open-streetmap-mcp/blob/main/pyproject.toml"
    click uvlock "https://github.com/jagan-shanmugam/open-streetmap-mcp/blob/main/uv.lock"
    click workflow "https://github.com/jagan-shanmugam/open-streetmap-mcp/blob/main/.github/workflows/publish-to-pypi.yml"
    click license "https://github.com/jagan-shanmugam/open-streetmap-mcp/tree/main/LICENSE"
    click readme "https://github.com/jagan-shanmugam/open-streetmap-mcp/blob/main/README.md"
    click gitignore "https://github.com/jagan-shanmugam/open-streetmap-mcp/blob/main/.gitignore"
    click init "https://github.com/jagan-shanmugam/open-streetmap-mcp/blob/main/src/osm_mcp_server/__init__.py"

    %% Styles
    classDef external fill:#E3F2FD,stroke:#2196F3,stroke-width:2px
    classDef adapter fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px
    classDef registry fill:#F3E5F5,stroke:#8E24AA,stroke-width:2px
    classDef service fill:#E8F5E9,stroke:#43A047,stroke-width:2px
    classDef docs fill:#FAFAFA,stroke:#90A4AE,stroke-width:2px
```
