GIS MCP Server

Instructions

Implementation Reference

• src/gis_mcp/geopandas_functions.py:183-222 (handler)

  The primary handler function implementing the 'overlay_gpd' MCP tool. It reads two geospatial files, performs a spatial overlay operation using geopandas.overlay with the specified method, optionally saves the result, and returns metadata and a preview.

  @gis_mcp.tool()
  def overlay_gpd(gdf1_path: str, gdf2_path: str, how: str = "intersection", output_path: str = None) -> Dict[str, Any]:
      """
      Overlay two GeoDataFrames using geopandas.overlay.
      Args:
          gdf1_path: Path to the first geospatial file.
          gdf2_path: Path to the second geospatial file.
          how: Overlay method ('intersection', 'union', 'identity', 'symmetric_difference', 'difference').
          output_path: Optional path to save the result.
      Returns:
          Dictionary with status, message, and output info.
      """
      try:
          gdf1 = gpd.read_file(gdf1_path)
          gdf2 = gpd.read_file(gdf2_path)
          if gdf1.crs != gdf2.crs:
              gdf2 = gdf2.to_crs(gdf1.crs)
          result = gpd.overlay(gdf1, gdf2, how=how)
          if output_path:
              output_path_resolved = resolve_path(output_path, relative_to_storage=True)
              output_path_resolved.parent.mkdir(parents=True, exist_ok=True)
              result.to_file(str(output_path_resolved))
              output_path = str(output_path_resolved)
          # Convert geometry to WKT for serialization
          preview_df = result.head(5).copy()
          if 'geometry' in preview_df.columns:
              preview_df['geometry'] = preview_df['geometry'].apply(lambda g: g.wkt if g is not None else None)
          preview = preview_df.to_dict(orient="records")
          return {
              "status": "success",
              "message": f"Overlay ({how}) completed successfully.",
              "num_features": len(result),
              "crs": str(result.crs),
              "columns": list(result.columns),
              "preview": preview,
              "output_path": output_path,
          }
      except Exception as e:
          logger.error(f"Error in overlay_gpd: {str(e)}")
          return {"status": "error", "message": str(e)}

• src/gis_mcp/geopandas_functions.py:13-26 (schema)

  MCP resource listing that documents 'overlay_gpd' as one of the available GeoPandas I/O operations, serving as a schema or directory for tool discovery.

  @gis_mcp.resource("gis://geopandas/io")
  def get_geopandas_io() -> Dict[str, List[str]]:
      """List available GeoPandas I/O operations."""
      return {
          "operations": [
              "read_file_gpd",
              "to_file_gpd",
              "overlay_gpd",
              "dissolve_gpd",
              "explode_gpd",
              "clip_vector",
              "write_file_gpd"
          ]
      }