gov-data-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle Maloney (malonestar)
+
+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/README.md

@@ -0,0 +1,108 @@
+# gov-data-mcp
+
+**95 US government open-data tools, as one MCP server.**
+
+EPA, FEMA, USGS, NOAA, FAA, USACE, FDIC, HUD, NRCS, HRSA, CMS, county assessor rolls and state licensing boards — all reachable as agent-callable tools, all reading directly from official government APIs and bulk files. No scraping, no HTML parsing, no rate-limit roulette.
+
+`mcp-name: io.github.malonestar/gov-data-mcp`
+
+```bash
+npx gov-data-mcp
+```
+
+## Install
+
+You need a free Apify API token from [console.apify.com/settings/integrations](https://console.apify.com/settings/integrations). Apify's free tier includes monthly platform credit that covers evaluating every tool here.
+
+### Claude Desktop / Claude Code / Cursor
+
+```json
+{
+  "mcpServers": {
+    "gov-data": {
+      "command": "npx",
+      "args": ["-y", "gov-data-mcp"],
+      "env": { "APIFY_TOKEN": "apify_api_..." }
+    }
+  }
+}
+```
+
+Claude Desktop reads `claude_desktop_config.json`; Claude Code reads `.mcp.json` in your project; Cursor reads `.cursor/mcp.json`. The block is identical in all three.
+
+## What you get
+
+**12 dedicated tools** for the highest-traffic questions, callable directly:
+
+| Tool | Answers |
+|---|---|
+| `site-due-diligence-bundle` | 20-layer go / caution / no-go verdict for one coordinate |
+| `epa-contaminated-site-screener` | Phase I ESA database search at ASTM E1527-21 distances |
+| `faa-drone-airspace-checker` | Part 107 LAANC and airspace verdicts, batched |
+| `hifld-grid-proximity-screener` | Nearest transmission line, substation, serving utility, ISO/RTO |
+| `interconnection-queue-tracker` | Generator interconnection queues across 7 ISOs |
+| `fdic-ncua-health-rollup` | Bank and credit-union health with real peer cohorts |
+| `fema-nri-county-risk-profile` | County and census-tract natural-hazard risk |
+| `fws-wetlands-proximity-screener` | NWI wetlands within a radius, with decode columns |
+| `nhd-surface-water-404-screener` | Clean Water Act §404 surface-water screen |
+| `epa-drinking-water-quality-screener` | SDWA violations, lead, PFAS occurrence |
+| `parcel-owner-lookup` | Assessor-roll owner of record for an address |
+| `license-verifier` | 19 professional licensing boards across 9 states + OIG exclusions |
+
+**Plus three tools that reach the other 83:**
+
+- `search_gov_data_tools` — find a tool by keyword, agency or topic
+- `describe_gov_data_tool` — full input schema for any tool in the catalog
+- `run_gov_data_tool` — run any tool in the catalog
+
+The catalog is bundled, so discovery costs nothing. Ask your agent *"what government data tools do you have for flood risk?"* and it will search all 95.
+
+## Example prompts
+
+> Screen 1200 Broadway, Denver CO for environmental risk under ASTM E1527-21 and tell me which findings fall inside the standard's search distance.
+
+> I'm siting a 40 MW solar project at 41.88, -93.10. Check grid proximity, prime farmland, wetlands, critical habitat and the interconnection queue, then tell me what would kill the project.
+
+> Can I fly a Part 107 mission at these six coordinates, and which ones need a DroneZone authorization rather than LAANC?
+
+> Which Texas banks show the 2006 CRE-concentration guidance flagged on both prongs?
+
+## How it works
+
+Each tool is a published [Apify Actor](https://apify.com/malonestar) that this server invokes through the Apify API. The server starts the run, waits for a terminal state, and returns the rows.
+
+**Billing** is to your own Apify account at each actor's published pay-per-result rate, listed on its Store page. Free-tier credit covers evaluation. A run that fails bills nothing beyond a fractional actor-start charge.
+
+Every result carries the `run_id` and a `console.apify.com` URL, so any claim an agent makes from this server can be traced back to the exact run that produced it.
+
+## On honest answers
+
+These actors are built around one rule: **a failure must never be presentable as "nothing was found."** That distinction matters most in exactly the cases people use this for — telling a buyer a property is clear of contamination, telling a pilot an airspace is uncontrolled, telling a lender a borrower is unlicensed.
+
+So this server:
+
+- reports `run_status` on every call, and never attaches a `rows` key to a run that did not succeed
+- distinguishes *"the run SUCCEEDED and the source genuinely matched nothing"* from *"the run failed"* in the response text, explicitly
+- retries transient Apify 429/5xx, then fails loudly saying the platform failed and no conclusion should be drawn about the government source
+- treats an unknown tool name as a catalog miss, never as an empty result
+
+The underlying actors carry the same discipline: per-source status on every row, `null` meaning *not checked* rather than *checked and negative*, live drift assertions that fail the run when an upstream silently truncates, and pagination guards on sources that answer HTTP 200 with a partial payload. Each actor's Store page documents the specific traps it defends against.
+
+## Coverage
+
+Environmental & contamination · flood, wildfire, seismic, landslide, karst & sea-level rise · wetlands, critical habitat, protected lands & historic places · energy siting, grid, pipelines & interconnection · farmland, soils & water rights · banking, credit unions & fair lending · securities, auditors & pension plans · professional licensing & exclusion screening · real-estate leads, parcels, deeds & distress signals · drone airspace, bridges, tunnels & dams.
+
+Run `search_gov_data_tools` with any of those terms for the full list, or browse [apify.com/malonestar](https://apify.com/malonestar).
+
+## Development
+
+```bash
+npm install
+npm test              # offline suite, no network
+node tools/mutate.cjs # re-injects known defects, asserts the suite catches them
+npm run catalog -- <apify-token>   # regenerate src/catalog.json from the live API
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "gov-data-mcp",
+  "version": "1.0.0",
+  "mcpName": "io.github.malonestar/gov-data-mcp",
+  "description": "MCP server exposing 95 US government open-data tools (EPA, FEMA, USGS, NOAA, FAA, USACE, FDIC, HUD, state licensing boards) as agent-callable tools, backed by published Apify Actors.",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "gov-data-mcp": "src/index.js"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test test/tools.test.js test/apify.test.js test/catalog.test.js",
+    "catalog": "node tools/gen-catalog.cjs",
+    "check:catalog": "node tools/check-catalog-live.cjs"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "mcp-server",
+    "government-data",
+    "open-data",
+    "epa",
+    "fema",
+    "usgs",
+    "noaa",
+    "faa",
+    "fdic",
+    "environmental",
+    "due-diligence",
+    "phase-i-esa",
+    "real-estate",
+    "compliance",
+    "apify"
+  ],
+  "author": "malonestar <57780205+malonestar@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/malonestar/gov-data-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/malonestar/gov-data-mcp/issues"
+  },
+  "homepage": "https://github.com/malonestar/gov-data-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  }
+}

package/src/apify.js

@@ -0,0 +1,194 @@
+/**
+ * Apify API client.
+ *
+ * `fetch` is injected so every branch below is reachable from the offline test
+ * suite. Nothing in this file may reach the network on import.
+ *
+ * DESIGN NOTE — why this polls instead of using run-sync-get-dataset-items:
+ * the sync endpoint hands back dataset rows without an unambiguous run status,
+ * so an actor that FAILED and an actor that legitimately matched nothing can
+ * arrive at the caller looking identical. Both are then reported to an agent as
+ * "no results", which is a confident negative the run never actually verified.
+ * Polling costs one extra request and makes the distinction explicit.
+ */
+
+const API = 'https://api.apify.com/v2';
+
+export const TERMINAL_STATES = ['SUCCEEDED', 'FAILED', 'ABORTED', 'TIMED-OUT'];
+
+export class ApifyError extends Error {
+  constructor(message, { status = null, runId = null, retryable = false } = {}) {
+    super(message);
+    this.name = 'ApifyError';
+    this.status = status;
+    this.runId = runId;
+    this.retryable = retryable;
+  }
+}
+
+export function createClient({ token, fetchImpl = globalThis.fetch, sleep = ms => new Promise(r => setTimeout(r, ms)), now = () => Date.now() }) {
+  if (!token) throw new ApifyError('APIFY_TOKEN is not set. Create a token at https://console.apify.com/settings/integrations and set APIFY_TOKEN in your MCP client config.');
+
+  async function request(pathname, { method = 'GET', body, attempt = 1 } = {}) {
+    const res = await fetchImpl(API + pathname, {
+      method,
+      headers: {
+        Authorization: 'Bearer ' + token,
+        ...(body ? { 'Content-Type': 'application/json' } : {}),
+      },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+
+    // 429 and 5xx are transient. Everything else is an answer, including 4xx.
+    if (res.status === 429 || res.status >= 500) {
+      if (attempt >= 4) {
+        throw new ApifyError(`Apify API ${method} ${pathname} failed with HTTP ${res.status} after ${attempt} attempts. This is an Apify platform problem, not a data problem — no conclusion should be drawn about the underlying government source.`, { status: res.status, retryable: true });
+      }
+      await sleep(500 * 2 ** (attempt - 1));
+      return request(pathname, { method, body, attempt: attempt + 1 });
+    }
+
+    let json = null;
+    const text = await res.text();
+    try { json = text ? JSON.parse(text) : null; } catch {
+      throw new ApifyError(`Apify API ${method} ${pathname} returned HTTP ${res.status} with a non-JSON body (first 200 chars: ${text.slice(0, 200)}).`, { status: res.status });
+    }
+
+    if (!res.ok) {
+      const detail = json && json.error ? `${json.error.type}: ${json.error.message}` : `HTTP ${res.status}`;
+      throw new ApifyError(`Apify API ${method} ${pathname} failed — ${detail}`, { status: res.status });
+    }
+
+    // TWO ENVELOPE SHAPES, and assuming one costs you the other silently.
+    // Most Apify v2 endpoints wrap their payload as { data: ... }, but
+    // /datasets/<id>/items returns a BARE JSON ARRAY. Reading `.data` off that
+    // array yields undefined, which downstream reads as "no rows" — a confident
+    // empty result produced by a request that actually succeeded. Measured
+    // 2026-08-11: this made every dataset read return [] forever while the
+    // dataset's own itemCount correctly reported 1.
+    if (Array.isArray(json)) return json;
+    return json && Object.prototype.hasOwnProperty.call(json, 'data') ? json.data : json;
+  }
+
+  /**
+   * Read a dataset that has just been written, without believing an early zero.
+   *
+   * MEASURED 2026-08-11: a karst screener run reached SUCCEEDED, the dataset read
+   * one millisecond later returned [], and the same dataset held 1 row (65 fields,
+   * in_karst_terrain: true) moments afterwards. Both `itemCount` and the items
+   * endpoint lag the run's terminal state, and they lag TOGETHER — so a single
+   * sample is not evidence. Reporting that first read would have told the caller
+   * the source "genuinely matched nothing" about a site that is in carbonate karst.
+   *
+   * The delay is INTERMITTENT, not a fixed cost: measured on the same actor and
+   * the same dataset endpoint, one run was readable 0 ms after finishing and
+   * another was still unreadable at 21 s while its own itemCount already said 1.
+   * A cache-busting parameter made no difference, so this is genuine propagation,
+   * not a stale edge cache. Hence a generous ceiling — a premature give-up wastes
+   * a run the caller has already paid for.
+   *
+   * A zero is only accepted after `minReads` independent reads spanning at least
+   * `minWindowMs`, all of which agreed that both signals were zero.
+   */
+  async function settleDataset(datasetId, maxItems, { minReads = 3, minWindowMs = 4000, maxWaitMs = 60000, gapMs = 2000 } = {}) {
+    const started = now();
+    let reads = 0;
+    let lastCount = 0;
+    while (true) {
+      const [meta, items] = await Promise.all([
+        request(`/datasets/${datasetId}`),
+        request(`/datasets/${datasetId}/items?limit=${maxItems}&clean=true`),
+      ]);
+      const rows = Array.isArray(items) ? items : [];
+      // Take the max of both signals; either one being non-zero disproves "empty".
+      lastCount = Math.max(rows.length, (meta && meta.itemCount) || 0);
+      reads += 1;
+      if (rows.length > 0) return { ok: true, items: rows };
+
+      const elapsed = now() - started;
+      if (lastCount === 0 && reads >= minReads && elapsed >= minWindowMs) {
+        return { ok: true, items: [] };
+      }
+      if (elapsed >= maxWaitMs) {
+        if (lastCount > 0) {
+          return {
+            ok: false,
+            message: `The run SUCCEEDED and its dataset reports ${lastCount} row(s), but the rows were still not readable after ${Math.round(elapsed / 1000)}s. This is an Apify dataset-propagation delay, not an empty result — retry the call, or read the dataset directly. No conclusion should be drawn about the underlying source.`,
+          };
+        }
+        return { ok: true, items: [] };
+      }
+      await sleep(gapMs);
+    }
+  }
+
+  return {
+    request,
+
+    /**
+     * Start a run, wait for a terminal state, and return rows.
+     * Resolves with { status, runId, items, itemCount, datasetId, statusMessage }.
+     * A non-SUCCEEDED terminal state RESOLVES rather than throwing so the caller
+     * can report the distinction between "failed" and "matched nothing" verbatim.
+     */
+    async runActor(actorId, input, { waitSecs = 300, pollMs = 2000, maxItems = 200 } = {}) {
+      const slug = actorId.replace('/', '~');
+      const run = await request(`/acts/${slug}/runs`, { method: 'POST', body: input });
+      const runId = run.id;
+
+      const deadline = now() + waitSecs * 1000;
+      let status = run.status;
+      let current = run;
+      while (!TERMINAL_STATES.includes(status)) {
+        if (now() > deadline) {
+          return {
+            status: 'CLIENT_TIMEOUT',
+            runId,
+            items: [],
+            itemCount: 0,
+            datasetId: current.defaultDatasetId || null,
+            statusMessage: `The run did not reach a terminal state within ${waitSecs}s. It is still running on Apify — check https://console.apify.com/actors/runs/${runId}. No result is available yet; this is NOT evidence that the source returned nothing.`,
+          };
+        }
+        await sleep(pollMs);
+        current = await request(`/actor-runs/${runId}`);
+        status = current.status;
+      }
+
+      const datasetId = current.defaultDatasetId;
+      if (status !== 'SUCCEEDED') {
+        return {
+          status,
+          runId,
+          items: [],
+          itemCount: 0,
+          datasetId,
+          statusMessage: `The run terminated with status ${status}${current.statusMessage ? ` — ${current.statusMessage}` : ''}. These actors are built to fail loudly rather than emit a misleading empty result, so treat this as "the question was not answered", never as "nothing was found".`,
+        };
+      }
+
+      const settled = await settleDataset(datasetId, maxItems);
+      if (!settled.ok) {
+        return {
+          status: 'DATASET_UNSETTLED',
+          runId,
+          items: [],
+          itemCount: 0,
+          datasetId,
+          statusMessage: settled.message,
+        };
+      }
+      const rows = settled.items;
+      return {
+        status,
+        runId,
+        items: rows,
+        itemCount: rows.length,
+        datasetId,
+        statusMessage: rows.length === 0
+          ? 'The run SUCCEEDED and the actor emitted zero rows. For these actors that is a real answer — the query was well-formed, the source was reached, and it genuinely matched nothing.'
+          : null,
+      };
+    },
+  };
+}