geotap-mcp-server 3.0.0 → 3.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GeoTap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geotap-mcp-server",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "MCP server for GeoTap — collect comprehensive environmental data from 80+ US federal sources for any site. One tool, all the data.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -27,18 +27,59 @@ DATA INCLUDES:
 - Contamination: Superfund, brownfields, USTs, EPA-regulated facilities (RCRA, GHG, FRS)
 - Water: streams, watershed, water quality impairments (ATTAINS), NPDES outfalls, groundwater
 - Hazards: seismic design (ASCE 7-22), earthquakes, wildfires, landslides, coastal vulnerability, NRI
-- Rainfall: NOAA Atlas 14 precipitation frequency data
+- Rainfall: NOAA Atlas 14 precipitation frequency data (IDF curves, design storms)
+- Land cover: NLCD 2021 classification (developed, forest, wetlands, etc.)
+- Elevation: USGS 3DEP (min/max/mean elevation, relief)
 - Infrastructure: hospitals, fire stations, schools, EMS, dams, levees, power plants, airports, railroads, bridges
 - Ecology: species (GBIF), fish habitat, critical habitat, cropland, national forests, BLM lands, historic places
 - Energy: solar potential, utility rates, EV charging stations
-- Demographics: Census ACS (population, income, housing, poverty)
+- Demographics: Census ACS (population, income, housing, poverty, vacancy rates)
 - Protected lands (PAD-US), wild & scenic rivers, sole source aquifers
 
+HOW TO PRESENT RESULTS:
+The goal is a scannable engineering document, not a data dump. An engineer doing site due diligence needs to answer three questions fast:
+1. What kills the project? (floodway, contamination, protected species)
+2. What complicates permitting? (wetlands, impaired waters, high slopes, poor soils)
+3. What's the baseline context? (rainfall IDF, seismic params, demographics, infrastructure)
+
+CRITICAL FLAGS — scan results and lead with these if present:
+- Any FEMA zone AE/AO/VE (SFHA): "Site intersects SFHA — Zone [X]" (CRITICAL)
+- Any floodway: "Regulatory floodway — no-rise certification required" (CRITICAL)
+- Superfund site nearby: "NPL Superfund site within search radius" (CRITICAL)
+- Wetland count > 10: "High wetland density — Section 404 permitting likely" (HIGH)
+- 303(d) impaired water (Category 5): "TMDL required, stricter discharge limits" (HIGH)
+- Brownfields > 3: "Phase I ESA recommended" (MODERATE)
+- Soils with HSG D: "Poorly draining soils — stormwater design impact" (MODERATE)
+
+SECTION ORDER (skip sections with no data):
+1. Site overview — address, coordinates, county, elevation (min/max/mean), land cover, area
+2. FEMA flood zones — table with zone, subtype, SFHA status, risk level
+3. Soils — one block per soil unit: HSG, drainage class, slope, flood frequency, limitations
+4. Atlas 14 rainfall — IDF table (rows: 15min, 1hr, 6hr, 12hr, **24hr bold**, 3day; cols: 2yr, 5yr, 10yr, 25yr, 50yr, 100yr). Include Atlas 14 volume/version.
+5. Natural hazard risk — NRI ratings by hazard type (overall, flooding, tornado, earthquake, etc.)
+6. Wetlands — count, type breakdown, Section 404 permitting note
+7. Water resources — streams (with distances), impaired waters (category), watershed HUC
+8. Contamination — Superfund, brownfields (with distances/status), USTs, NPDES outfalls
+9. Seismic & dams — ASCE 7-22 params (SDS, SD1, SDC, PGA), nearby dams with hazard rating
+10. Infrastructure — hospitals, fire stations, schools, EMS counts with distances
+11. Solar & energy — DNI, GHI, capacity factor, utility rates
+12. Demographics — population, median income, vacancy rate (from Census ACS)
+
+FORMATTING RULES:
+- Use markdown tables for flood zones, rainfall IDF, brownfields, soils
+- Bold the 24-hr row in rainfall tables — it's the most referenced for stormwater design
+- For soils, always include HSG and drainage class — these drive CN calculations
+- Include distances and cardinal directions for nearby features (e.g., "0.8 mi NW")
+- When a source returned no data ("_noData"), mention it where relevant ("no Superfund sites" is positive)
+- Cite source agencies (FEMA, NRCS, NOAA Atlas 14, EPA), not just "GeoTap"
+- End with disclaimer: "Data sourced from US federal agencies via GeoTap. Verify critical findings against authoritative sources before making engineering or regulatory decisions."
+
 IMPORTANT:
-- All data from authoritative US federal sources. Always cite the source agency.
+- All data from authoritative US federal sources. Always cite the source agency, not just "GeoTap."
 - Data is for informational purposes. Remind users to verify for engineering/regulatory decisions.
 - Coordinates must be within the United States (including territories).
-- If a data source returns "_noData: true", it was queried but found nothing at that location.`
+- If a data source returns "_noData: true", it was queried but found nothing at that location — mention this where relevant (no contamination nearby is positive).
+- If a data source returns "_error", note that the source was unavailable and the user should check back.`
 });
 
 // ── Tool: collect_site_data ──────────────────────────────────────────
@@ -66,18 +107,21 @@ Data returned covers: flood zones, wetlands, soils, geology, contamination sites
       if (address && !siteGeometry) {
         // Geocode the address first
         const geocodeResult = await callApi('/geocode', 'GET', { address });
-        if (!geocodeResult?.lat || !geocodeResult?.lng) {
+        // API returns { success, results: [{ lat, lon, displayName, source }] }
+        const match = geocodeResult?.results?.[0];
+        if (!match?.lat || !match?.lon) {
           return {
             content: [{ type: 'text', text: JSON.stringify({
               error: true,
-              message: `Could not geocode address: "${address}". Try a more specific address or use lat/lng coordinates.`,
+              message: `Could not geocode address: "${address}". Try a more specific address with city/state, or use lat/lng coordinates directly.`,
+              suggestion: 'Example: { lat: 34.8779, lng: -82.3313 }',
             }, null, 2) }],
             isError: true
           };
         }
         siteGeometry = {
           type: 'Point',
-          coordinates: [geocodeResult.lng, geocodeResult.lat]
+          coordinates: [match.lon, match.lat]
         };
       } else if (lat != null && lng != null && !siteGeometry) {
         siteGeometry = {
@@ -133,7 +177,7 @@ Data returned covers: flood zones, wetlands, soils, geology, contamination sites
 
 server.tool(
   'get_results',
-  `Check the status of a data collection job and retrieve results. Poll every 10 seconds until status is "completed". When complete, returns the full data summary from all 80+ federal sources.`,
+  `Check the status of a data collection job and retrieve results. Poll every 10 seconds until status is "completed". When complete, returns the full data summary from all 80+ federal sources. Present the results to the user following the formatting instructions in the server description.`,
   {
     jobId: z.string().describe('Job ID returned from collect_site_data'),
   },
@@ -141,15 +185,45 @@ server.tool(
     try {
       const result = await callApi(`/site-analysis/data-collect/${encodeURIComponent(params.jobId)}`, 'GET', {});
 
+      const response = { ...result };
+
+      // Add presentation guidance when results are complete
+      if (result.status === 'completed') {
+        response._meta = {
+          sources: '80+ US federal agencies (FEMA, USGS, NOAA, EPA, NRCS, USFWS, USACE, DOE, DOT, CDC, Census, and more)',
+          retrievedAt: new Date().toISOString(),
+          disclaimer: 'Data sourced from US federal agencies via GeoTap. Always verify critical data against authoritative sources before making engineering or regulatory decisions.',
+        };
+        response._presentationGuide = {
+          instructions: 'Present as a scannable engineering document. Lead with critical flags, then structured sections. Follow the HOW TO PRESENT RESULTS instructions.',
+          priorityOrder: [
+            '1. Critical flags (floodway, SFHA, Superfund, high wetland density)',
+            '2. FEMA flood zones (table: zone, subtype, SFHA, risk)',
+            '3. Soils (HSG, drainage class, slope, limitations)',
+            '4. Atlas 14 rainfall (IDF table — bold 24hr row)',
+            '5. NRI hazard risk (badge grid by hazard type)',
+            '6. Wetlands (count, types, Section 404 note)',
+            '7. Water resources (streams, impaired waters with distances)',
+            '8. Contamination (Superfund, brownfields, USTs with distances)',
+            '9. Seismic & dams (ASCE 7-22 params, nearby dams)',
+            '10. Infrastructure (hospitals, fire, schools, EMS counts)',
+            '11. Solar/energy & demographics (collapsed/secondary)',
+          ],
+          tips: [
+            'Lead with what kills or complicates the project — not context',
+            'Use tables for flood zones, rainfall IDF, brownfields, soils',
+            'Bold the 24-hr rainfall row — most referenced for stormwater design',
+            'For soils, always show HSG and drainage class (drives CN calculation)',
+            'Cite source agencies (FEMA, NRCS, NOAA Atlas 14, EPA)',
+            '"No Superfund sites nearby" is positive — mention it',
+          ]
+        };
+      } else {
+        response._instructions = `Job status: ${result.status}. Poll again in 10 seconds until status is "completed".`;
+      }
+
       return {
-        content: [{ type: 'text', text: JSON.stringify({
-          ...result,
-          _meta: {
-            sources: '80+ US federal agencies (FEMA, USGS, NOAA, EPA, NRCS, USFWS, USACE, DOE, DOT, CDC, Census, and more)',
-            retrievedAt: new Date().toISOString(),
-            disclaimer: 'Data sourced from US federal agencies via GeoTap. Always verify critical data against authoritative sources before making engineering or regulatory decisions.',
-          }
-        }, null, 2) }]
+        content: [{ type: 'text', text: JSON.stringify(response, null, 2) }]
       };
     } catch (error) {
       if (error instanceof StructuredApiError) {