overture_maps 0.1.0

data/lib/overture_maps/mcp_server.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "overture_maps"
+
+begin
+  require "mcp"
+  require "mcp/server/transports/stdio_transport"
+rescue LoadError
+  abort "The MCP server needs the official mcp gem: gem install mcp"
+end
+
+require "json"
+
+module OvertureMaps
+  # A read-only MCP (Model Context Protocol) server over Overture's public
+  # GeoParquet — no Rails app, no database. Queries stream through DuckDB
+  # with bbox pushdown, so nothing is bulk-downloaded.
+  #
+  #   overture-maps-mcp    # speaks MCP over stdio
+  #
+  # Claude Desktop config:
+  #   { "mcpServers": { "overture-maps": { "command": "overture-maps-mcp" } } }
+  module MCPServer
+    MAX_FEATURES = 100
+
+    module Helpers
+      module_function
+
+      def text_response(payload)
+        MCP::Tool::Response.new([{ type: "text", text: JSON.pretty_generate(payload) }])
+      end
+
+      def error_response(message)
+        MCP::Tool::Response.new([{ type: "text", text: JSON.generate(error: message) }], error: true)
+      end
+
+      # Accepts either a named-corner bbox or a location name.
+      def resolve_bbox(args)
+        if args[:west] && args[:south] && args[:east] && args[:north]
+          BoundingBox.new(lat1: args[:south], lng1: args[:west],
+                          lat2: args[:north], lng2: args[:east])
+        elsif args[:location]
+          results = DivisionSearch.search(query: args[:location])
+          raise Error, "no divisions found matching #{args[:location].inspect}" if results.empty?
+
+          results.first[:bbox]
+        else
+          raise ArgumentError, "provide west/south/east/north or a location name"
+        end
+      end
+
+      def bbox_properties
+        {
+          location: { type: "string", description: "Place name to geocode (e.g. 'Seattle'); alternative to the bbox corners" },
+          west: { type: "number" }, south: { type: "number" },
+          east: { type: "number" }, north: { type: "number" }
+        }
+      end
+    end
+
+    class GeocodeTool < MCP::Tool
+      tool_name "geocode"
+      description "Find geographic divisions (countries, regions, cities, neighborhoods) by name. " \
+                  "Returns each match with its bounding box [west, south, east, north]."
+      input_schema(
+        properties: { query: { type: "string", description: "Division name, e.g. 'Seattle'" } },
+        required: ["query"]
+      )
+
+      def self.call(query:, server_context: nil)
+        results = DivisionSearch.search(query: query).map do |r|
+          {
+            name: r[:name], subtype: r[:subtype], country: r[:country], region: r[:region],
+            area_km2: r[:area_km2],
+            bbox: [r[:bbox].min_lng, r[:bbox].min_lat, r[:bbox].max_lng, r[:bbox].max_lat]
+          }
+        end
+        Helpers.text_response(results)
+      rescue OvertureMaps::Error, ArgumentError => e
+        Helpers.error_response(e.message)
+      end
+    end
+
+    class QueryFeaturesTool < MCP::Tool
+      tool_name "query_features"
+      description "Fetch Overture Maps features (places, buildings, addresses, roads, ...) in an " \
+                  "area as GeoJSON features. Themes: places, buildings, addresses, divisions, " \
+                  "transportation (type segment/connector), base (type water/land/land_use/...). " \
+                  "Limit is capped at #{MAX_FEATURES}."
+      input_schema(
+        properties: Helpers.bbox_properties.merge(
+          theme: { type: "string", description: "Overture theme, e.g. 'places'" },
+          type: { type: "string", description: "Feature type for multi-type themes, e.g. 'segment'" },
+          category: { type: "string", description: "Places only: comma-separated leaf categories, e.g. 'cafe,coffee_shop'" },
+          limit: { type: "integer", description: "Max features (default 20, cap #{MAX_FEATURES})" }
+        ),
+        required: ["theme"]
+      )
+
+      def self.call(theme:, type: nil, category: nil, limit: nil, server_context: nil, **bbox_args)
+        bbox = Helpers.resolve_bbox(bbox_args)
+        limit = [(limit || 20).to_i.clamp(1, MAX_FEATURES), MAX_FEATURES].min
+        wanted = category&.split(",")&.map(&:strip)
+
+        features = []
+        Query.new(theme: theme, type: type, bbox: bbox, limit: limit * 5).each do |record|
+          if wanted
+            cats = record["categories"]
+            primary = cats.is_a?(Hash) ? cats["primary"] : record["basic_category"]
+            next unless wanted.include?(primary) ||
+                        (cats.is_a?(Hash) && (Array(cats["alternate"]) & wanted).any?)
+          end
+
+          geometry = record.delete("geometry")
+          properties = record.except("bbox", "names", "sources")
+          properties["name"] = record.dig("names", "primary")
+          features << {
+            type: "Feature",
+            geometry: geometry && RGeo::GeoJSON.encode(geometry),
+            properties: properties
+          }
+          break if features.length >= limit
+        end
+
+        Helpers.text_response({ type: "FeatureCollection", features: features })
+      rescue OvertureMaps::Error, ArgumentError => e
+        Helpers.error_response(e.message)
+      end
+    end
+
+    class CountFeaturesTool < MCP::Tool
+      tool_name "count_features"
+      description "Count Overture Maps features of a theme in an area without downloading them."
+      input_schema(
+        properties: Helpers.bbox_properties.merge(
+          theme: { type: "string" },
+          type: { type: "string" }
+        ),
+        required: ["theme"]
+      )
+
+      def self.call(theme:, type: nil, server_context: nil, **bbox_args)
+        bbox = Helpers.resolve_bbox(bbox_args)
+        count = Query.new(theme: theme, type: type, bbox: bbox).count
+        Helpers.text_response({ theme: theme, type: type, bbox: bbox.to_s, count: count })
+      rescue OvertureMaps::Error, ArgumentError => e
+        Helpers.error_response(e.message)
+      end
+    end
+
+    class ExportGeojsonTool < MCP::Tool
+      tool_name "export_geojson"
+      description "Export Overture Maps features for an area to a local file. Format comes from " \
+                  "the extension: .geojson, .geojsonseq, .gpkg, or .parquet."
+      input_schema(
+        properties: Helpers.bbox_properties.merge(
+          theme: { type: "string" },
+          type: { type: "string" },
+          path: { type: "string", description: "Output file path" },
+          limit: { type: "integer" }
+        ),
+        required: %w[theme path]
+      )
+
+      def self.call(theme:, path:, type: nil, limit: nil, server_context: nil, **bbox_args)
+        bbox = Helpers.resolve_bbox(bbox_args)
+        query = Query.new(theme: theme, type: type, bbox: bbox)
+        query = query.limit(limit) if limit
+        output = query.export(File.expand_path(path))
+        Helpers.text_response({ exported: output, bytes: File.size(output) })
+      rescue OvertureMaps::Error, ArgumentError => e
+        Helpers.error_response(e.message)
+      end
+    end
+
+    class GersLookupTool < MCP::Tool
+      tool_name "gers_lookup"
+      description "Look up a GERS id (Overture's stable entity id) in the official registry: " \
+                  "when it first appeared, when it last changed, and where it lives."
+      input_schema(
+        properties: { id: { type: "string", description: "GERS id (dashed UUID)" } },
+        required: ["id"]
+      )
+
+      def self.call(id:, server_context: nil)
+        row = GERS.lookup(id)
+        Helpers.text_response(row || { error: "not found in the registry" })
+      rescue OvertureMaps::Error, ArgumentError => e
+        Helpers.error_response(e.message)
+      end
+    end
+
+    class ListReleasesTool < MCP::Tool
+      tool_name "list_releases"
+      description "List available Overture Maps data releases, newest first."
+      input_schema(properties: {}, required: [])
+
+      def self.call(server_context: nil)
+        Helpers.text_response({ releases: Releases.all, latest: Releases.latest })
+      rescue OvertureMaps::Error => e
+        Helpers.error_response(e.message)
+      end
+    end
+
+    TOOLS = [
+      GeocodeTool, QueryFeaturesTool, CountFeaturesTool,
+      ExportGeojsonTool, GersLookupTool, ListReleasesTool
+    ].freeze
+
+    def self.start
+      server = MCP::Server.new(
+        name: "overture-maps",
+        version: OvertureMaps::VERSION,
+        instructions: "Query Overture Maps open geospatial data: geocode place names, fetch and " \
+                      "count features (places, buildings, roads, ...), export GeoJSON, and look " \
+                      "up GERS ids. Read-only; data streams from Overture's public bucket.",
+        tools: TOOLS
+      )
+      MCP::Server::Transports::StdioTransport.new(server).open
+    end
+  end
+end

data/lib/overture_maps/models/address.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  module Models
+    class Address < Base
+      self.table_name = "overture_addresses"
+
+      scope :by_country, ->(country) {
+        where(country: country)
+      }
+
+      scope :by_locality, ->(locality) {
+        where(locality: locality)
+      }
+
+      scope :by_region, ->(region) {
+        where(region: region)
+      }
+
+      scope :by_postcode, ->(postcode) {
+        where(postcode: postcode)
+      }
+
+      def full_address
+        [
+          [number, street].compact.join(" "),
+          unit, locality, region, postcode, country
+        ].compact.reject(&:empty?).join(", ")
+      end
+    end
+  end
+end

data/lib/overture_maps/models/base.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rgeo"
+require "rgeo/geo_json"
+
+module OvertureMaps
+  module Models
+    class Base < ::ActiveRecord::Base
+      self.abstract_class = true
+
+      # Everything whose geometry intersects the bounding box. Works for any
+      # geometry type (points, building polygons, segments).
+      scope :within_bounds, ->(south, west, north, east) {
+        where(
+          "ST_Intersects(geometry, ST_MakeEnvelope(?, ?, ?, ?, 4326)::geography)",
+          west, south, east, north
+        )
+      }
+
+      # Within radius_meters of a point.
+      scope :near, ->(lat, lng, radius_meters = 1000) {
+        where(
+          "ST_DWithin(geometry, ST_SetSRID(ST_MakePoint(?, ?), 4326)::geography, ?)",
+          lng, lat, radius_meters
+        )
+      }
+
+      def to_geojson
+        return nil unless geometry
+
+        {
+          type: "Feature",
+          geometry: RGeo::GeoJSON.encode(geometry),
+          properties: attributes.except("geometry", "created_at", "updated_at")
+        }
+      end
+    end
+  end
+end

data/lib/overture_maps/models/base_feature.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  module Models
+    # All six base-theme feature types (bathymetry, infrastructure, land,
+    # land_cover, land_use, water) in one table, discriminated by
+    # feature_type.
+    class BaseFeature < Base
+      self.table_name = "overture_base_features"
+
+      scope :by_feature_type, ->(feature_type) {
+        where(feature_type: feature_type)
+      }
+
+      scope :by_subtype, ->(subtype) {
+        where(subtype: subtype)
+      }
+
+      scope :by_class, ->(feature_class) {
+        where(feature_class: feature_class)
+      }
+
+      scope :water, -> { by_feature_type("water") }
+      scope :land, -> { by_feature_type("land") }
+      scope :land_use, -> { by_feature_type("land_use") }
+      scope :land_cover, -> { by_feature_type("land_cover") }
+      scope :infrastructure, -> { by_feature_type("infrastructure") }
+      scope :bathymetry, -> { by_feature_type("bathymetry") }
+    end
+  end
+end

data/lib/overture_maps/models/building.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  module Models
+    class Building < Base
+      self.table_name = "overture_buildings"
+
+      scope :by_height, ->(min: nil, max: nil) {
+        query = all
+        query = query.where("height >= ?", min) if min
+        query = query.where("height <= ?", max) if max
+        query
+      }
+
+      scope :by_floors, ->(min: nil, max: nil) {
+        query = all
+        query = query.where("num_floors >= ?", min) if min
+        query = query.where("num_floors <= ?", max) if max
+        query
+      }
+
+      scope :by_class, ->(building_class) {
+        where(building_class: building_class)
+      }
+
+      scope :with_height, -> {
+        where("height IS NOT NULL AND height > 0")
+      }
+
+      scope :underground, -> {
+        where(is_underground: true)
+      }
+    end
+  end
+end

data/lib/overture_maps/models/category.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  module Models
+    # Overture places category taxonomy (no geometry — plain lookup table).
+    class Category < ::ActiveRecord::Base
+      self.table_name = "overture_categories"
+
+      validates :name, presence: true, uniqueness: true
+
+      scope :by_primary, ->(primary) {
+        where(primary_category: primary)
+      }
+
+      def self.primary_categories
+        distinct.where.not(primary_category: nil).pluck(:primary_category).sort
+      end
+
+      # Expands taxonomy groups to the leaf categories beneath them, at any
+      # depth ("eat_and_drink" or "restaurant" → every *_restaurant leaf).
+      # Names that aren't groups pass through unchanged, so mixed input like
+      # ["eat_and_drink", "museum"] works.
+      def self.expand(names)
+        names = Array(names).map(&:to_s)
+        leaves = names.flat_map do |group|
+          where("taxonomy @> ?", [group].to_json).pluck(:name)
+        end
+        (names + leaves).uniq
+      end
+    end
+  end
+end

data/lib/overture_maps/models/connector.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  module Models
+    # Transportation connectors: points where segments physically meet,
+    # usable as routing nodes.
+    class Connector < Base
+      self.table_name = "overture_connectors"
+    end
+  end
+end

data/lib/overture_maps/models/division.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  module Models
+    # Imported division areas (theme=divisions/type=division_area): the
+    # geocodable territories of countries, regions, counties, localities, etc.
+    # Once populated, location searches resolve locally instead of querying
+    # Overture's bucket.
+    class Division < Base
+      self.table_name = "overture_divisions"
+
+      scope :by_subtype, ->(subtype) {
+        where(subtype: subtype)
+      }
+
+      scope :by_country, ->(country) {
+        where(country: country)
+      }
+
+      scope :countries, -> {
+        where(subtype: "country")
+      }
+
+      scope :search_by_name, ->(query) {
+        where("name ILIKE ?", "%#{sanitize_sql_like(query)}%")
+      }
+
+      scope :largest_first, -> {
+        order(Arel.sql("(bbox_xmax - bbox_xmin) * (bbox_ymax - bbox_ymin) DESC"))
+      }
+
+      def to_bounding_box
+        return nil unless bbox_xmin && bbox_xmax && bbox_ymin && bbox_ymax
+
+        BoundingBox.new(
+          lat1: bbox_ymin, lng1: bbox_xmin,
+          lat2: bbox_ymax, lng2: bbox_xmax,
+          display_name: name
+        )
+      end
+    end
+  end
+end

data/lib/overture_maps/models/imported_area.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  module Models
+    # Bookkeeping for every area/type combination that has been imported:
+    # which release the rows came from and the bbox they cover. This is what
+    # overture_maps:sync iterates to bring tables up to a newer release.
+    class ImportedArea < ::ActiveRecord::Base
+      self.table_name = "overture_imported_areas"
+
+      validates :theme, :feature_type, :model_class_name, :slug, :release, presence: true
+
+      scope :for_release, ->(release) { where(release: release) }
+      scope :behind, ->(release) { where.not(release: release) }
+
+      def to_bounding_box
+        BoundingBox.new(
+          lat1: bbox_ymin, lng1: bbox_xmin,
+          lat2: bbox_ymax, lng2: bbox_xmax,
+          display_name: slug
+        )
+      end
+
+      def model_class
+        model_class_name.constantize
+      end
+
+      # Upserts the bookkeeping row after an import.
+      def self.record!(theme:, feature_type:, model_class:, bbox:, release:, records_count:)
+        area = find_or_initialize_by(theme: theme, feature_type: feature_type, slug: bbox.slug)
+        area.update!(
+          model_class_name: model_class.name,
+          bbox_xmin: bbox.min_lng, bbox_xmax: bbox.max_lng,
+          bbox_ymin: bbox.min_lat, bbox_ymax: bbox.max_lat,
+          release: release,
+          records_count: records_count
+        )
+        area
+      end
+    end
+  end
+end

data/lib/overture_maps/models/place.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  module Models
+    class Place < Base
+      self.table_name = "overture_places"
+
+      # Matches the primary category or any alternate. Takes leaf category
+      # names from the Overture taxonomy (e.g. "cafe", "restaurant").
+      scope :by_category, ->(categories) {
+        cats = Array(categories).map(&:to_s)
+        where(
+          "primary_category = ANY (ARRAY[:cats]::text[]) OR categories->'alternate' ?| ARRAY[:cats]::text[]",
+          cats: cats
+        )
+      }
+
+      scope :by_country, ->(country) {
+        where(country: country)
+      }
+
+      # Matches the brand's primary name, e.g. by_brand("Starbucks").
+      scope :by_brand, ->(brands) {
+        where(
+          "brands->'names'->>'primary' = ANY (ARRAY[:brands]::text[])",
+          brands: Array(brands).map(&:to_s)
+        )
+      }
+
+      scope :by_operating_status, ->(status) {
+        where(operating_status: status)
+      }
+
+      scope :min_confidence, ->(confidence) {
+        where("confidence >= ?", confidence)
+      }
+
+      def brand_name
+        brands&.dig("names", "primary")
+      end
+    end
+  end
+end

data/lib/overture_maps/models/segment.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module OvertureMaps
+  module Models
+    # Transportation segments: center-lines of roads, rails, and waterways.
+    class Segment < Base
+      self.table_name = "overture_segments"
+
+      scope :by_subtype, ->(subtype) {
+        where(subtype: subtype)
+      }
+
+      scope :by_class, ->(segment_class) {
+        where(segment_class: segment_class)
+      }
+
+      scope :roads, -> { where(subtype: "road") }
+      scope :rails, -> { where(subtype: "rail") }
+      scope :waterways, -> { where(subtype: "water") }
+    end
+  end
+end

data/lib/overture_maps/models.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# This gem is an ActiveRecord integration at heart, so the model layer loads
+# eagerly. (Deferring via on_load(:active_record) breaks rake tasks: Zeitwerk
+# can autoload an app's OverturePlace subclass before anything has touched
+# ActiveRecord::Base, at which point the gem superclass wouldn't exist yet.)
+require "active_record"
+require "rgeo/active_record"
+require "activerecord-postgis-adapter"
+
+module OvertureMaps
+  module Models
+  end
+end
+
+require "overture_maps/models/base"
+require "overture_maps/models/place"
+require "overture_maps/models/building"
+require "overture_maps/models/address"
+require "overture_maps/models/category"
+require "overture_maps/models/division"
+require "overture_maps/models/segment"
+require "overture_maps/models/connector"
+require "overture_maps/models/base_feature"
+require "overture_maps/models/imported_area"