npm - bbox-mcp-server - Versions diffs - 1.1.0 → 1.2.0 - Mend

bbox-mcp-server 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -1,30 +1,47 @@
-# bbox-mcp-server
+# 🌍 bbox-mcp-server
-An [MCP](https://modelcontextprotocol.io/) server that gives AI agents geospatial superpowers — coordinate conversion, EPSG projections, H3 indexing, and shareable map links.
+The geospatial toolkit for AI agents. **6 tools, zero config** — give any LLM the ability to parse, convert, query, and aggregate spatial data out of the box.
-Every response includes a link to [vibhorsingh.com/boundingbox](https://vibhorsingh.com/boundingbox/) so you can visually verify results on an interactive map.
+Every response includes a verification link to **[vibhorsingh.com/boundingbox](https://vibhorsingh.com/boundingbox/)** so you can visually confirm results on an interactive map.
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org/) [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 ---
-## Why use this?
+## Why This Exists
-- **Parse any coordinate format** — raw coords, WKT, GeoJSON, or `ogrinfo` output
-- **Project to 3900+ coordinate systems** — unknown codes auto-fetched from [epsg.io](https://epsg.io)
-- **Generate H3 hex grids** — cell IDs + optional GeoJSON boundaries
-- **Visual verification** — every response links to the [Bounding Box tool](https://vibhorsingh.com/boundingbox/) with coords pre-loaded
+| The problem | How bbox-mcp solves it |
+|---|---|
+| *"I have WKT but the API needs a GeoJSON bbox in EPSG:3857."* | Parses 6 input formats, projects to 3,900+ EPSG codes, outputs in 9 formats — in one call. |
+| *"I keep getting the wrong OSM tags for Overpass queries."* | `list_osm_tags` returns curated tag combos. No more hallucinated `amenity=grocery`. |
+| *"How many hospitals are in this district?"* | `aggregate_overpass_h3` queries Overpass and bins results into H3 hexagons server-side. |
+| *"Is this bounding box actually correct?"* | Every response includes a clickable map link for visual verification. |
+---
+## Tools at a Glance
+| Tool | What it does | Key params |
+|---|---|---|
+| `get_bounds` | Convert and project a bbox across formats and coordinate systems | `bbox`, `epsg`, `format`, `coord_order`, `zoom` |
+| `get_h3_indices` | Generate H3 hex cell indices covering a bbox | `bbox`, `resolution`, `compact` |
+| `generate_share_url` | Create a shareable map link for a bbox | `bbox` |
+| `search_overpass` | Query OpenStreetMap via Overpass QL | `bbox`, `query`, `limit` |
+| `list_osm_tags` | Look up correct OSM tags for a category | `category` |
+| `aggregate_overpass_h3` | Run an Overpass query and bin results into H3 hexagons | `bbox`, `query`, `resolution` |
+All tools accept `location` (natural language, requires Mapbox token) or `bbox` (coordinates, WKT, GeoJSON, etc).
 ---
 ## Quick Start
-Add the server to your MCP client config — **no install, no API keys required**.
+Add to your MCP client config:
-### Claude Desktop
+<details>
+<summary><b>Claude Desktop</b> <i>(Click to expand)</i></summary>
 Add to `claude_desktop_config.json`:
 ```json
 {
   "mcpServers": {
@@ -35,11 +52,12 @@ Add to `claude_desktop_config.json`:
   }
 }
 ```
+</details>
-### Cursor
+<details>
+<summary><b>Cursor</b> <i>(Click to expand)</i></summary>
 Add to `.cursor/mcp.json`:
 ```json
 {
   "mcpServers": {
@@ -50,11 +68,12 @@ Add to `.cursor/mcp.json`:
   }
 }
 ```
+</details>
-### Windsurf
+<details>
+<summary><b>Windsurf</b> <i>(Click to expand)</i></summary>
 Add to `~/.codeium/windsurf/mcp_config.json`:
 ```json
 {
   "mcpServers": {
@@ -65,11 +84,12 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
   }
 }
 ```
+</details>
-### VS Code
-Add to `.vscode/mcp.json` in your workspace (requires [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot)):
+<details>
+<summary><b>VS Code (GitHub Copilot)</b> <i>(Click to expand)</i></summary>
+Add to `.vscode/mcp.json` in your workspace:
 ```json
 {
   "servers": {
@@ -80,12 +100,13 @@ Add to `.vscode/mcp.json` in your workspace (requires [GitHub Copilot](https://m
   }
 }
 ```
+</details>
-That's it — start prompting. Try: *"Get the bounding box for Central Park in WKT format"*
+<br/>
-### Optional: enable location search
+> Try: *"Get the bounding box for Central Park in WKT format"*
-By default, you pass coordinates directly via the `bbox` parameter. To enable natural-language location search (e.g. *"San Francisco"*), add a [Mapbox access token](https://account.mapbox.com/access-tokens/):
+### Optional Configuration
 ```json
 {
@@ -94,46 +115,40 @@ By default, you pass coordinates directly via the `bbox` parameter. To enable na
       "command": "npx",
       "args": ["-y", "bbox-mcp-server"],
       "env": {
-        "MAPBOX_ACCESS_TOKEN": "pk.your-token-here"
+        "MAPBOX_ACCESS_TOKEN": "pk.your-token-here",
+        "OVERPASS_API_URL": "https://your.custom.overpass.instance/api/interpreter"
       }
     }
   }
 }
 ```
-### Other options
 | Variable | Default | Description |
 |---|---|---|
-| `MAX_H3_CELLS` | `50000` | Safety cap for H3 grid generation at high resolutions |
-### Install globally (alternative to npx)
-```bash
-npm install -g bbox-mcp-server
-```
+| `MAPBOX_ACCESS_TOKEN` | — | Enables natural language location search (e.g. *"San Francisco"*) |
+| `OVERPASS_API_URL` | auto | Custom Overpass endpoint. By default, rotates between `overpass-api.de` and `kumi.systems`. |
+| `MAX_H3_CELLS` | `50000` | Safety cap for H3 grid generation |
-Then use `"command": "bbox-mcp-server"` instead of the npx command in any of the configs above.
+*Or install globally: `npm install -g bbox-mcp-server`*
 ---
-## Tools
+## Tool Reference
 ### `get_bounds`
-Convert and project a bounding box across formats and coordinate systems.
+Convert and project a bounding box across 6 input formats, 9 output formats, and 3,900+ coordinate systems. Returns the center point and tile coordinates for the centroid.
-**Input** (one of `location` or `bbox` required):
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `bbox` | string | — | Input geometry (coordinates, WKT, GeoJSON, ogrinfo extent) |
+| `epsg` | string | `"4326"` | Target projection. Unknown codes auto-fetched from epsg.io. |
+| `format` | string | `"csv"` | Output: `csv`, `wkt`, `geojson-bbox`, `geojson-polygon`, `leaflet`, `overpass`, `ogc-bbox`, `kml`, `stac-bbox` |
+| `coord_order` | string | `"lng,lat"` | Swap to `"lat,lng"` for APIs that expect latitude first |
+| `zoom` | number | `15` | Zoom level for tile coordinate calculation |
+| `precision` | number | `6` | Decimal places in formatted output |
-| Param | Type | Description |
-|---|---|---|
-| `location` | string | Text search (e.g. `"San Francisco"`). Requires `MAPBOX_ACCESS_TOKEN`. |
-| `bbox` | string | Any parseable geometry — `"lat1,lng1,lat2,lng2"`, WKT, GeoJSON, or ogrinfo extent. |
-| `epsg` | string | Target EPSG code (default `"4326"`). Unknown codes auto-fetched from epsg.io. |
-| `format` | string | Output format: `csv`, `wkt`, `geojson-bbox`, `geojson-polygon`, `leaflet`, `overpass`, `ogc-bbox`, `kml`, `stac-bbox` |
-| `precision` | number | Decimal places (default `6`) |
-**Example prompt:** *"Get the bounding box for Central Park in WKT format projected to EPSG:32618"*
+**💡 Prompt:** *"Get the bounding box for Central Park in WKT format projected to EPSG:32618"*
 ---
@@ -141,78 +156,116 @@ Convert and project a bounding box across formats and coordinate systems.
 Generate Uber H3 hexagonal cell indices covering a bounding box.
-**Input** (one of `location` or `bbox` required):
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `bbox` | string | — | Input geometry |
+| `resolution` | number | — | H3 resolution (0–15) |
+| `compact` | boolean | `false` | Merge cells into coarser parents where possible |
+| `return_geometry` | boolean | `false` | Include GeoJSON hex boundaries |
+**💡 Prompt:** *"Give me H3 cells at resolution 7 for downtown Chicago, include the hex geometries"*
+---
+### `search_overpass`
+Execute an Overpass QL query within a bounding box. Returns structured results with names, coordinates, and tags.
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `bbox` | string | — | Input geometry |
+| `query` | string | — | Overpass QL (e.g. `nwr["amenity"="cafe"]`). The server wraps it in a bbox filter automatically. |
+| `limit` | number | `100` | Max elements returned |
+**💡 Prompt:** *"Search for nwr["amenity"="bench"] in Central Park, limit 50"*
+---
+### `list_osm_tags`
+Look up the correct OpenStreetMap tags for a category before writing an Overpass query.
 | Param | Type | Description |
 |---|---|---|
-| `location` | string | Text search. Requires `MAPBOX_ACCESS_TOKEN`. |
-| `bbox` | string | Any parseable geometry. |
-| `resolution` | number | **Required.** H3 resolution `0`–`15`. |
-| `compact` | boolean | Compact mixed-resolution output (default `false`) |
-| `return_geometry` | boolean | Include GeoJSON hex boundaries (default `false`) |
+| `category` | string | Broad category (e.g. `"food"`, `"health"`, `"transport"`) |
-**Example prompt:** *"Give me H3 cells at resolution 7 for downtown Chicago, include the hex geometries"*
+**💡 Prompt:** *"What are the correct OSM tags for supermarkets?"*
+---
+### `aggregate_overpass_h3`
+Run an Overpass query and bin results into H3 hexagons for spatial density analysis. Returns counts per cell and GeoJSON hex boundaries.
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `bbox` | string | — | Input geometry |
+| `query` | string | — | Overpass QL core query |
+| `resolution` | number | `8` | H3 resolution for binning |
+**💡 Prompt:** *"Aggregate all hospitals in Seattle into H3 bins at resolution 7"*
 ---
 ### `generate_share_url`
-Generate a shareable link to visualize a bounding box on the interactive map tool.
+Generate a shareable link to visualize a bounding box on the interactive map at vibhorsingh.com/boundingbox.
 | Param | Type | Description |
 |---|---|---|
-| `bbox` | string | **Required.** Any parseable geometry. |
+| `bbox` | string | Input geometry |
-**Example prompt:** *"Generate a share link for bbox 40.7128,-74.0060,40.7580,-73.9855"*
+**💡 Prompt:** *"Generate a share link for bbox 40.7128,-74.0060,40.7580,-73.9855"*
 ---
 ## Supported Input Formats
-All tools accept these formats through the `bbox` parameter:
+All tools auto-detect the input format. No need to specify which one you're using.
 | Format | Example |
 |---|---|
-| **Raw coordinates** | `40.7128,-74.0060,40.7580,-73.9855` |
-| **WKT** | `POLYGON((-74.006 40.712, -73.985 40.712, ...))` |
-| **GeoJSON** | `{"type":"Feature","geometry":{...}}` |
-| **GeoJSON bbox** | `{"bbox":[-74.006,40.712,-73.985,40.758]}` |
-| **ogrinfo extent** | `Extent: (-74.006, 40.712) - (-73.985, 40.758)` |
-| **Space-separated (GDAL)** | `40.7128 -74.0060 40.7580 -73.9855` |
+| Raw coordinates | `40.7128,-74.0060,40.7580,-73.9855` |
+| WKT | `POLYGON((-74.006 40.712, -73.985 40.712, ...))` |
+| GeoJSON | `{"type":"Feature","geometry":{...}}` |
+| GeoJSON bbox | `{"bbox":[-74.006,40.712,-73.985,40.758]}` |
+| ogrinfo extent | `Extent: (-74.006, 40.712) - (-73.985, 40.758)` |
+| Space-separated | `40.7128 -74.0060 40.7580 -73.9855` |
 ---
-## For AI Agent Developers
+## 🤖 For AI Agent Developers
+### Response structure
-### What agents get back
+Every tool returns two content blocks:
-Every tool response includes two content blocks:
+1. **Human-readable text** — formatted output with the map verification link
+2. **Structured JSON** — all computed data, machine-parseable
-1. **Human-readable text** — formatted for display, includes the map link
-2. **Structured JSON** — machine-parseable with all computed data
+Example `get_bounds` JSON response:
 ```json
 {
   "original_wgs84": { "lat1": 40.7128, "lng1": -74.006, "lat2": 40.758, "lng2": -73.9855 },
   "projected": { "xmin": -8238310.23, "ymin": 4970241.32, "xmax": -8235527.11, "ymax": 4976491.56 },
+  "center": { "lat": 40.7354, "lng": -73.99575 },
+  "tile_indices": { "z": 15, "x": 9660, "y": 12284 },
   "epsg": "3857",
+  "coord_order": "lng,lat",
   "area_km2": 8.681,
   "dimensions": { "width_km": 1.714, "height_km": 5.066 },
   "share_url": "https://vibhorsingh.com/boundingbox/#40.712800,-74.006000,40.758000,-73.985500"
 }
 ```
-### Verification pattern
-The `share_url` in every response opens the visual BBox Finder tool with the exact coordinates pre-loaded. Agents can present this link to users for visual confirmation.
 ### Error handling
-All errors return `isError: true` with a descriptive message. The server never crashes on bad input — invalid coordinates, unknown EPSG codes, and oversized H3 areas all return clean error responses.
+All errors return `isError: true` with a descriptive message. Invalid coordinates, unknown EPSG codes, and oversized H3 requests all return clean errors — the server never crashes on bad input.
 ### Logging
-Structured JSON logs are written to **stderr** (not stdout, which is reserved for the MCP protocol). Each log entry includes timestamp, level, and context data.
+Structured JSON logs go to **stderr** (stdout is reserved for MCP protocol). Each entry includes timestamp, level, and context.
 ---

package/dist/index.js CHANGED Viewed

@@ -7,7 +7,7 @@ import proj4 from "proj4";
 import proj4defs from "./proj4defs.json" with { type: "json" };
 import { wktToGeoJSON as parseWKT } from "@terraformer/wkt";
 const SERVER_NAME = "bbox-mcp-server";
-const SERVER_VERSION = "1.1.0";
+const SERVER_VERSION = "1.2.0";
 const MAX_H3_CELLS = process.env.MAX_H3_CELLS ? parseInt(process.env.MAX_H3_CELLS, 10) : 50000;
 const MAPBOX_ACCESS_TOKEN = process.env.MAPBOX_ACCESS_TOKEN;
 const MAX_INPUT_LENGTH = 1_000_000; // 1 MB input size guard
@@ -240,11 +240,22 @@ async function ensureProjection(epsg) {
         clearTimeout(timeout);
     }
 }
-function getFormattedBox(bbox, format, precision = 6) {
-    const xmin = bbox.lng1.toFixed(precision);
-    const ymin = bbox.lat1.toFixed(precision);
-    const xmax = bbox.lng2.toFixed(precision);
-    const ymax = bbox.lat2.toFixed(precision);
+function getFormattedBox(bbox, format, precision = 6, coordOrder = "lng,lat") {
+    let xmin, ymin, xmax, ymax;
+    if (coordOrder === "lat,lng") {
+        // Swap X and Y coordinates
+        xmin = bbox.lat1.toFixed(precision);
+        ymin = bbox.lng1.toFixed(precision);
+        xmax = bbox.lat2.toFixed(precision);
+        ymax = bbox.lng2.toFixed(precision);
+    }
+    else {
+        // Default lng,lat order
+        xmin = bbox.lng1.toFixed(precision);
+        ymin = bbox.lat1.toFixed(precision);
+        xmax = bbox.lng2.toFixed(precision);
+        ymax = bbox.lat2.toFixed(precision);
+    }
     switch (format.toLowerCase()) {
         case 'wkt':
             return `POLYGON(( ${xmin} ${ymin}, ${xmax} ${ymin}, ${xmax} ${ymax}, ${xmin} ${ymax}, ${xmin} ${ymin} ))`;
@@ -294,6 +305,13 @@ function calculateBboxArea(bbox) {
     const { widthKm, heightKm } = calculateBboxDimensions(bbox);
     return widthKm * heightKm;
 }
+function latLngToTile(lat, lng, zoom) {
+    const n = Math.pow(2, zoom);
+    const x = Math.floor((lng + 180) / 360 * n);
+    const latRad = lat * Math.PI / 180;
+    const y = Math.floor((1 - Math.log(Math.tan(latRad) + 1 / Math.cos(latRad)) / Math.PI) / 2 * n);
+    return { z: zoom, x, y };
+}
 function buildShareUrl(bbox) {
     const hash = `${bbox.lat1.toFixed(6)},${bbox.lng1.toFixed(6)},${bbox.lat2.toFixed(6)},${bbox.lng2.toFixed(6)}`;
     return `https://vibhorsingh.com/boundingbox/#${hash}`;
@@ -439,6 +457,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             description: "Format of the output. Options: wkt, geojson-bbox, leaflet, overpass, ogc-bbox, kml, geojson-polygon, csv, stac-bbox. Default: csv.",
                             enum: ["wkt", "geojson-bbox", "leaflet", "overpass", "ogc-bbox", "kml", "geojson-polygon", "csv", "stac-bbox"]
                         },
+                        coord_order: {
+                            type: "string",
+                            description: "Toggle between 'lng,lat' (default) and 'lat,lng' coordinate ordering in the formatted output. Useful for APIs that expect swapped coordinate orders.",
+                            enum: ["lng,lat", "lat,lng"]
+                        },
+                        zoom: {
+                            type: "number",
+                            description: "The map zoom level (0-22) used to calculate the map tile coordinates for the centroid. Defaults to 15."
+                        },
                         precision: {
                             type: "number",
                             description: "The number of decimal places to output coordinate strings as (defaults to 6)."
@@ -497,6 +524,80 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     },
                     required: ["bbox"],
                 },
+            },
+            {
+                name: "search_overpass",
+                description: "Execute an Overpass QL query to find POIs, roads, or other OSM features within a bounding box. You must provide the base query. The server automatically wraps it in a bbox filter and returns structured JSON.\n\nCOMMON TAG EXAMPLES:\n- Restaurants: `nwr[\"amenity\"=\"restaurant\"]`\n- Pizza: `nwr[\"amenity\"=\"fast_food\"][\"cuisine\"=\"pizza\"]`\n- Supermarkets: `nwr[\"shop\"=\"supermarket\"]`\n- Parks: `nwr[\"leisure\"=\"park\"]`\n- Hospitals: `nwr[\"amenity\"=\"hospital\"]`\n- Schools: `nwr[\"amenity\"=\"school\"]`\n- Parking: `nwr[\"amenity\"=\"parking\"]`\n- Highways/Roads: `way[\"highway\"]`",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        location: {
+                            type: "string",
+                            description: "A text location to search for (e.g. 'San Francisco'). Requires MAPBOX_ACCESS_TOKEN env var. Either 'location' or 'bbox' MUST be provided."
+                        },
+                        bbox: {
+                            type: "string",
+                            description: "The geometry to parse. Can be a raw bounding box string ('lat1,lng1,lat2,lng2'), WKT, GeoJSON, or ogrinfo extent. Either 'location' or 'bbox' MUST be provided.",
+                        },
+                        query: {
+                            type: "string",
+                            description: "The Overpass QL core query. Example: `node[\"amenity\"=\"cafe\"]` or `nwr[\"leisure\"=\"park\"]`. DO NOT include the bounding box `(S,W,N,E)` or output format (`out json`), the server handles that automatically."
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Maximum number of elements to return. Helps prevent enormous JSON responses. Default is 100. Set to a higher number if you need more results."
+                        }
+                    },
+                    required: ["query"],
+                    oneOf: [
+                        { required: ["location"] },
+                        { required: ["bbox"] }
+                    ]
+                },
+            },
+            {
+                name: "list_osm_tags",
+                description: "Discovery tool to look up the correct OpenStreetMap tags for a given category. Helps prevent hallucinating incorrect tags before writing an Overpass query.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        category: {
+                            type: "string",
+                            description: "Broad category to look up (e.g. 'food', 'health', 'transport', 'leisure', 'retail')."
+                        }
+                    },
+                    required: ["category"]
+                }
+            },
+            {
+                name: "aggregate_overpass_h3",
+                description: "Executes an Overpass query and bins the results into H3 hexagons at a specified resolution to analyze spatial density.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        location: {
+                            type: "string",
+                            description: "A text location to search for (e.g. 'Seattle')."
+                        },
+                        bbox: {
+                            type: "string",
+                            description: "The bounding box geometry to parse."
+                        },
+                        query: {
+                            type: "string",
+                            description: "The Overpass QL core query (e.g. `nwr[\"amenity\"=\"cafe\"]`)."
+                        },
+                        resolution: {
+                            type: "number",
+                            description: "The H3 resolution level (0-15) for binning. Default is 8."
+                        }
+                    },
+                    required: ["query", "resolution"],
+                    oneOf: [
+                        { required: ["location"] },
+                        { required: ["bbox"] }
+                    ]
+                }
             }
         ],
     };
@@ -530,12 +631,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             let epsg = args.epsg || "4326";
             let format = args.format || "csv";
+            let coordOrder = args.coord_order || "lng,lat";
+            let zoom = args.zoom || 15;
             let precision = args.precision || 6;
             epsg = epsg.replace(/[^0-9]/g, "");
             // Dynamically fetch projection if not bundled
             await ensureProjection(epsg);
             const projCoords = projectBounds(bboxObj, epsg);
-            const WGS84Formatted = getFormattedBox(bboxObj, format, precision);
+            const WGS84Formatted = getFormattedBox(bboxObj, format, precision, coordOrder);
             // Build projected bbox for formatting (uses projected values)
             const projBbox = {
                 lat1: projCoords.ymin,
@@ -543,10 +646,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 lat2: projCoords.ymax,
                 lng2: projCoords.xmax
             };
-            const projectedFormatted = getFormattedBox(projBbox, format, precision);
+            const projectedFormatted = getFormattedBox(projBbox, format, precision, coordOrder);
             const shareUrl = buildShareUrl(bboxObj);
             const dims = calculateBboxDimensions(bboxObj);
             const areaKm2 = calculateBboxArea(bboxObj);
+            // Calculate center and tile indices based on WGS84 original bounds
+            const centerLat = (bboxObj.lat1 + bboxObj.lat2) / 2;
+            const centerLng = (bboxObj.lng1 + bboxObj.lng2) / 2;
+            const tileIndices = latLngToTile(centerLat, centerLng, zoom);
             log('info', `get_bounds completed`, { epsg, format, area_km2: areaKm2 });
             return {
                 content: [
@@ -559,8 +666,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         text: JSON.stringify({
                             original_wgs84: bboxObj,
                             projected: projCoords,
+                            center: {
+                                lat: centerLat,
+                                lng: centerLng
+                            },
+                            tile_indices: tileIndices,
                             epsg,
                             format,
+                            coord_order: coordOrder,
                             precision,
                             area_km2: areaKm2,
                             dimensions: {
@@ -652,6 +765,308 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ]
             };
         }
+        else if (toolName === "search_overpass") {
+            const args = request.params.arguments || {};
+            const queryRaw = args.query;
+            const limit = args.limit || 100;
+            if (!queryRaw) {
+                return { content: [{ type: "text", text: "Error: 'query' is required (e.g. `node[\"amenity\"=\"restaurant\"]`)." }], isError: true };
+            }
+            if (queryRaw.length > 2000) {
+                return { content: [{ type: "text", text: "Error: Query is too long (maximum 2000 characters)." }], isError: true };
+            }
+            if (queryRaw.includes("[out:") || queryRaw.includes("[timeout:") || queryRaw.includes("[bbox:")) {
+                return { content: [{ type: "text", text: "Error: Query must not contain direct [out:], [timeout:], or [bbox:] directives. The server handles these automatically." }], isError: true };
+            }
+            let bboxObj;
+            if (args.location) {
+                try {
+                    bboxObj = await geocodeLocation(args.location);
+                }
+                catch (err) {
+                    if (!args.bbox) {
+                        log('error', `Geocoding failed for overpass location: ${args.location}`, { error: err.message });
+                        return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
+                    }
+                    bboxObj = parseBBox(args.bbox);
+                }
+            }
+            else if (args.bbox) {
+                bboxObj = parseBBox(args.bbox);
+            }
+            else {
+                return { content: [{ type: "text", text: "Error: Either 'location' or 'bbox' argument must be provided." }], isError: true };
+            }
+            log('info', `search_overpass starting`, { query: queryRaw });
+            const overpassQuery = `[out:json][timeout:25][bbox:${bboxObj.lat1},${bboxObj.lng1},${bboxObj.lat2},${bboxObj.lng2}];\n(${queryRaw};);\nout center;`;
+            const endpoints = [
+                "https://overpass-api.de/api/interpreter",
+                "https://overpass.kumi.systems/api/interpreter"
+            ];
+            if (process.env.OVERPASS_API_URL) {
+                endpoints.unshift(process.env.OVERPASS_API_URL);
+            }
+            let data = null;
+            let lastError = null;
+            // Formatting payload precisely for Overpass
+            const params = new URLSearchParams();
+            params.append('data', overpassQuery);
+            for (const endpoint of endpoints) {
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS * 2);
+                try {
+                    log('info', `Executing Overpass query at ${endpoint}`);
+                    const response = await fetch(endpoint, {
+                        method: "POST",
+                        body: params.toString(),
+                        headers: {
+                            'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8',
+                            'Accept': 'application/json',
+                            'User-Agent': `${SERVER_NAME}/${SERVER_VERSION}`
+                        },
+                        signal: controller.signal
+                    });
+                    if (!response.ok) {
+                        throw new Error(`Overpass API returned status: ${response.status} ${response.statusText}`);
+                    }
+                    data = await response.json();
+                    break; // Success!
+                }
+                catch (err) {
+                    lastError = err;
+                    log('warn', `Overpass API failed at ${endpoint}`, { error: err.message });
+                }
+                finally {
+                    clearTimeout(timeout);
+                }
+            }
+            if (!data) {
+                if (lastError?.name === 'AbortError') {
+                    return { content: [{ type: "text", text: `Error: Overpass API request timed out on all endpoints after ${(FETCH_TIMEOUT_MS * 4) / 1000}s overall. The query might be too broad.` }], isError: true };
+                }
+                throw new Error(`Overpass query failed on all endpoints: ${lastError?.message}`);
+            }
+            let rawElements = data.elements || [];
+            // Parse raw elements into structured output
+            const seenIds = new Set();
+            let parsedElements = rawElements.reduce((acc, e) => {
+                if (seenIds.has(e.id))
+                    return acc;
+                seenIds.add(e.id);
+                const lat = e.lat ?? e.center?.lat;
+                const lon = e.lon ?? e.center?.lon;
+                // Only keep elements that actually have coordinates and tags (or allow untagged if requested, but structured output is better)
+                if (lat !== undefined && lon !== undefined) {
+                    acc.push({
+                        id: e.id,
+                        type: e.type,
+                        name: e.tags?.name || "Unnamed",
+                        coordinates: { lat, lon },
+                        tags: e.tags || {}
+                    });
+                }
+                return acc;
+            }, []);
+            const elementCount = parsedElements.length;
+            let truncated = false;
+            if (parsedElements.length > limit) {
+                parsedElements = parsedElements.slice(0, limit);
+                truncated = true;
+            }
+            const shareUrl = buildShareUrl(bboxObj);
+            log('info', `search_overpass completed`, { elements: elementCount, returned: parsedElements.length, truncated });
+            const responseData = {
+                generator: data.generator,
+                osm3s: data.osm3s,
+                elements: parsedElements,
+                total_count: elementCount,
+                returned_count: parsedElements.length,
+                truncated,
+                original_bbox: bboxObj,
+                share_url: shareUrl
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Successfully executed Overpass query.\nFound ${elementCount} elements${truncated ? ` (truncated to ${limit})` : ''}.\n\nSummary:\n${parsedElements.slice(0, 5).map((e) => `- [${e.type}] ${e.id} (${e.name})`).join('\n')}${parsedElements.length > 5 ? '\n... (see JSON for full results)' : ''}\n\nView original bounding box on map: ${shareUrl}`
+                    },
+                    {
+                        type: "text",
+                        text: JSON.stringify(responseData, null, 2)
+                    }
+                ]
+            };
+        }
+        else if (toolName === "list_osm_tags") {
+            const args = request.params.arguments || {};
+            const category = (args.category || "").toLowerCase();
+            let recommendations = "";
+            switch (true) {
+                case category.includes('food') || category.includes('restaurant') || category.includes('cafe'):
+                    recommendations = `Restaurants: nwr["amenity"="restaurant"]\nFast Food: nwr["amenity"="fast_food"]\nCafes: nwr["amenity"="cafe"]\nBars: nwr["amenity"="bar"]\nPubs: nwr["amenity"="pub"]`;
+                    break;
+                case category.includes('health') || category.includes('medical'):
+                    recommendations = `Hospitals: nwr["amenity"="hospital"]\nClinics: nwr["amenity"="clinic"]\nPharmacies: nwr["amenity"="pharmacy"]\nDoctors: nwr["amenity"="doctors"]\nDentists: nwr["amenity"="dentist"]`;
+                    break;
+                case category.includes('transport') || category.includes('transit') || category.includes('traffic'):
+                    recommendations = `Parking: nwr["amenity"="parking"]\nBus Stops: nwr["highway"="bus_stop"]\nSubway Stations: nwr["railway"="station"]["station"="subway"]\nTrain Stations: nwr["railway"="station"]\nBicycle Parking: nwr["amenity"="bicycle_parking"]\nGas Stations: nwr["amenity"="fuel"]`;
+                    break;
+                case category.includes('leisure') || category.includes('park') || category.includes('entertainment'):
+                    recommendations = `Parks: nwr["leisure"="park"]\nPlaygrounds: nwr["leisure"="playground"]\nTheatres: nwr["amenity"="theatre"]\nCinemas: nwr["amenity"="cinema"]\nSports Centres: nwr["leisure"="sports_centre"]`;
+                    break;
+                case category.includes('retail') || category.includes('shop') || category.includes('store'):
+                    recommendations = `Supermarkets: nwr["shop"="supermarket"]\nConvenience Stores: nwr["shop"="convenience"]\nMalls: nwr["shop"="mall"]\nClothes Shops: nwr["shop"="clothes"]\nBakeries: nwr["shop"="bakery"]`;
+                    break;
+                case category.includes('education') || category.includes('school'):
+                    recommendations = `Schools: nwr["amenity"="school"]\nUniversities: nwr["amenity"="university"]\nColleges: nwr["amenity"="college"]\nKindergartens: nwr["amenity"="kindergarten"]\nLibraries: nwr["amenity"="library"]`;
+                    break;
+                case category.includes('tourism') || category.includes('hotel'):
+                    recommendations = `Hotels: nwr["tourism"="hotel"]\nMotels: nwr["tourism"="motel"]\nHostels: nwr["tourism"="hostel"]\nAttractions: nwr["tourism"="attraction"]\nMuseums: nwr["tourism"="museum"]\nInformation: nwr["tourism"="information"]`;
+                    break;
+                default:
+                    recommendations = `Top categories:\n- Food: nwr["amenity"="restaurant"], nwr["amenity"="cafe"]\n- Health: nwr["amenity"="hospital"]\n- Transport: nwr["highway"="bus_stop"], nwr["amenity"="parking"]\n- Leisure: nwr["leisure"="park"]\n- Retail: nwr["shop"="supermarket"]\n- Education: nwr["amenity"="school"]\n\nPlease try searching for one of those broader categories (e.g. "health") for more detailed tag combinations.`;
+                    break;
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: `OSM Tag Recommendations for '${category}':\n\n${recommendations}\n\nTip: You can usually just use these directly as the 'query' argument in search_overpass.`
+                    }]
+            };
+        }
+        else if (toolName === "aggregate_overpass_h3") {
+            const args = request.params.arguments || {};
+            const queryRaw = args.query;
+            const resolution = args.resolution || 8;
+            if (!queryRaw) {
+                return { content: [{ type: "text", text: "Error: 'query' is required." }], isError: true };
+            }
+            let bboxObj;
+            if (args.location) {
+                try {
+                    bboxObj = await geocodeLocation(args.location);
+                }
+                catch (err) {
+                    if (!args.bbox) {
+                        return { content: [{ type: "text", text: `Error: Geocoding failed: ${err.message}` }], isError: true };
+                    }
+                    bboxObj = parseBBox(args.bbox);
+                }
+            }
+            else if (args.bbox) {
+                bboxObj = parseBBox(args.bbox);
+            }
+            else {
+                return { content: [{ type: "text", text: "Error: Either 'location' or 'bbox' argument must be provided." }], isError: true };
+            }
+            log('info', `aggregate_overpass_h3 starting`, { query: queryRaw, resolution });
+            // Ensure H3 resolution is valid early
+            if (resolution < 0 || resolution > 15 || !Number.isInteger(resolution)) {
+                return { content: [{ type: "text", text: `Error: Invalid H3 resolution: ${resolution}. Must be 0-15.` }], isError: true };
+            }
+            const overpassQuery = `[out:json][timeout:25][bbox:${bboxObj.lat1},${bboxObj.lng1},${bboxObj.lat2},${bboxObj.lng2}];\n(${queryRaw};);\nout center;`;
+            let data = null;
+            let lastError = null;
+            const params = new URLSearchParams();
+            params.append('data', overpassQuery);
+            const endpoints = [
+                "https://overpass-api.de/api/interpreter",
+                "https://overpass.kumi.systems/api/interpreter"
+            ];
+            if (process.env.OVERPASS_API_URL) {
+                endpoints.unshift(process.env.OVERPASS_API_URL);
+            }
+            for (const endpoint of endpoints) {
+                const controller = new AbortController();
+                const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS * 2);
+                try {
+                    const response = await fetch(endpoint, {
+                        method: "POST",
+                        body: params.toString(),
+                        headers: {
+                            'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8',
+                            'Accept': 'application/json',
+                            'User-Agent': `${SERVER_NAME}/${SERVER_VERSION}`
+                        },
+                        signal: controller.signal
+                    });
+                    if (!response.ok)
+                        throw new Error(`Status: ${response.status}`);
+                    data = await response.json();
+                    break;
+                }
+                catch (err) {
+                    lastError = err;
+                }
+                finally {
+                    clearTimeout(timeout);
+                }
+            }
+            if (!data) {
+                return { content: [{ type: "text", text: `Error: Overpass query failed: ${lastError?.message}` }], isError: true };
+            }
+            let rawElements = data.elements || [];
+            // Bin into H3 Hexagons
+            const hexCounts = {};
+            const hexElements = {};
+            const seenIds = new Set();
+            rawElements.forEach((e) => {
+                if (seenIds.has(e.id))
+                    return;
+                seenIds.add(e.id);
+                const lat = e.lat ?? e.center?.lat;
+                const lon = e.lon ?? e.center?.lon;
+                if (lat !== undefined && lon !== undefined) {
+                    const h3Index = h3.latLngToCell(lat, lon, resolution);
+                    hexCounts[h3Index] = (hexCounts[h3Index] || 0) + 1;
+                    if (!hexElements[h3Index])
+                        hexElements[h3Index] = [];
+                    // Keep element data minimal to avoid massive payloads
+                    hexElements[h3Index].push({
+                        id: e.id,
+                        name: e.tags?.name || "Unnamed"
+                    });
+                }
+            });
+            const shareUrl = buildShareUrl(bboxObj);
+            const totalGrouped = Object.values(hexCounts).reduce((a, b) => a + b, 0);
+            // Generate GeoJSON of the active hexes
+            const activeHexes = Object.keys(hexCounts);
+            const geojson = h3CellsToGeoJSON(activeHexes);
+            // Inject the counts into the GeoJSON properties
+            geojson.features.forEach((f) => {
+                const cellId = f.properties.h3_index;
+                f.properties.count = hexCounts[cellId];
+                f.properties.elements = hexElements[cellId];
+            });
+            log('info', `aggregate_overpass_h3 completed`, { resolution, elements: totalGrouped, activeHexes: activeHexes.length });
+            const responseData = {
+                resolution,
+                total_elements: totalGrouped,
+                active_hex_count: activeHexes.length,
+                hex_counts: hexCounts,
+                hex_geojson: geojson,
+                original_bbox: bboxObj,
+                share_url: shareUrl
+            };
+            // Sort map for display
+            const topHexes = Object.entries(hexCounts)
+                .sort((a, b) => b[1] - a[1])
+                .slice(0, 10);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Aggregated ${totalGrouped} elements into ${activeHexes.length} H3 hexagons at resolution ${resolution}.\n\nTop Hexagons by Density:\n${topHexes.map(([hex, count]) => `- Hex ${hex}: ${count} elements`).join('\n')}\n\nView bounding area on map: ${shareUrl}`
+                    },
+                    {
+                        type: "text",
+                        text: JSON.stringify(responseData, null, 2)
+                    }
+                ]
+            };
+        }
         else {
             log('warn', `Unknown tool requested: ${toolName}`);
             return {

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
     "name": "bbox-mcp-server",
-    "version": "1.1.0",
-    "description": "MCP server for bounding box coordinate conversion, EPSG projections, Uber H3 hexagonal indexing, and shareable map links",
+    "version": "1.2.0",
+    "description": "MCP server for bounding box coordinate conversion, EPSG projections, Uber H3 hexagonal indexing, Overpass OSM queries, and shareable map links",
     "type": "module",
     "license": "MIT",
     "author": "Vibhor Singh",
@@ -24,7 +24,11 @@
         "h3",
         "hexagonal-grid",
         "wkt",
-        "geojson"
+        "geojson",
+        "overpass",
+        "osm",
+        "openstreetmap",
+        "poi"
     ],
     "bin": {
         "bbox-mcp-server": "./dist/index.js"