mapular-geo-mcp 0.1.0__tar.gz

mapular_geo_mcp-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+data/
+.env
+__pycache__/
+*.pyc
+.venv/

mapular_geo_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: mapular-geo-mcp
+Version: 0.1.0
+Summary: Geospatial analysis MCP server powered by DuckDB spatial + H3
+Requires-Python: >=3.11
+Requires-Dist: duckdb>=0.10.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0

mapular_geo_mcp-0.1.0/README.md

@@ -0,0 +1,102 @@
+# mapular-geo-mcp
+
+Spatial SQL analysis for AI agents — DuckDB with spatial + H3 extensions.
+
+## Quick start
+
+```bash
+uvx mapular-geo-mcp
+```
+
+No credentials needed. Run SQL queries over local geospatial files (Parquet, CSV, GeoJSON) with full spatial and H3 support.
+
+## Claude Code setup
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "mapular-geo-mcp": {
+      "command": "uvx",
+      "args": ["mapular-geo-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `query` | Run DuckDB SQL with spatial + H3 extensions; returns file path + preview rows |
+| `export` | Export SQL results to Parquet, CSV, or GeoJSON |
+| `geocode` | Convert a free-form address to lat/lon coordinates |
+
+**Typical workflow:** `geocode` an address -> `query` nearby POIs with ST_DWithin -> `export` results to GeoJSON.
+
+## Usage examples
+
+### Basic SQL query on a local file
+
+```
+query(sql="SELECT * FROM read_parquet('/tmp/pois.parquet') WHERE category = 'restaurant' LIMIT 10")
+```
+
+### Spatial proximity query (ST_DWithin)
+
+```
+query(sql="""
+  SELECT name, category, latitude, longitude
+  FROM read_parquet('/tmp/pois.parquet')
+  WHERE ST_DWithin(
+    ST_Point(longitude, latitude),
+    ST_Point(13.377, 52.516),  -- Brandenburg Gate
+    0.01                        -- ~1 km in degrees
+  )
+""")
+```
+
+### H3 spatial indexing
+
+```
+query(sql="""
+  SELECT h3_latlng_to_cell(latitude, longitude, 7) AS h3_index,
+         COUNT(*) AS poi_count
+  FROM read_parquet('/tmp/pois.parquet')
+  GROUP BY 1
+  ORDER BY poi_count DESC
+  LIMIT 10
+""")
+```
+
+### Export to GeoJSON
+
+```
+export(
+  sql="SELECT * FROM read_parquet('/tmp/pois.parquet') LIMIT 100",
+  format="geojson"
+)
+```
+
+### Geocode an address
+
+```
+geocode(address="Brandenburg Gate, Berlin")
+# -> {"lat": 52.5163, "lon": 13.3777, "display_name": "...", "confidence": "high", "provider": "nominatim"}
+```
+
+## File path restrictions
+
+The `query` tool restricts `read_parquet()`, `read_csv_auto()`, `read_json()`, and `st_read()` calls to these directories:
+
+- System temp directory (`/tmp` or `$TMPDIR`) — where `mpoi_fetch` writes its output
+- `~/Downloads`
+
+To allow an additional directory, set `MAPULAR_GEO_DATA_DIR=/path/to/data` in the server's environment.
+
+## Companion servers
+
+- **mapular-mpoi-mcp** — Pre-indexed POI data (Overture/OSM). Use `mpoi_fetch` to download a Parquet file, then analyze it here with `query`.
+- **mapular-mapbook-mcp** — Map visualization (future).
+

mapular_geo_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "mapular-geo-mcp"
+version = "0.1.0"
+description = "Geospatial analysis MCP server powered by DuckDB spatial + H3"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "duckdb>=0.10.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.scripts]
+mapular-geo-mcp = "mapular_geo_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mapular_geo_mcp"]
+
+[dependency-groups]
+dev = ["pytest"]

mapular_geo_mcp-0.1.0/src/mapular_geo_mcp/__init__.py

@@ -0,0 +1 @@
+"""mapular-geo-mcp: Geospatial analysis MCP server powered by DuckDB spatial + H3."""

mapular_geo_mcp-0.1.0/src/mapular_geo_mcp/errors.py

@@ -0,0 +1,166 @@
+"""Agent-friendly error classification for DuckDB queries.
+
+Wraps raw DuckDB exceptions into structured, actionable error dicts
+so the LLM agent can understand what went wrong and how to fix it.
+"""
+
+import re
+
+import duckdb
+
+
+def classify_error(exc: Exception) -> dict:
+    """Classify an exception into an agent-actionable error dict.
+
+    Returns:
+        {"error": True, "category": str, "message": str, "hint": str}
+    """
+    msg = str(exc)
+
+    # --- syntax_error: SQL parse failures ---
+    if isinstance(exc, duckdb.ParserException):
+        return _build(
+            "syntax_error",
+            msg,
+            "Check SQL syntax. DuckDB uses PostgreSQL-style SQL. "
+            "Common issues: missing quotes, unsupported keywords, or wrong function names.",
+            recovery={"action": "rewrite_sql"},
+        )
+
+    # --- missing_extension: spatial/H3 function not found ---
+    if isinstance(exc, duckdb.CatalogException) and _looks_like_missing_function(msg):
+        func_name = _extract_function_name(msg)
+        hint = _extension_hint(func_name)
+        setup_sql = _extension_setup_sql(func_name)
+        return _build(
+            "missing_extension",
+            msg,
+            hint,
+            recovery={"action": "retry_with_setup", "setup_sql": setup_sql},
+        )
+
+    # --- file_not_found: input path does not exist ---
+    if isinstance(exc, (FileNotFoundError,)):
+        return _build(
+            "file_not_found",
+            msg,
+            "The file path does not exist. Verify the path and check for typos.",
+            recovery={"action": "check_path"},
+        )
+    if isinstance(exc, duckdb.IOException) and _looks_like_file_not_found(msg):
+        path = _extract_path(msg)
+        return _build(
+            "file_not_found",
+            msg,
+            f"File not found: {path}. Verify the path exists and is accessible.",
+            recovery={"action": "check_path"},
+        )
+
+    # --- timeout: query exceeded time limit ---
+    if _looks_like_timeout(exc, msg):
+        return _build(
+            "timeout",
+            msg,
+            "Query exceeded the time limit. Try adding LIMIT, filtering with WHERE, "
+            "or reducing the dataset size.",
+            recovery={"action": "simplify_query"},
+        )
+
+    # --- oom: memory exceeded ---
+    if isinstance(exc, MemoryError) or _looks_like_oom(msg):
+        return _build(
+            "oom",
+            msg,
+            "Query exceeded available memory. Try using LIMIT, sampling with "
+            "TABLESAMPLE, or filtering to reduce the data size.",
+            recovery={"action": "simplify_query"},
+        )
+
+    # --- unknown: catch-all ---
+    return _build(
+        "unknown",
+        msg,
+        "An unexpected error occurred. Check the message for details.",
+    )
+
+
+def _build(category: str, message: str, hint: str, recovery: dict | None = None) -> dict:
+    d = {
+        "error": True,
+        "category": category,
+        "message": message,
+        "hint": hint,
+    }
+    if recovery:
+        d["recovery"] = recovery
+    return d
+
+
+def _looks_like_missing_function(msg: str) -> bool:
+    lower = msg.lower()
+    return "does not exist" in lower and ("function" in lower or "macro" in lower)
+
+
+def _extract_function_name(msg: str) -> str:
+    # "Scalar Function with name st_point does not exist!"
+    match = re.search(r"name\s+(\w+)\s+does not exist", msg, re.IGNORECASE)
+    return match.group(1) if match else ""
+
+
+def _extension_hint(func_name: str) -> str:
+    lower = func_name.lower()
+    if lower.startswith("st_"):
+        return (
+            f"Function '{func_name}' requires the spatial extension. "
+            "Run: INSTALL spatial; LOAD spatial;"
+        )
+    if lower.startswith("h3"):
+        return (
+            f"Function '{func_name}' requires the H3 extension. "
+            "Run: INSTALL h3 FROM community; LOAD h3;"
+        )
+    return (
+        f"Function '{func_name}' not found. It may require an extension. "
+        "Check https://duckdb.org/docs/extensions/overview for available extensions."
+    )
+
+
+def _extension_setup_sql(func_name: str) -> str:
+    """Return the SQL needed to install and load the extension for a function."""
+    lower = func_name.lower()
+    if lower.startswith("st_"):
+        return "INSTALL spatial; LOAD spatial;"
+    if lower.startswith("h3"):
+        return "INSTALL h3 FROM community; LOAD h3;"
+    return f"-- Unknown extension for '{func_name}'. Check DuckDB docs."
+
+
+def _looks_like_file_not_found(msg: str) -> bool:
+    lower = msg.lower()
+    return any(
+        pattern in lower
+        for pattern in [
+            "no such file",
+            "file not found",
+            "does not exist",
+            "cannot open",
+            "no files found",
+        ]
+    )
+
+
+def _extract_path(msg: str) -> str:
+    match = re.search(r"['\"]([^'\"]+)['\"]", msg)
+    return match.group(1) if match else "(unknown path)"
+
+
+def _looks_like_timeout(exc: Exception, msg: str) -> bool:
+    lower = msg.lower()
+    if "timeout" in lower or "cancelled" in lower or "interrupted" in lower:
+        return True
+    return isinstance(exc, duckdb.InvalidInputException) and "interrupt" in lower
+
+
+def _looks_like_oom(msg: str) -> bool:
+    lower = msg.lower()
+    return "out of memory" in lower or ("memory" in lower and "exceed" in lower)

mapular_geo_mcp-0.1.0/src/mapular_geo_mcp/export.py

@@ -0,0 +1,108 @@
+"""Export query results to Parquet, CSV, or GeoJSON.
+
+Reuses the persistent GeoSession from session.py.
+Views and tables persist across calls within the same process.
+
+SECURITY: LOCAL-ONLY tool — DuckDB SQL can access the local filesystem.
+"""
+
+import tempfile
+from datetime import datetime
+from pathlib import Path
+from uuid import uuid4
+
+from mapular_geo_mcp.errors import classify_error
+from mapular_geo_mcp.query import _copy_with_geometry_fallback
+from mapular_geo_mcp.session import _session
+
+SUPPORTED_FORMATS = ("parquet", "csv", "geojson")
+
+
+def export_query(
+    sql: str,
+    format: str,
+    output_path: str | None = None,
+) -> dict:
+    """Export DuckDB SQL results to a file.
+
+    Args:
+        sql: DuckDB SQL query. Reference files via read_parquet(), read_csv_auto(), etc.
+        format: Output format — "parquet", "csv", or "geojson".
+        output_path: Optional absolute path for the output file.
+                     If None, auto-generates in a temp directory.
+
+    Returns:
+        On success: {"path": str, "format": str, "row_count": int}
+        On error: {"error": str}
+    """
+    if format not in SUPPORTED_FORMATS:
+        return classify_error(
+            ValueError(f"Unsupported format: {format!r}. Use one of: {', '.join(SUPPORTED_FORMATS)}.")
+        )
+
+    # Auto-create views for any read_parquet() references
+    try:
+        _session.ensure_views(sql)
+    except ValueError as e:
+        return classify_error(e)
+
+    result_table = f"__export_{uuid4().hex[:8]}"
+    cursor = _session.conn.cursor()
+    try:
+        # Materialize user SQL exactly once
+        cursor.execute(f"CREATE TEMP TABLE {result_table} AS ({sql})")
+        try:
+            row_count = cursor.execute(f"SELECT count(*) FROM {result_table}").fetchone()[0]
+
+            # Resolve output path
+            dest = _resolve_output_path(output_path, format)
+            dest.parent.mkdir(parents=True, exist_ok=True)
+
+            if format == "geojson":
+                _export_geojson(cursor, result_table, dest, row_count)
+            else:
+                _copy_with_geometry_fallback(cursor, result_table, dest, format)
+
+            return {
+                "path": str(dest.resolve()),
+                "format": format,
+                "row_count": row_count,
+            }
+        finally:
+            cursor.execute(f"DROP TABLE IF EXISTS {result_table}")
+
+    except Exception as e:
+        return classify_error(e)
+    finally:
+        cursor.close()
+
+
+def _resolve_output_path(output_path: str | None, format: str) -> Path:
+    """Resolve the output file path, auto-generating if needed."""
+    if output_path is not None:
+        return Path(output_path)
+
+    output_dir = Path(tempfile.gettempdir()) / "mapular-geo-mcp"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
+    ext = format if format != "geojson" else "geojson"
+    return output_dir / f"export_{timestamp}.{ext}"
+
+
+def _export_geojson(
+    conn,
+    table_name: str,
+    dest: Path,
+    row_count: int,
+) -> None:
+    """Export to GeoJSON using DuckDB's GDAL driver.
+
+    For zero-row results, writes a minimal empty FeatureCollection.
+    """
+    if row_count == 0:
+        dest.write_text('{"type":"FeatureCollection","features":[]}')
+        return
+
+    conn.execute(
+        f"COPY (SELECT * FROM {table_name}) TO '{dest}' WITH (FORMAT GDAL, DRIVER 'GeoJSON')"
+    )

mapular_geo_mcp-0.1.0/src/mapular_geo_mcp/geocode.py

@@ -0,0 +1,125 @@
+"""Geocode addresses to lat/lon coordinates.
+
+Uses Nominatim (OpenStreetMap) by default. Optionally supports Mapbox
+when MAPBOX_ACCESS_TOKEN is set.
+
+Nominatim usage policy: identifiable User-Agent, max 1 req/s.
+"""
+
+import json
+import os
+import time
+from urllib.error import URLError
+from urllib.parse import quote_plus
+from urllib.request import Request, urlopen
+
+USER_AGENT = "mapular-geo-mcp/0.1.0 (https://github.com/mapular/mapular-geo-mcp)"
+
+# Simple rate limiter: track last request time
+_last_nominatim_request: float = 0.0
+
+
+def _importance_to_confidence(importance: float) -> str:
+    """Map Nominatim importance score to confidence level."""
+    if importance >= 0.7:
+        return "high"
+    elif importance >= 0.4:
+        return "medium"
+    return "low"
+
+
+def _geocode_nominatim(address: str) -> dict:
+    """Geocode via Nominatim (OpenStreetMap)."""
+    global _last_nominatim_request
+
+    # Rate limit: max 1 req/s
+    now = time.monotonic()
+    elapsed = now - _last_nominatim_request
+    if _last_nominatim_request > 0 and elapsed < 1.0:
+        time.sleep(1.0 - elapsed)
+
+    url = (
+        f"https://nominatim.openstreetmap.org/search"
+        f"?q={quote_plus(address)}&format=json&limit=1"
+    )
+    req = Request(url)
+    req.add_header("User-Agent", USER_AGENT)
+
+    try:
+        resp = urlopen(req, timeout=10)
+        data = json.loads(resp.read())
+    except URLError:
+        return {"error": True, "message": "Geocoding service unreachable. Check network connection."}
+    finally:
+        _last_nominatim_request = time.monotonic()
+
+    if not data:
+        return {"error": True, "message": "No results for address. Try a more specific query."}
+
+    hit = data[0]
+    importance = float(hit.get("importance", 0))
+
+    return {
+        "lat": float(hit["lat"]),
+        "lon": float(hit["lon"]),
+        "display_name": hit.get("display_name", ""),
+        "confidence": _importance_to_confidence(importance),
+        "provider": "nominatim",
+    }
+
+
+def _geocode_mapbox(address: str) -> dict:
+    """Geocode via Mapbox Geocoding API."""
+    token = os.environ.get("MAPBOX_ACCESS_TOKEN")
+    if not token:
+        # Fall back to nominatim with warning
+        result = _geocode_nominatim(address)
+        result["warning"] = "MAPBOX_ACCESS_TOKEN not set. Using nominatim as fallback."
+        return result
+
+    url = (
+        f"https://api.mapbox.com/geocoding/v5/mapbox.places"
+        f"/{quote_plus(address)}.json?access_token={token}&limit=1"
+    )
+    req = Request(url)
+    req.add_header("User-Agent", USER_AGENT)
+
+    try:
+        resp = urlopen(req, timeout=10)
+        data = json.loads(resp.read())
+    except URLError:
+        return {"error": True, "message": "Geocoding service unreachable. Check network connection."}
+
+    features = data.get("features", [])
+    if not features:
+        return {"error": True, "message": "No results for address. Try a more specific query."}
+
+    feat = features[0]
+    lon, lat = feat["center"]
+    relevance = feat.get("relevance", 0)
+
+    return {
+        "lat": lat,
+        "lon": lon,
+        "display_name": feat.get("place_name", ""),
+        "confidence": _importance_to_confidence(relevance),
+        "provider": "mapbox",
+    }
+
+
+def geocode_address(address: str, provider: str = "nominatim") -> dict:
+    """Geocode a free-form address to lat/lon coordinates.
+
+    Args:
+        address: Free-form address string.
+        provider: "nominatim" (default) or "mapbox".
+
+    Returns:
+        On success: {"lat": float, "lon": float, "display_name": str,
+                     "confidence": "high"|"medium"|"low", "provider": str}
+        On no results: {"error": True, "message": str}
+        On network error: {"error": True, "message": str}
+    """
+    if provider == "mapbox":
+        return _geocode_mapbox(address)
+    return _geocode_nominatim(address)