# Maps MCP App

A ChatGPT App that displays an interactive map powered by OpenStreetMap data. Users can search for locations, businesses, landmarks, and points of interest — all within a ChatGPT conversation.

## Architecture

```
ChatGPT
   ↓
ChatGPT App (React + MapLibre)
   ↓
MCP Protocol
   ↓
MCP Server (Hono + Cloudflare Workers)
   ↓
OpenStreetMap API (Nominatim + Overpass)
```

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Frontend | React 19, TypeScript, Vite, MapLibre GL JS |
| Backend | Bun, Hono, MCP SDK, Zod |
| Data | OpenStreetMap (Nominatim geocoding, Overpass POI queries) |
| Deployment | Cloudflare Workers (server) + Cloudflare Pages (frontend) |
| Validation | Shared Zod schemas across frontend and backend |

## Repository Structure

```
├── apps/
│   ├── mcp-server/           # MCP protocol server
│   │   └── src/
│   │       ├── routes/        # Hono HTTP routes
│   │       ├── tools/         # MCP tool handlers
│   │       ├── services/      # OSM search service
│   │       └── index.ts       # Cloudflare Worker entry
│   └── chatgpt-app/          # React frontend
│       └── src/
│           ├── components/    # React components
│           ├── context/       # State management
│           ├── api/           # MCP client
│           └── main.tsx       # App entry
├── packages/
│   ├── shared-types/         # TypeScript types, enums, interfaces
│   └── shared-validation/    # Zod schemas (shared)
└── docs/
    ├── techspecs.md          # Technical specification
    ├── implementation.md     # Implementation guide
    └── DEPLOYMENT.md         # Deployment instructions
```

## Getting Started

### Prerequisites

- [Bun](https://bun.sh) 1.3+
- Node.js 22+ (for tooling)

### Install

```bash
git clone <repo-url>
cd maps-mcp-app
bun install
```

### Build Shared Packages

```bash
bun run --filter @maps-mcp/shared-types build
bun run --filter @maps-mcp/shared-validation build
```

### Run Locally

**Terminal 1 — MCP Server:**
```bash
cd apps/mcp-server
bun run dev
```
Server starts on http://localhost:3001

**Terminal 2 — Frontend:**
```bash
cd apps/chatgpt-app
bun run dev
```
App opens at http://localhost:5173

### Run Tests

```bash
# All tests
bun test

# Or per package
cd packages/shared-validation && bun test
cd apps/mcp-server && bun test
```

## MCP Tools

### `search_locations`

Search for nearby points of interest.

**Input:**
- `center` — `{ lat: number, lng: number }`
- `radius` — meters (250, 500, 1000, 2000, 5000, 10000, 25000)
- `category` — single category (optional)
- `categories` — multiple categories (optional)
- `text` — text search (optional)
- `limit` — max results (default 50)

**Output:** GeoJSON FeatureCollection + list items

### `get_location`

Get detailed information for one location.

### `categories`

List all supported search categories.

## Supported Categories

- Restaurants, Coffee, Grocery, Parks, Museums
- Schools, Hospitals, Hotels, EV Chargers

## Features

- ✅ Interactive MapLibre map with OpenStreetMap tiles
- ✅ Search by category, text, or both
- ✅ Adjustable search radius with visual overlay
- ✅ Pin markers that highlight on click
- ✅ Interactive results list (click to pan/zoom)
- ✅ Category filter chips
- ✅ Light and dark mode support
- ✅ Responsive layout (desktop + mobile)
- ✅ Full Zod validation on every request/response
- ✅ Strict TypeScript throughout
- ✅ Cloudflare Workers + Pages deployment

## Deployment

See [Deployment Guide](docs/DEPLOYMENT.md) for instructions on deploying to Cloudflare and registering with ChatGPT.