geotap-mcp-server 1.0.0 → 1.2.0

package/README.md

@@ -1,5 +1,8 @@
 # GeoTap Developer
 
+[![npm version](https://img.shields.io/npm/v/geotap-mcp-server.svg)](https://www.npmjs.com/package/geotap-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 **One API for 28+ US federal environmental and infrastructure data sources.**
 
 GeoTap aggregates data from FEMA, USGS, EPA, NOAA, USDA, USFWS, DOT, Census, and more into a single REST API. This repository contains:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geotap-mcp-server",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "MCP server for GeoTap — access 28+ US federal environmental and infrastructure data sources from Claude, Cursor, and other AI tools",
   "type": "module",
   "main": "src/index.js",
@@ -49,6 +49,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/jcholly/geotap-mcp-server"
+    "url": "https://github.com/jcholly/geotap-developer"
   }
 }

package/src/index.js

@@ -9,34 +9,39 @@ import { toolSources } from './sources.js';
 
 const server = new McpServer({
   name: 'geotap',
-  version: '1.0.0',
+  version: '1.2.0',
   description: 'Access 28+ US federal environmental and infrastructure data sources. Query flood zones, wetlands, soils, rainfall, watersheds, water quality, endangered species, elevation, land use, and more for any location in the United States.',
   instructions: `You have access to GeoTap, which provides real-time data from 28+ US federal agencies (FEMA, USGS, NOAA, EPA, NRCS, USFWS, USACE, and more).
 
-HOW TO USE THESE TOOLS:
-- For any US location question, start with geocode_address if the user gives an address (not coordinates).
-- Most tools accept lat/lon (or lat/lng). Use WGS84 decimal degrees.
-- Combine multiple tools to build a complete picture. For example, to assess a site:
-  1. geocode_address → get coordinates
-  2. get_flood_zones → FEMA flood risk
-  3. get_wetlands → USFWS wetland boundaries
-  4. get_soils → NRCS soil type, drainage, hydric rating
-  5. get_rainfall_atlas14 → NOAA precipitation data
-  6. get_stations_near → nearby USGS/NOAA monitoring stations
-  7. get_water_quality_impairments → EPA impaired waterways
+START HERE — CORE TOOLS (use these for 90% of queries):
+1. query_address — Geocode + environmental lookup in ONE call. Always start here when user gives an address.
+2. identify_features_at_point — Same as above but when you already have lat/lng coordinates.
+3. get_rainfall_data — NOAA Atlas 14 precipitation data for any US location.
+4. get_environmental_summary — Quick feature counts for an area (no geometry, just numbers).
+5. geocode_address — Convert address to coordinates (only needed if query_address doesn't cover your use case).
+
+These 5 tools handle most questions. Use specialized tools only when these don't cover the request.
+
+RESPONSE SIZE MANAGEMENT:
+- query_address and identify_features_at_point always return <5KB (no geometry, just properties + interpretations).
+- For all other spatial tools, ALWAYS set geometry="none" unless the user specifically needs coordinates.
+- Always specify layers (e.g., layers="flood_zones,wetlands") instead of querying all 19 layers.
+- In urban areas, full-geometry responses can exceed 1MB. Geometry="none" reduces this to <10KB.
 
 COMMON WORKFLOWS:
-- "Is this a good place to build?" → flood zones + wetlands + soils + constraints
-- "What's the flood risk?" → flood zones + rainfall + nearby stream gauges
-- "Environmental due diligence" → flood zones + wetlands + contamination + critical habitat + water quality
+- "What flood zone is this address in?" → query_address (one call, done)
+- "Is this a good place to build?" → query_address → get_rainfall_data → get_environmental_summary
+- "Environmental due diligence" → query_address (covers flood, wetlands, soils, contamination, habitat)
+- "What's the 100-year rainfall?" → get_rainfall_data
 - "Hydrology analysis" → watershed delineate + curve numbers + rainfall + peak flow
-- "Export data" → query the layers you need, then use the export tool for GeoJSON/Shapefile/CSV/KML
+- "Export data" → query layers, then export tool for GeoJSON/Shapefile/CSV/KML
 
 IMPORTANT NOTES:
-- All data comes from authoritative federal sources. Always mention the source agency when presenting results.
-- This data is for informational purposes. Remind users to verify critical data before making engineering or regulatory decisions.
+- All data comes from authoritative federal sources. Always mention the source agency.
+- Responses include _interpretation fields with plain-English summaries — use these in your answers.
+- This data is for informational purposes. Remind users to verify critical data for engineering/regulatory decisions.
 - Coordinates must be within the United States (including territories).
-- Some tools (watershed delineation, hydrology) can take 10-60 seconds for complex areas.
+- Some tools (watershed delineation, hydrology) can take 10-60 seconds.
 - Layer names use underscores: flood_zones, wetlands, dem_elevation, building_footprints, etc.`
 });
 

package/src/sources.js

@@ -63,6 +63,8 @@ const MULTI_SOURCE = [
  */
 export const toolSources = {
   // ── Spatial Queries ──
+  query_address: MULTI_SOURCE,
+  identify_features_at_point: MULTI_SOURCE,
   get_environmental_data_for_area: MULTI_SOURCE,
   get_environmental_data_near_point: MULTI_SOURCE,
   get_environmental_summary: MULTI_SOURCE,

package/src/tools.js

@@ -17,27 +17,50 @@ export const tools = [
   // ═══════════════════════════════════════════════════════════════════
   // SPATIAL QUERIES — Query environmental data by geography
   // ═══════════════════════════════════════════════════════════════════
+  {
+    name: 'query_address',
+    description: `The recommended starting tool for most queries. Geocodes a US address AND queries environmental data at that location in a single call. Returns flood zones, wetlands, soils, critical habitat, contamination sites, and more — with plain-English interpretations (e.g., "High-risk flood zone. Flood insurance required."). No geometry in response — just properties and interpretations. Response is always small (<5KB). Use this FIRST when the user provides an address. Only use geocode_address separately if you need coordinates for other tools.`,
+    parameters: {
+      address: z.string().describe('US street address (e.g., "123 Main St, Houston TX")'),
+      layers: z.string().optional().describe('Comma-separated layer names. Defaults to: flood_zones, wetlands, soil_map_units, critical_habitat, protected_lands, brownfields, superfund, npdes_outfalls, sole_source_aquifers')
+    },
+    endpoint: '/query-address',
+    method: 'GET'
+  },
+  {
+    name: 'identify_features_at_point',
+    description: `Identify what environmental features exist at an exact lat/lng point. Returns ONLY properties (no geometry) with plain-English interpretations. Response is always small (<5KB). Use this when you already have coordinates. For addresses, use query_address instead (it geocodes + queries in one call). Returns flood zones, wetlands, soils, critical habitat, protected lands, brownfields, Superfund, NPDES outfalls, and sole source aquifers by default.`,
+    parameters: {
+      lat: z.number().describe('Latitude (WGS84)'),
+      lng: z.number().describe('Longitude (WGS84)'),
+      layers: z.string().optional().describe('Comma-separated layer names (e.g., "flood_zones,wetlands,soil_map_units"). Defaults to key regulatory layers.')
+    },
+    endpoint: '/spatial/point',
+    method: 'GET'
+  },
   {
     name: 'get_environmental_data_for_area',
-    description: `Query all available US federal environmental and infrastructure data within a geographic area (polygon). Returns features from 28+ data sources including FEMA flood zones, NWI wetlands, USDA soils, USGS geology, EPA sites (Superfund, brownfields, TRI), USFWS critical habitat, DOT bridges, power plants, dams, mines, and more. Use this tool when someone asks about environmental conditions, site constraints, development feasibility, or regulatory concerns for a specific area. Accepts a GeoJSON polygon (e.g., a property boundary, project site, or any area of interest). This is the most comprehensive tool — it returns everything available for the given area.`,
+    description: `Query all available US federal environmental and infrastructure data within a geographic area (polygon). Returns features from 28+ data sources. WARNING: responses can be very large (100KB-2MB+) in urban areas with full geometry. ALWAYS set geometry="none" unless the user specifically needs coordinates. Specify layers to reduce response size. For simple "what's at this location?" questions, use query_address or identify_features_at_point instead — they're faster and return <5KB.`,
     parameters: {
       polygon: z.object({
         type: z.literal('Polygon'),
         coordinates: z.array(z.array(z.array(z.number())))
       }).describe('GeoJSON Polygon geometry defining the area of interest'),
-      layers: z.array(z.string()).optional().describe('Optional array of specific layer names to query. If omitted, all layers are queried.')
+      layers: z.array(z.string()).optional().describe('Optional array of specific layer names to query. If omitted, all layers are queried.'),
+      geometry: z.enum(['none', 'simplified', 'full']).optional().describe('Geometry detail: "none" strips coordinates (smallest response), "simplified" reduces density, "full" returns complete geometry. Default: full. Use "none" when you only need properties.')
     },
     endpoint: '/spatial/in-polygon',
     method: 'POST'
   },
   {
     name: 'get_environmental_data_near_point',
-    description: `Query all available US federal environmental and infrastructure data near a specific point (latitude/longitude). Returns features within a given radius from 28+ data sources including FEMA flood zones, NWI wetlands, USDA soils, USGS geology, EPA sites, endangered species habitat, bridges, dams, and more. Use this tool when someone asks "what's near this location?" or provides an address/coordinates and wants to know about environmental conditions in the vicinity. Great for quick site screening.`,
+    description: `Query environmental data near a lat/lng point within a radius. WARNING: responses can be very large (50KB-1MB+) with default settings. ALWAYS set geometry="none" and specify layers to keep responses manageable. For "what's AT this exact location?" use identify_features_at_point or query_address instead — they return <5KB. Only use this tool when the user specifically needs data within a radius (e.g., "what EPA sites are within 2 miles?").`,
     parameters: {
       lat: z.number().describe('Latitude of the center point (WGS84)'),
       lng: z.number().describe('Longitude of the center point (WGS84)'),
-      radius: z.number().optional().describe('Search radius in kilometers (default: 1)'),
-      layers: z.string().optional().describe('Comma-separated layer names to query. If omitted, all layers are queried.')
+      radius: z.number().optional().describe('Search radius in kilometers (min: 0.01, default: 1)'),
+      layers: z.string().optional().describe('Comma-separated layer names to query. If omitted, all layers are queried.'),
+      geometry: z.enum(['none', 'simplified', 'full']).optional().describe('Geometry detail: "none" strips coordinates (smallest response), "simplified" reduces density, "full" returns complete geometry. Default: full. Use "none" when you only need properties.')
     },
     endpoint: '/spatial/near',
     method: 'GET'
@@ -57,10 +80,11 @@ export const tools = [
   },
   {
     name: 'get_environmental_data_in_bbox',
-    description: `Query environmental data within a bounding box. Simpler than polygon query — just provide west, south, east, north coordinates. Returns features from specified layers. Good for quick rectangular area searches when you don't have an exact polygon boundary.`,
+    description: `Query environmental data within a bounding box. WARNING: responses can be very large with full geometry. Set geometry="none" and specify layers to keep responses small. For point lookups, use identify_features_at_point instead.`,
     parameters: {
       bbox: z.string().describe('Bounding box as "west,south,east,north" in WGS84 coordinates'),
-      layers: z.string().optional().describe('Comma-separated layer names to query')
+      layers: z.string().optional().describe('Comma-separated layer names to query'),
+      geometry: z.enum(['none', 'simplified', 'full']).optional().describe('Geometry detail: "none" strips coordinates (smallest response), "simplified" reduces density, "full" returns complete geometry. Default: full.')
     },
     endpoint: '/spatial/bbox',
     method: 'GET'
@@ -90,7 +114,8 @@ export const tools = [
     description: `Get features from a specific data layer within a bounding box. Use this tool when you need data from one specific source (e.g., just flood zones, or just wetlands) rather than all sources at once.`,
     parameters: {
       layerName: z.string().describe('The layer identifier (e.g., "flood_zones", "wetlands", "dem_elevation", "nlcd_land_cover", "contours", "building_footprints", "stream_gauges", "tide_stations", "weather_alerts", "air_quality")'),
-      bbox: z.string().describe('Bounding box as "west,south,east,north" in WGS84 coordinates')
+      bbox: z.string().describe('Bounding box as "west,south,east,north" in WGS84 coordinates'),
+      geometry: z.enum(['none', 'simplified', 'full']).optional().describe('Geometry detail: "none" strips coordinates (smallest response), "simplified" reduces density, "full" returns complete geometry. Default: full.')
     },
     endpoint: '/layers/{layerName}/features',
     method: 'GET'