RockHound — Plataforma de inteligencia para la búsqueda de rocas en Colorado

Una plataforma de datos gobernada y con conciencia espacial que responde a una pregunta real: «¿Dónde puedo ir legalmente a buscar rocas en Colorado, y qué es probable que encuentre?» Construida de extremo a extremo a partir de datos gubernamentales federales y estatales en bruto a través de una arquitectura Medallion (capas de estilo Bronze/Silver) hasta un servidor MCP (Model Context Protocol) gobernado — lo que permite a un agente de IA responder preguntas sobre búsqueda de rocas fundamentadas en datos espaciales reales, seleccionados y fiables, en lugar de fuentes brutas o no verificadas.

Estructura del repositorio: scripts SQL en /sql, código Python en /python — consulta esas carpetas para ver la implementación real.

El objetivo

Combinar múltiples conjuntos de datos públicos independientes — estado de los reclamos mineros, propiedad de la tierra y registros históricos de ocurrencias de minerales — en una única plataforma consultable, y luego exponer esos datos a un sistema de IA a través de una interfaz gobernada que solo presenta consultas específicas, seguras y preaprobadas en lugar de acceso directo a la base de datos. Esto refleja el mismo patrón de «producto de datos gobernado y listo para IA» cada vez más solicitado en los roles modernos de ingeniería de datos.

Pregunta específica a la que responde: «Encuentra reclamos mineros vacantes/caducados cerca de ocurrencias documentadas de un mineral, y dime si realmente me está permitido estar allí.»

Related MCP server: arcgis-lacounty

Arquitectura

flowchart TD
    A["BLM Mining Claims<br/>(Active + Closed + Closed-Recent)"] --> D
    B["BLM Surface Management Agency<br/>(Land Ownership)"] --> D
    C["USGS MRDS<br/>(Mineral Occurrences)"] --> D

    D["BRONZE LAYER<br/>Raw ingestion, full provenance<br/>(source_url + source_type)"] --> E

    E["SILVER LAYER<br/>Cleansed, deduplicated<br/>Native geography types, MakeValid()<br/>Colorado-filtered"] --> F

    F["Spatial Indexes +<br/>CROSS APPLY Query Layer"] --> G

    G["MCP SERVER<br/>Streamable HTTP"] --> H["find_vacant_claims_near_mineral()"]
    G --> I["check_land_access()"]

    H --> J["MCP Inspector / AI Client"]
    I --> J

Fuentes de datos reales (todas públicas y gratuitas)

Todos los registros de las fuentes incluyen source_url y source_type (p. ej., «Government Agency») para un seguimiento completo del linaje y la procedencia de los datos — un patrón de gobernanza incorporado intencionadamente, no como una idea de último momento.

Pila tecnológica

• SQL Server — tipo de datos espaciales nativos geography, indexación espacial, STDistance/STIntersects/STContains, MakeValid()

• Python — geopandas, pandas, pyodbc, shapely

• MCP Python SDK (mcp.server) — transporte Streamable HTTP

• MCP Inspector — herramienta oficial para probar/verificar servidores MCP

• Cloudflare Tunnel — exposición HTTPS local para probar clientes MCP remotos

Herramientas y plataformas utilizadas

Un desglose detallado de qué se usó para cada cosa, ya que el entorno de desarrollo real forma parte de la historia real de este proyecto.

Fuentes de datos (de dónde provienen los datos brutos)

Desarrollo de base de datos y consultas

Desarrollo en Python

Herramientas específicas de MCP

Control de versiones y alojamiento

Dos herramientas gobernadas, deliberadamente delimitadas en lugar de exponer acceso SQL bruto a un sistema de IA:

find_vacant_claims_near_mineral(mineral_name, max_distance_miles) Encuentra reclamos mineros vacantes/caducados cerca de ocurrencias históricas documentadas de un mineral determinado, marcando qué reclamos cerraron más recientemente (oportunidades más frescas), en qué condado se encuentra cada uno y ordenándolos por proximidad.

check_land_access(latitude, longitude, mineral_search_radius_miles) Dada una coordenada, devuelve un informe completo del lugar: tipo de propiedad de la tierra, si algún reclamo minero cubre ese punto (y si es así, activo vs. vacante), el condado, la ciudad más cercana y su distancia, y cualquier mineral documentado dentro de un radio de búsqueda configurable.

Ambas herramientas consultan únicamente la capa Silver seleccionada mediante consultas fijas y parametrizadas — la IA nunca obtiene acceso arbitrario a la base de datos, solo estas respuestas específicas, seguras y creadas para un propósito concreto.

Retos de ingeniería reales resueltos

Esta sección existe porque el proceso de depuración es posiblemente la parte más representativa de todo el proyecto: la ingeniería de datos real no es un primer intento limpio. Consulta /sql/04_example_queries.sql para ver las consultas de diagnóstico reales utilizadas para encontrar y corregir estos problemas.

1. Geometría espacial no válida. Los datos reales de polígonos GIS gubernamentales incluían geometrías no válidas con autointersecciones que provocaban errores en tiempo de ejecución en el estricto tipo geography de SQL Server (24144: instance is not valid). Se corrigió aplicando .MakeValid() durante la transformación de Bronze a Silver; ver /sql/02_silver_schema_and_transform.sql.

2. Un error silencioso de mapeo de datos. La búsqueda de minerales usaba inicialmente mineral_name como campo de coincidencia (el nombre del sitio de una mina, p. ej., «Silver King Mine») en lugar de commodity_type (lo que realmente estaba documentado como encontrado allí), un error de exactitud que se detectó al comparar el número de filas: 11 coincidencias con el nombre del sitio para «Quartz» frente a 82 coincidencias reales con el tipo de mineral.

3. Un problema real de rendimiento/plan de consulta. Un patrón sencillo de JOIN ... ON STDistance(...) < X provocaba que las consultas tardaran silenciosamente más de 13 minutos para minerales comunes, porque el optimizador de SQL Server no usaba el índice espacial para esa forma de combinación; se confirmó mediante el análisis del plan de ejecución, que mostraba 124M+ operaciones de filas estimadas en una combinación de bucles anidados. Se corrigió reestructurando la consulta en torno a CROSS APPLY (el patrón documentado para activar de forma fiable el uso del índice espacial en búsquedas del vecino más cercano), reduciendo la misma consulta a ~36 segundos. Ver /sql/04_example_queries.sql.

4. Filtrado de datos de ámbito nacional. Varios conjuntos de datos «Colorado» de fuentes federales eran en realidad de ámbito nacional (un archivo de reclamaciones activas tenía 579.730 filas antes de filtrarse a las 14.699 de Colorado). Se filtraron mediante intersección con un cuadro delimitador durante la ingesta, en lugar de cargarlos y descartarlos en una fase posterior; ver COLORADO_BBOX_WKT en /python/load_bronze.py.

5. Integración con el cliente MCP. Se descubrió que el flujo del conector remoto del cliente MCP de destino esperaba un registro de cliente OAuth incluso para servidores locales no autenticados. Se solucionó ejecutando el servidor sobre Streamable HTTP con un túnel rápido de Cloudflare para HTTPS, y se validó la funcionalidad mediante la herramienta oficial MCP Inspector, en lugar de atender los requisitos de autenticación específicos de una única aplicación consumidora.

6. Orientación invertida de los anillos de los polígonos, que afectaba a tres tablas distintas. Los polígonos procedentes de shapefiles y geodatabases de archivos (condados, ciudades y el gran conjunto de datos histórico de Claims) a veces se almacenaban con el orden de enrollado de los anillos invertido; el tipo geography de SQL Server los interpretaba como «en todas partes excepto X» en lugar de «X», algo que .MakeValid() no detecta ni corrige (solo repara las autointersecciones, no la orientación). Se diagnosticó comprobando si STArea() devolvía valores increíblemente grandes (un condado real de Colorado, correctamente orientado, nunca debería acercarse a ~510.000.000 km², la superficie total de la Tierra). Se corrigió con un .ReorientObject() condicional basado en un umbral de área. Un primer intento de esta corrección usó la unidad equivocada (STArea() devuelve metros cuadrados, no kilómetros cuadrados), lo que invirtió incorrectamente varios condados genuinamente grandes y correctamente orientados; el error se detectó y corrigió al revalidar contra los 64 condados reales de Colorado.

7. Una clase recurrente de errores de recuento de parámetros, y una corrección estructural. Repetir geography::Point(?, ?, 4326) en línea varias veces dentro de una sola consulta facilitaba contar mal la lista de parámetros necesaria, lo que provocó dos errores de tiempo de ejecución separados de «recuento de parámetros incorrecto». Se corrigió estructuralmente calculando el punto de coordenadas una sola vez mediante una variable SQL DECLARE @searchPoint GEOGRAPHY = ... y referenciándolo en toda la consulta, lo que redujo la mayoría de las consultas a solo 2 parámetros reales y eliminó esa clase de errores de cara al futuro, en lugar de corregir solo el caso inmediato.

8. Una carencia de diseño en la completitud de los datos, no un error. check_land_access devolvía originalmente una única reclamación arbitraria mediante TOP 1 sin ordenación explícita. Las pruebas con una reclamación real y conocida («Rocket Six», verificada con los datos reales de una reclamación minera de un amigo) revelaron que 14 reclamaciones distintas —6 activas, 8 vacantes— se superponen legítimamente en esa única coordenada, algo normal en un denso distrito minero histórico de Colorado. La solución no fue un parche de errores, sino una decisión de diseño deliberada: enumerar cada reclamación activa por nombre (ya que cualquiera de ellas significa «no excavar») y resumir las reclamaciones vacantes como un recuento, en lugar de elegir una silenciosamente y ocultar el resto.

9. Una investigación de rendimiento en varias etapas sobre una búsqueda de enriquecimiento por fila. Tras añadir una consulta de condado para enriquecer los resultados de la búsqueda de minerales, los minerales comunes (Quartz: ~24.570 coincidencias brutas) empezaron a agotar el tiempo de espera en la llamada a la herramienta MCP. La depuración descartó varias causas plausibles una tras otra: limitar con TOP (N) a nivel de SQL en realidad empeoró las cosas drásticamente (más de 4 minutos frente a ~6 segundos sin límite) debido a una regresión del optimizador de SQL Server cuando TOP se combina con ORDER BY en una columna calculada costosa; limitar en Python después de recuperar los datos tampoco ayudó, ya que el coste real se seguía pagando dentro de SQL Server antes de que se devolvieran los resultados; y reescribir la consulta de condado como subconsulta correlacionada, como JOIN y como OUTER APPLY fue igualmente lento en todos los casos (~4 minutos), lo que demostró que el cuello de botella era el gran número de consultas espaciales (una por coincidencia bruta), no la sintaxis de la consulta. La solución real fue una consulta en dos fases: primero, coincidencia rápida solo por distancia y limitación; después, una consulta espacial de condado únicamente sobre el pequeño conjunto de resultados final (<=50 filas), en lugar de hacerlo sobre cada coincidencia bruta. Este es un buen ejemplo de cómo la eliminación sistemática de hipótesis plausibles pero incorrectas constituye el verdadero trabajo de la depuración del rendimiento, y no una única solución ingeniosa encontrada de inmediato.

Salida de ejemplo

> find_vacant_claims_near_mineral(mineral_name="Quartz", max_distance_miles=20)

AVENGER #15, Park County - 0.7 mi from documented Quartz
GAMBLE NO 1, Park County - 2.9 mi from documented Quartz
SARAH K #45, Chaffee County - 4.6 mi from documented Quartz
...

> check_land_access(latitude=39.5, longitude=-105.7)

Land type: USFS, covered by claim '#1' (VACANT)
County: Park County
Nearest city: Fairplay (3.2 mi away)
Documented minerals within 2.0 mi: Gold, Quartz, Silver

Contenido del repositorio

RockHound/
├── README.md
├── sql/
│   ├── 01_bronze_schema.sql          -- Bronze table DDL
│   ├── 02_silver_schema_and_transform.sql  -- Silver DDL + MakeValid() + dedup logic
│   ├── 03_spatial_indexes.sql        -- Spatial index creation
│   ├── 04_example_queries.sql        -- Diagnostic + optimized query patterns
│   └── 05_cities_counties_schema_and_load.sql  -- County/city boundary layer
└── python/
    ├── load_bronze.py                -- Bronze ingestion (Colorado-filtered, fast bulk insert)
    └── rockhound_server.py           -- MCP server with governed tools

Hoja de ruta (Fase 2 / Fase 3, planificada pero aún no construida)

• Fase 2: Ríos/arroyos (potencial de depósitos de placer), manantiales termales (geología formadora de minerales), datos de lecho rocoso/formaciones geológicas (Macrostrat): mismo patrón espacial de Bronze a Silver, nuevas fuentes.

• Fase 3: Puntos de entrada a senderos/aparcamientos, datos de elevación y comparación del acceso por carretera específico del vehículo (distancia al suelo / requisitos de 4WD frente a un perfil de vehículo concreto).

Atribución de los datos

Datos proporcionados por el Bureau of Land Management (BLM) y el U.S. Geological Survey (USGS), utilizados de acuerdo con sus términos de datos públicos. Este es un proyecto personal y no está afiliado ni respaldado por BLM ni por USGS. Los datos se proporcionan «tal cual» y pueden contener errores u omisiones: verifique siempre de forma independiente el estado de la reclamación y el acceso al terreno antes de visitar cualquier sitio en persona.

Otros proyectos

• Data Engineering & Systems Architecture Portfolio — Una plataforma de arquitectura Medallion de nivel de producción construida sobre Microsoft Fabric, que incluye pipelines de PySpark/Delta Lake, agentes de IA de Copilot Studio, análisis de KQL Eventhouse y CI/CD completo mediante Azure DevOps.