gov-data-mcp 1.2.5 → 1.2.7

package/src/index.js

@@ -18,7 +18,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 
 import { createClient, ApifyError } from './apify.js';
-import { indexCatalog, listTools, searchCatalog, describeTool, resolveCall, formatRunResult, META_TOOLS } from './tools.js';
+import { indexCatalog, listTools, searchCatalog, describeTool, resolveCall, formatRunResult, serverInstructions, META_TOOLS } from './tools.js';
 import { parseCliArgs, resolvePreset, describePresets, PRESET_ENV } from './presets.js';
 
 const here = dirname(fileURLToPath(import.meta.url));
@@ -51,7 +51,7 @@ const identity = chosen.preset
 
 const server = new Server(
   identity,
-  { capabilities: { tools: {} } },
+  { capabilities: { tools: {} }, instructions: serverInstructions(index) },
 );
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: listTools(index) }));
@@ -82,7 +82,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const result = await client.runActor(`${catalog.owner}/${call.slug}`, call.input, {
       maxItems: call.maxItems ?? 200,
     });
-    const formatted = formatRunResult(call.slug, result);
+    const formatted = formatRunResult(call.slug, result, index.bySlug.get(call.slug));
     return text(formatted.text, formatted.isError);
   } catch (err) {
     if (err instanceof ApifyError) return text(`${err.message}`, true);

package/src/tools.js

@@ -54,6 +54,78 @@ export const RENAMED_IN_1_1 = {
   run_gov_data_tool: 'run-gov-data-tool',
 };
 
+/**
+ * Server-level guide, sent in the MCP `initialize` response as `instructions`.
+ *
+ * Written because the measured failure mode is agents GUESSING inputs: an agent
+ * that calls a screener with no state, no coordinates and no name starts a
+ * metered run that refuses the question (or matches nothing) and costs the
+ * caller an actor-start fee for no answer. Every rule below targets that.
+ */
+export function serverInstructions(index) {
+  const n = index.actors.length;
+  return [
+    `gov-data-mcp: ${n} tools over official US government open data (EPA, FEMA, USGS, FDIC, SEC, state licensing boards and registries, ...).${index.scopeNote || ''}`,
+    '',
+    'HOW TO CALL THESE TOOLS WELL',
+    `1. Find the tool: ${META_TOOLS.SEARCH} (free). 2. Read it: ${META_TOOLS.DESCRIBE} (free) - it returns mustSupply, exampleInput and run-verified examples. 3. Run it.`,
+    '4. Start from exampleInput or one of the examples and change only the values you need. These inputs are verified to return rows; a hand-built input usually is not.',
+    '5. Always SCOPE the question: a state, county, coordinates, a name, an NPI, a date window. Unscoped calls are refused by most tools or bill for whole national lists.',
+    '6. Use real values the source knows: two-letter state codes unless the schema says otherwise, decimal-degree lat/lon, ISO dates (YYYY-MM-DD). Never invent enum values - use the enum in the schema.',
+    '7. Keep the first call small (low maxResults / few assets) and widen once the shape works. Each call bills per row (see the price in the tool description).',
+    '',
+    'READING RESULTS',
+    '- run_status other than SUCCEEDED means the question was NOT answered. Read `note` (the tool explains what was wrong), fix the input, and do not retry the identical input.',
+    '- SUCCEEDED with zero rows means the source was reached and matched nothing for exactly that input. Before concluding "none exist", check the scope (radius, date window, spelling, state).',
+    '- null in a field means "not checked / not published", never "no". Many rows carry per-source status fields; read them before stating a negative.',
+  ].join('\n');
+}
+
+/**
+ * Free, local pre-flight check run BEFORE a metered call: required fields the
+ * caller must supply (required with no server default) and closed vocabularies.
+ * Apify would reject these too, but only after the agent has learned nothing
+ * useful; answering here returns the example to copy instead.
+ */
+export function preflight(actor, input) {
+  const problems = [];
+  const props = (actor.inputSchema && actor.inputSchema.properties) || {};
+  const given = input && typeof input === 'object' ? input : {};
+  for (const k of actor.mustSupply || []) {
+    const v = given[k];
+    if (v === undefined || v === null || v === '' || (Array.isArray(v) && v.length === 0)) problems.push(`"${k}" is required and was not supplied`);
+  }
+  for (const [k, v] of Object.entries(given)) {
+    const p = props[k];
+    if (!p) { problems.push(`"${k}" is not an input of this tool (known inputs: ${Object.keys(props).join(', ')})`); continue; }
+    if (Array.isArray(p.enum) && v !== undefined && v !== null && !p.enum.includes(v)) problems.push(`"${k}" must be one of ${JSON.stringify(p.enum)}, got ${JSON.stringify(v)}`);
+    const itemEnum = p.items && Array.isArray(p.items.enum) ? p.items.enum : null;
+    if (itemEnum && Array.isArray(v)) {
+      const bad = v.filter(x => !itemEnum.includes(x));
+      if (bad.length) problems.push(`"${k}" items must be from ${JSON.stringify(itemEnum)}, got ${JSON.stringify(bad)}`);
+    }
+  }
+  return problems;
+}
+
+/** What an agent should do next, attached to every non-SUCCEEDED or zero-row result. */
+export function guidanceFor(actor, kind) {
+  const ex = actor && actor.exampleInput ? actor.exampleInput : null;
+  const examples = actor && Array.isArray(actor.examples) ? actor.examples : [];
+  const base = kind === 'failed'
+    ? 'The question was not answered and no result rows were billed. Read `note` above for the reason, fix the input, and do not resend the same input.'
+    : kind === 'preflight'
+      ? 'Nothing was run and nothing was charged. Fix the input and call again.'
+      : 'Zero rows is an answer only for exactly this input. Before concluding nothing exists, check the scope: spelling, state code, radius, date window, mode.';
+  return {
+    next_step: `${base} Compare your input with example_input (verified to return rows) and change only the values you need.`,
+    must_supply: actor ? (actor.mustSupply || []) : [],
+    example_input: ex,
+    examples: examples.length ? examples : undefined,
+    describe: actor ? `${META_TOOLS.DESCRIBE} {"tool":"${actor.slug}"}` : undefined,
+  };
+}
+
 /** MCP tool names must match ^[a-zA-Z0-9_-]{1,64}$. Slugs already do. */
 export function toolNameFor(slug) {
   return slug;
@@ -180,8 +252,51 @@ export const ROUTING = {
   'epa-drinking-water-quality-screener':
     'CHOOSE THIS for public water-system quality: SDWA violations, lead 90th-percentile results and PFAS occurrence. '
     + 'It is NOT a property contamination screen — for soil and groundwater records at a site use epa-contaminated-site-screener.',
+  'faa-drone-airspace-checker':
+    'CHOOSE THIS for drone (Part 107) airspace questions at specific US points: airspace class, LAANC ceiling, restricted and special-use areas, temporary flight restrictions. '
+    + 'It does NOT screen ground conditions — for a site environmental or hazard screen use site-due-diligence-bundle. It reports what the FAA layers say; it does not request or grant an authorization.',
 };
 
+/**
+ * Parameter guidance for the featured tools: which inputs matter, how they
+ * interact, and how to keep a first call small. Input schemas already document
+ * each field on its own; what they cannot say is which combinations an agent
+ * should reach for, which inputs override others, and which one is the cost cap.
+ * Every input named here in backticks is asserted to exist in the live schema
+ * (test/guidance.test.js), so a renamed field fails the build rather than
+ * leaving advice that points at nothing.
+ */
+export const SCOPING = {
+  'site-due-diligence-bundle':
+    'INPUTS: `assets` is required (lat/lon per site). `radiusMiles` sets the proximity layers only; point-in-polygon layers ignore it. `maxAssets` is the cost cap, one billed row per site, so start with 1-3 sites.',
+  'epa-contaminated-site-screener':
+    'INPUTS: `mode` decides everything else. In "assets" mode supply `assets` (address or lat/lon) and `radiusMiles`; `states`, `onlyNpl` and `onlyWithCoords` are ignored. In "inventory" mode supply `states` and the asset inputs are ignored. One row per site hit is billed, so `maxHitsPerProgram` and `maxResults` are the cost levers; keep them low on a first call near dense industrial areas.',
+  'faa-drone-airspace-checker':
+    'INPUTS: `points` is required. `layers` narrows which FAA layers are checked; leave it empty for all eight. `maxPoints` is the cost cap, one billed row per point.',
+  'hifld-grid-proximity-screener':
+    'INPUTS: `assets` is required. `radiusMiles` bounds every layer. `minVoltageKv` filters lines only, never substations or plants, and drops lines with unknown voltage. `includeSubstations`, `includePowerPlants` and `includeUtility` add columns, not rows; turn them off to speed up large batches. `maxResults` caps assets, one billed row each.',
+  'interconnection-queue-tracker':
+    'INPUTS: leave `isos` empty for all seven ISOs, or name one or two to keep a first call small. `maxResults` is applied in ISO order, so a low value silently drops the later ISOs; raise it or narrow `isos` instead. For change monitoring use `deltaOnly` in snapshot mode rather than re-pulling the full queue.',
+  'fdic-ncua-health-rollup':
+    'INPUTS: always set `state`; an empty state scores the whole country and bills far more rows. `minAssets` and `maxAssets` are in THOUSANDS of dollars (1000000 = $1B) and together with `peerBasis` define who counts as a peer. `institutionType` "credit_union" is not available yet and fails the run. `maxResults` is the cost cap.',
+  'fema-nri-county-risk-profile':
+    'INPUTS: supply `assets` (FIPS, state+county, or lat/lon) for specific places; `states` and `counties` are used ONLY when `assets` is empty (inventory mode). `resolution` "tract" applies only to lat/lon assets and inventory pulls; FIPS or state+county assets always get county data. `maxResults` caps rows in both modes.',
+  'fws-wetlands-proximity-screener':
+    'INPUTS: `assets` is required. `radiusMeters` is the presence check (a true circle); `nearestSearchRadiusMeters` is independent and only bounds the nearest-wetland distance, so a site can read no wetland in radius and still report a nearest one. `maxResults` caps assets, one billed row each.',
+  'nhd-surface-water-404-screener':
+    'INPUTS: `assets` is required. `radiusMeters` 1000 covers a typical Phase I adjacent-property review; widen it only on purpose. Keep `includeNonNetworkFlowlines` on for a conservative screen. `runBudgetSeconds` trades completeness for speed when the USGS service is slow; a site cut by the budget reports null counts, not zero. `maxResults` caps sites, exactly one row each.',
+  'epa-drinking-water-quality-screener':
+    'INPUTS: supply `assets` (lat/lon, matched to a water system boundary) or `pwsids` (9-character EPA system ids) or both. `includePfas` is the slow leg; turn it off when PFAS is not the question. `violationYears` only changes the recent-violation flags, not the history summary. `maxAssets` is the cost cap.',
+  'parcel-owner-lookup':
+    'INPUTS: `addresses` is required, one full street address with city and state per entry. Coverage is a fixed list of county and state assessor rolls; every address still yields exactly one row, so read its lookup_status before treating a missing owner as an answer. `maxResults` caps addresses, one billed row each.',
+  'license-verifier':
+    'INPUTS: always scope with `states` (a state code searches every board in it; a board id targets one). The most precise search is `licenseNumber`; otherwise `lastName` plus `firstName`. `roster` runs a batch instead of a single search, and `mode` "roster-delta" switches to the newly-credentialed feed with `professions` and `sinceDays`. `maxResults` applies PER BOARD, so a bare state code can bill several boards; start with a low value.',
+};
+
+export function scopingNoteFor(slug) {
+  return SCOPING[slug] ? ` ${SCOPING[slug]}` : '';
+}
+
 /**
  * A routing note is only shown when every tool it points at is reachable on
  * THIS server. Under a preset, a note that sends the agent to a tool outside
@@ -204,7 +319,7 @@ export function featuredToolDefinitions(index) {
     const routing = routingNoteFor(index, slug);
     return {
       name: toolNameFor(slug),
-      description: `${a.title}. ${truncate(a.description, 400)}${routing} Reads live from the official government source. ${costNote(a.pricing)} Store page: ${a.storeUrl}`,
+      description: `${a.title}. ${truncate(a.description, 400)}${routing}${scopingNoteFor(slug)} Reads live from the official government source. Call ${META_TOOLS.DESCRIBE} (free) for a verified example input. ${costNote(a.pricing)} Store page: ${a.storeUrl}`,
       inputSchema: a.inputSchema,
       annotations: { title: a.title, ...ANNOTATIONS.BILLED_LIVE_READ },
     };
@@ -242,7 +357,7 @@ export function metaToolDefinitions(index) {
     {
       name: META_TOOLS.RUN,
       description: `Run any one of the ${n} catalog tools with the given input and return its rows. Call ${META_TOOLS.DESCRIBE} first to shape the input. `
-        + `${COST_NOTE} A run that FAILS returns an error and no rows rather than an empty result, so a zero-row answer here always means the source was reached and genuinely matched nothing.`,
+        + `${COST_NOTE} A run that FAILS returns an error and no rows rather than an empty result, so a zero-row answer means the source was reached and matched nothing for exactly that input. Failed and zero-row results carry next_step, must_supply and a verified example_input to copy. Inputs are checked locally first: a missing required field or an invalid enum value is reported free, without starting a run.`,
       annotations: { title: 'Run any government data tool', ...ANNOTATIONS.BILLED_LIVE_READ },
       inputSchema: {
         type: 'object',
@@ -308,13 +423,25 @@ export function describeTool(index, name) {
       ? { ...actor.pricing, summary: priceLine(actor.pricing) }
       : null,
     storeUrl: actor.storeUrl,
+    must_supply: actor.mustSupply || [],
+    example_input: actor.exampleInput || null,
+    examples: actor.examples || [],
+    how_to_call: 'Start from example_input (or one of examples): these inputs are verified to return rows. Change only the values you need, keep the call scoped (state / coordinates / name / date window) and keep the first call small. '
+      + `Run it with ${META_TOOLS.RUN} {"tool":"${actor.slug}","input":{...}}${index.featured && index.featured.includes(actor.slug) ? ` or call the dedicated "${actor.slug}" tool directly` : ''}.`,
     inputSchema: actor.inputSchema,
   };
 }
 
 /** Resolve a tool call to { slug, input } or an error, for both featured and meta RUN calls. */
 export function resolveCall(index, toolName, args) {
-  if (index.bySlug.has(toolName)) return { ok: true, slug: toolName, input: args || {}, maxItems: undefined };
+  const checked = (slug, input, maxItems) => {
+    const problems = preflight(index.bySlug.get(slug), input);
+    if (problems.length) {
+      return { ok: false, error: JSON.stringify({ tool: slug, run_status: 'NOT_RUN_INPUT_INVALID', problems, ...guidanceFor(index.bySlug.get(slug), 'preflight') }, null, 2) };
+    }
+    return { ok: true, slug, input, maxItems };
+  };
+  if (index.bySlug.has(toolName)) return checked(toolName, args || {}, undefined);
   if (toolName === META_TOOLS.RUN) {
     const slug = args && args.tool;
     if (!slug) return { ok: false, error: `${META_TOOLS.RUN} requires a "tool" argument naming which catalog tool to run.` };
@@ -322,7 +449,7 @@ export function resolveCall(index, toolName, args) {
       const near = searchCatalog(index, String(slug).replace(/[-_]/g, ' '), 5).map(r => r.tool);
       return { ok: false, error: `No tool named "${slug}" in this catalog.${near.length ? ` Closest matches: ${near.join(', ')}.` : ''}${index.scopeNote || ''}` };
     }
-    return { ok: true, slug, input: (args && args.input) || {}, maxItems: args && args.maxItems };
+    return checked(slug, (args && args.input) || {}, args && args.maxItems);
   }
   // A caller with a hardcoded pre-1.1 name gets told what happened rather than
   // silently aliased, so the hardcode gets fixed instead of quietly persisting.
@@ -333,7 +460,7 @@ export function resolveCall(index, toolName, args) {
 }
 
 /** Shape a run result into MCP text content. Never collapses a failure into an empty answer. */
-export function formatRunResult(slug, result) {
+export function formatRunResult(slug, result, actor = null) {
   const header = {
     tool: slug,
     run_status: result.status,
@@ -343,6 +470,10 @@ export function formatRunResult(slug, result) {
   };
   if (result.statusMessage) header.note = result.statusMessage;
   const failed = result.status !== 'SUCCEEDED';
+  // A run still in flight on Apify is not a wrong input; do not tell the agent to change it.
+  const pending = result.status === 'CLIENT_TIMEOUT' || result.status === 'DATASET_UNSETTLED';
+  if (actor && failed && !pending) Object.assign(header, guidanceFor(actor, 'failed'));
+  if (actor && !failed && result.itemCount === 0) Object.assign(header, guidanceFor(actor, 'zero'));
   return {
     isError: failed,
     text: JSON.stringify(failed ? header : { ...header, rows: result.items }, null, 2),