@pipeworx/mcp-grants-gov 0.1.2 → 0.1.4

package/README.md

@@ -2,16 +2,32 @@
 
 Grants.gov MCP — open federal funding opportunities, no auth.
 
-Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1681+ live data sources.
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1686+ live data sources.
 
 ## Tools
 
+Live (proxies Grants.gov's search2 API — currently-open coverage only):
+
 - `search_opportunities(keyword?, status?, agencies?, funding_categories?, aln?, limit?, offset?)` — filter open opportunities.
 - `get_opportunity(opportunity_id)` — full record with synopsis, eligibility, attachments.
 
-## Data source
+Local mirror (fleet #2512 — closed, archived and forecasted history the live API cannot serve):
+
+- `search_historical_opportunities(agency_code?, cfda?, keyword?, status?, opportunity_category?, post_date_from?, post_date_to?, limit?, offset?)` — search the FULL extract, every status, back to 2004.
+- `get_historical_opportunity(opportunity_id)` — one record, any status, with a computed `status`.
+- `agency_posting_trend(agency_code, years?)` — an agency's opportunity count / funding by federal fiscal year.
+
+## Data sources
 
-`https://api.grants.gov/v1/api/` — public POST-JSON API, no key required.
+- Live: `https://api.grants.gov/v1/api/` — public POST-JSON API, no key required.
+- Mirror: Grants.gov's own daily full-catalog XML extract (`grants.gov/xml-extract` ->
+  `prod-grants-gov-chatbot.s3.amazonaws.com/extracts/GrantsDBExtract<YYYYMMDD>v2.zip`,
+  no auth). Loaded into Supabase `grants_gov_opportunities`
+  (`supabase/migrations/226_grants_gov_extract.sql`) by
+  `scripts/grants-gov-upsert.sh` via `.github/workflows/grants-gov-refresh.yml`
+  (`workflow_dispatch` for now — see that workflow for why no `schedule:` is
+  wired yet). Every mirror response carries `data_as_of`, the last successful
+  refresh.
 
 ## Quick Start
 
@@ -57,7 +73,7 @@ directly, instead of just this one's:
 }
 ```
 
-Both URLs reach the same gateway and the same 1681+ data sources. The
+Both URLs reach the same gateway and the same 1686+ data sources. The
 only difference is which pack's tools are listed **directly**; `ask_pipeworx`
 reaches all of them from either one.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipeworx/mcp-grants-gov",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Grants.gov MCP — open federal grant opportunities (free, no auth)",
   "type": "module",
   "main": "src/index.ts",
@@ -26,7 +26,7 @@
     "@cloudflare/workers-types": "^4.20260405.1"
   },
   "pipeworx": {
-    "sourceHash": "v1-be925a6e6350a16b702fd0c26a84dc08a92ebe3529b5908765bf64aeb6a04074",
-    "sourceCommit": "d82b03e5d3bf01fd0dfba214ff31dabe330f2ab6"
+    "sourceHash": "v1-ed594888eaeec8bf4a0e21bd489348e332b301028709ac493d6709e0557847d1",
+    "sourceCommit": "658bedc4e66c6eab7e17c569f81012a2ee312624"
   }
 }

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.pipeworx-io/grants-gov",
   "title": "Grants Gov",
   "description": "Grants.gov MCP — open federal grant opportunities (free, no auth)",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "websiteUrl": "https://pipeworx.io/packs/grants-gov",
   "repository": {
     "url": "https://github.com/pipeworx-io/mcp-grants-gov",

package/src/index.ts

@@ -452,7 +452,42 @@ async function fetchWithTimeout(
         ),
       );
     }
-    throw err;
+    // Fleet #2382. Everything that isn't a timeout/abort here is a genuine
+    // NETWORK-LEVEL failure — DNS resolution, connection refused, TLS handshake,
+    // Cloudflare's own "Network connection lost." — meaning `fetch()` itself
+    // threw and no HTTP response of any kind was ever received. Until this fix
+    // that raw exception was rethrown VERBATIM: a bare `TypeError: fetch failed`
+    // (or the Workers-runtime equivalent) names no upstream, carries no class
+    // token, and reads exactly like a defect in OUR code — because it says
+    // nothing about the call at all. It landed in `error`, the tier that means
+    // "Pipeworx has a defect", for every one of the (at the time of writing)
+    // ~470 packs that call this helper directly with no wrapper of their own.
+    //
+    // `dexscreener` hit this independently (fleet #1579) and fixed it with a
+    // bespoke per-pack try/catch around `fetchWithTimeout`. That fix is correct
+    // but only covers one pack; every other caller of this shared helper still
+    // leaked the raw exception. Moving the same fix HERE — the one place that
+    // already carries the timeout case — covers every pack that uses
+    // `fetchWithTimeout` without a wrapper, for free, and without widening
+    // `classifyToolError`'s regex list: the fix is giving the message a proper
+    // `upstream_down:` token at the point the two facts (no response was ever
+    // received, and which host we were trying to reach) are actually in hand,
+    // not teaching the classifier to guess from prose after the fact.
+    //
+    // Safe on the same grounds as the timeout branch above: no argument a
+    // caller passes can make `fetch()` itself throw a connection-level error,
+    // so this is always an availability failure, never a caller mistake. Same
+    // `markInternalOrigin` treatment — an origin we run that never answered is
+    // still ours, not a third party's outage.
+    const raw = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      markInternalOrigin(
+        `upstream_down: could not reach ${name} at all (${raw.slice(0, 160)}). ` +
+          `No request reached ${name}, so this says NOTHING about whether the arguments you passed ` +
+          'are valid — do not re-check them on the strength of this error. Retry shortly.',
+        url,
+      ),
+    );
   }
 }
 
@@ -642,9 +677,38 @@ function collapse(s: string): string {
  * the federal-wide clearinghouse for currently-open and forecasted opportunities.
  *
  * API: https://www.grants.gov/web/grants/s2s/grantor/schemas/grants-gov-search2.html
- * Tools:
+ * Tools (live proxy, currently-open coverage only):
  * - search_opportunities: filter by keyword, status, agency, funding category, dates
  * - get_opportunity:      single full record with attachments and synopsis text
+ *
+ * Tools (local mirror, fleet #2512 — closed/archived/forecasted history the
+ * live API structurally cannot serve):
+ * - search_historical_opportunities: agency/CFDA/keyword/status (incl. closed
+ *   and forecasted)/date-range search over the FULL extract, back to 2004.
+ * - get_historical_opportunity:      one record from the mirror, any status.
+ * - agency_posting_trend:            an agency's opportunity count / funding
+ *   by fiscal year, derived from post_date.
+ *
+ * WHY A MIRROR FOR HISTORY: search2 (BASE_URL below) is Grants.gov's live
+ * index and only usefully answers "what is open or about to open right
+ * now" — there is no live endpoint for "what did this agency post five
+ * fiscal years ago" or "what was forecasted but never opened". Per Bruce's
+ * 2026-09-23 ruling ("build a copy when live doesn't serve"), the historical
+ * tools below read migration 226's grants_gov_opportunities, loaded from
+ * Grants.gov's own daily full-catalog XML export
+ * (grants.gov/xml-extract -> prod-grants-gov-chatbot.s3.amazonaws.com,
+ * verified live 2026-09-30: 83,497 records, no auth) by
+ * scripts/grants-gov-upsert.sh via .github/workflows/grants-gov-refresh.yml.
+ * `data_as_of` is on every mirror response (the last successful refresh,
+ * read from grants_gov_ingest_runs via the grants_gov_coverage() RPC).
+ * The live tools (search_opportunities/get_opportunity) are UNCHANGED —
+ * they still proxy search2 for the "what's open right now" case, which the
+ * mirror (refreshed once daily) is never quite fresh enough for.
+ *
+ * NO NEW PERSONAL DATA: the mirror carries GrantorContactName/Text, an
+ * agency's published point-of-contact for the opportunity — the same class
+ * of disclosure get_opportunity's live GrantorContact* fields already
+ * surface; see the migration file for the full reasoning.
  */
 
 
@@ -667,14 +731,18 @@ const tools: McpToolExport['tools'] = [
     inputSchema: {
       type: 'object',
       properties: {
-        keyword: { type: 'string', description: 'Full-text query' },
+        keyword: {
+          type: 'string',
+          description:
+            'Grants.gov\'s own keyword match behaves like an exact/AND phrase across title and synopsis text, not a relevance-ranked full-text search — a compound multi-concept phrase (e.g. joining three unrelated nouns) routinely matches ZERO opportunities even when relevant ones are open (verified live 2026-09-25, fleet #2450: "cancer liquid biopsy diagnostic" -> 0 hits; the single word "SBIR" -> 29 hits including the exact NIH SBIR/STTR hub the compound phrase was trying to find). Prefer ONE short, salient term ("SBIR", "liquid biopsy", "wastewater") and narrow with `agencies`/`funding_categories`/`status` instead of cramming every concept into this field. A zero-hit result is worth one retry with a shorter keyword before concluding nothing is open.',
+        },
         status: {
           type: 'string',
           description: 'forecasted | posted | closed | archived (default posted; use a pipe to combine, e.g. "posted|forecasted")',
         },
         open_only: { type: 'boolean', description: 'true restricts to currently-open or forthcoming opportunities (same as status "posted|forecasted"); omit or false leaves status at its default. Alias for status when a caller only knows open/not-open, not the exact status vocabulary.' },
-        agencies: { type: 'string', description: 'Comma-separated agency codes (e.g., "EPA,USDA,NIH"). A parent department code (e.g. "HHS") also matches its sub-agencies (NIH, CDC, FDA, ...) — Grants.gov indexes opportunities under the posting sub-agency, not just the department.' },
-        agency: { type: 'string', description: 'Alias for `agencies` — a single agency or department code (e.g. "NIH" or "HHS").' },
+        agencies: { type: 'string', description: 'Comma-separated agency codes (e.g., "EPA,USDA" or a bare department like "HHS" or "NIH"). Grants.gov itself indexes opportunities under a FULLY-QUALIFIED sub-agency code ("HHS-NIH11", "HHS-CDC1", ...), and its own filter returns ZERO hits for a bare department code (verified live 2026-09-25, fleet #2450) — this tool detects a bare code automatically and matches it client-side against every hit\'s sub-agency code instead of sending it upstream, so "HHS" still finds NIH/CDC/FDA opportunities. A code you already have in the full "DEPT-SUBAGENCY#" form is sent upstream unchanged.' },
+        agency: { type: 'string', description: 'Alias for `agencies` — a single agency or department code (e.g. "NIH" or "HHS"; see `agencies` for how a bare code is matched).' },
         funding_categories: {
           type: 'string',
           description: 'Comma-separated category codes (e.g., "ED" education, "ENV" environment, "ST" science)',
@@ -701,6 +769,63 @@ const tools: McpToolExport['tools'] = [
       required: ['opportunity_id'],
     },
   },
+  {
+    name: 'search_historical_opportunities',
+    description:
+      'Search Grants.gov\'s FULL opportunity history (closed and archived opportunities back to 2004, plus forecasted opportunities not yet posted) — coverage search_opportunities\' live API cannot serve, since search2 only usefully answers "what is open right now". Covers Grants.gov\'s full catalog, refreshed once a day (see `data_as_of`). Filter by agency code, CFDA/Assistance Listing number, keyword (full-text over title + description), status, opportunity category, or post-date range. Unlike search_opportunities, status here defaults to EVERY status, not just "posted" — pass status explicitly to narrow. Answers "what did this agency fund last fiscal year", "what opportunities under CFDA 93.351 have ever closed", "what is forecasted for next year that hasn\'t posted yet".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        agency_code: {
+          type: 'string',
+          description: 'Agency or sub-agency code, e.g. "NIH" or "HHS-NIH11" or "DOS". Matches as a prefix/segment against the fully-qualified codes on file (same bare-vs-qualified forgiveness as search_opportunities\' `agencies`). Alias: agency.',
+        },
+        agency: { type: 'string', description: 'Alias for agency_code.' },
+        cfda: { type: 'string', description: 'Assistance Listing Number / CFDA number, exact match, e.g. "93.351". Alias: aln.' },
+        aln: { type: 'string', description: 'Alias for cfda.' },
+        keyword: { type: 'string', description: 'Full-text search over the opportunity title and description (PostgreSQL websearch syntax — quote a phrase, "-word" to exclude). More forgiving than the live tool\'s exact-phrase keyword match.' },
+        status: {
+          type: 'string',
+          description: 'posted | closed | archived | forecasted. Omit to search every status, unlike the live tool (whose default is "posted").',
+        },
+        opportunity_category: { type: 'string', description: 'Single-letter Grants.gov category code: D discretionary, M mandatory, C continuation, E earmark, O other.' },
+        post_date_from: { type: 'string', description: 'Only opportunities posted on/after this date, YYYY-MM-DD.' },
+        post_date_to: { type: 'string', description: 'Only opportunities posted on/before this date, YYYY-MM-DD.' },
+        limit: { type: 'number', description: 'Rows to return, 1-500 (default 25).' },
+        offset: { type: 'number', description: '0-based start record, for paging.' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'get_historical_opportunity',
+    description:
+      'Fetch one Grants.gov opportunity by its numeric opportunity ID, in ANY status (open, closed, archived, or forecasted) — unlike get_opportunity, which calls the live API and only reliably resolves currently-open opportunities. Returns the full record plus a computed `status` (derived from close/archive dates against today, the same vocabulary search_historical_opportunities uses) and `data_as_of`.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        opportunity_id: {
+          type: 'number',
+          description: 'Numeric opportunity ID (returned by search_historical_opportunities or search_opportunities as "id").',
+        },
+      },
+      required: ['opportunity_id'],
+    },
+  },
+  {
+    name: 'agency_posting_trend',
+    description:
+      'An agency\'s opportunity-posting trend by federal fiscal year (Oct-Sep): how many opportunities it posted, total estimated program funding, and average award ceiling, per year. Answers "is this agency posting more or fewer opportunities than last year" and "how has this agency\'s funding trended". Fiscal year is derived from each opportunity\'s post_date.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        agency_code: { type: 'string', description: 'Agency or sub-agency code, e.g. "EPA", "NIH", "HHS-CDC1". Matches as a prefix/segment, same forgiveness as search_historical_opportunities. Alias: agency.' },
+        agency: { type: 'string', description: 'Alias for agency_code.' },
+        years: { type: 'number', description: 'Number of most-recent fiscal years to return, 1-40 (default 10).' },
+      },
+      required: [],
+    },
+  },
 ];
 
 function reqNum(args: Record<string, unknown>, key: string, example: string): number {
@@ -712,7 +837,12 @@ function reqNum(args: Record<string, unknown>, key: string, example: string): nu
   return n;
 }
 
+const MIRROR_TOOLS = new Set(['search_historical_opportunities', 'get_historical_opportunity', 'agency_posting_trend']);
+
 async function callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+  if (MIRROR_TOOLS.has(name)) {
+    return callMirrorTool(name, args);
+  }
   switch (name) {
     case 'search_opportunities':
       return searchOpps(args);
@@ -738,15 +868,39 @@ async function grantsPost<T>(path: string, body: unknown): Promise<T> {
 
 async function searchOpps(args: Record<string, unknown>) {
   const status = (args.status as string) ?? (args.open_only === true ? 'posted|forecasted' : 'posted');
+  const requestedRows = Math.min(1000, Math.max(1, (args.limit as number) ?? 25));
+  const requestedOffset = Math.max(0, (args.offset as number) ?? 0);
+
+  const rawAgencies = args.agencies ?? args.agency;
+  const wantedAgencies = rawAgencies
+    ? String(rawAgencies).split(',').map((s) => s.trim()).filter(Boolean)
+    : [];
+  // A code is "bare" when Grants.gov's own filter cannot use it (see
+  // agencyMatches' header) — anything without a hyphen, since every real
+  // sub-agency code observed live is DEPT-SUBAGENCY#, e.g. "HHS-NIH11".
+  const bareAgencies = wantedAgencies.filter((a) => !a.includes('-'));
+  const needsClientSideAgencyFilter = bareAgencies.length > 0;
+
   const body: Record<string, unknown> = {
-    rows: Math.min(1000, Math.max(1, (args.limit as number) ?? 25)),
-    startRecordNum: (args.offset as number) ?? 0,
+    // When any wanted code is bare, upstream's own agencies filter cannot
+    // resolve it (verified live: {agencies:"HHS"} -> hitCount 0 despite open
+    // HHS-NIH* opportunities) — so ask for a full page and filter client-side
+    // below instead of asking upstream to do something it cannot do. 1000 is
+    // the documented upstream max; sortBy keeps the page deterministic run to
+    // run so client-side pagination (offset applied after filtering) is stable.
+    rows: needsClientSideAgencyFilter ? 1000 : requestedRows,
+    startRecordNum: needsClientSideAgencyFilter ? 0 : requestedOffset,
     sortBy: 'openDate|desc',
     oppStatuses: status,
   };
   if (args.keyword) body.keyword = String(args.keyword);
-  const agencies = args.agencies ?? args.agency;
-  if (agencies) body.agencies = String(agencies);
+  // Only pass agencies upstream when EVERY wanted code is already fully
+  // qualified — mixing a bare and a qualified code and asking upstream to
+  // OR them together is not something search2 is known to do correctly, so
+  // a mix falls through to client-side filtering for all of them instead.
+  if (wantedAgencies.length && !needsClientSideAgencyFilter) {
+    body.agencies = wantedAgencies.join(',');
+  }
   if (args.funding_categories) body.fundingCategories = String(args.funding_categories);
   if (args.aln) body.cfda = String(args.aln);
 
@@ -763,14 +917,79 @@ async function searchOpps(args: Record<string, unknown>) {
     throw new Error(`Grants.gov: ${data.msg ?? 'unknown error'}`);
   }
 
-  const hits = data.data?.oppHits ?? [];
+  const rawHits = data.data?.oppHits ?? [];
+
+  if (!needsClientSideAgencyFilter) {
+    return {
+      total: data.data?.hitCount ?? 0,
+      returned: rawHits.length,
+      opportunities: rawHits.map(normalizeHit),
+    };
+  }
+
+  const matched = rawHits.filter((h) => agencyMatches(h.agencyCode, wantedAgencies));
+  const page = matched.slice(requestedOffset, requestedOffset + requestedRows);
   return {
-    total: data.data?.hitCount ?? 0,
-    returned: hits.length,
-    opportunities: hits.map(normalizeHit),
+    // Honest, not fabricated: this counts matches within the page upstream
+    // actually returned (up to 1000, the docs' own max), not a full-catalog
+    // total — the same distinction `truncated`/`shortfall` exist for
+    // elsewhere in the catalog. Upstream gave no way to ask for an exact
+    // department-level count directly.
+    total: matched.length,
+    returned: page.length,
+    opportunities: page.map(normalizeHit),
+    agency_filter_note:
+      `"${wantedAgencies.join(',')}" matched client-side against sub-agency codes in the ` +
+      `${rawHits.length} upstream hits for this status/keyword (Grants.gov's own agencies filter ` +
+      'needs a fully-qualified code like "HHS-NIH11", not a bare department code) — total reflects ' +
+      'matches within that page, not an exact full-catalog count for the department.',
   };
 }
 
+/**
+ * Does an opportunity's agency code satisfy one of the wanted codes?
+ *
+ * Grants.gov's real `agencyCode` values are DEPT-SUBAGENCY#, e.g.
+ * "HHS-NIH11", "HHS-CDC1", "DOD-AMRAA" — verified live 2026-09-25 (fleet
+ * #2450) by searching with no agency filter and reading back real hits'
+ * `agencyCode`. A caller (or the router picking arguments for them) very
+ * reasonably passes the bare department ("HHS", "NIH", "EPA") the way every
+ * OTHER agency-filtered pack in this catalog accepts it — Grants.gov's own
+ * `agencies` filter param does not accept that shape and returns hitCount 0
+ * rather than erroring, which is indistinguishable from "nothing is open"
+ * unless you already know to suspect the filter itself.
+ *
+ * Matches on: exact equality; the wanted code as a `-`-delimited segment of
+ * the hit's code (so "HHS" matches segment "HHS" of "HHS-NIH11", and "NIH"
+ * matches a segment that STARTS WITH "NIH" — "NIH11" — since the numeric
+ * suffix varies by sub-agency and is not itself part of any recognizable
+ * department code, so requiring segment equality would only ever match
+ * "NIH" against nothing); or the hit code starting with `wanted-` (handles a
+ * caller who already supplies the department-subagency prefix, e.g.
+ * "HHS-NIH", without the trailing number).
+ *
+ * The segment-PREFIX form (`seg.startsWith(w)`, for the numeric-suffix case
+ * above) only fires for a wanted code of 3+ characters — real department/
+ * sub-agency abbreviations run 2-4 letters, so at 2 characters segment-prefix
+ * matching starts producing false positives (a 2-letter code as a prefix of
+ * an unrelated 4-6 letter segment, e.g. wanted "NI" would otherwise match
+ * USDA's "NIFA" segment). Exact segment/whole-code equality still applies at
+ * any length, so a real 2-letter code ("ED", department of Education) still
+ * matches an upstream code that uses it as a whole segment.
+ */
+function agencyMatches(hitCode: string | undefined, wanted: string[]): boolean {
+  if (!hitCode) return false;
+  const upper = hitCode.trim().toUpperCase();
+  if (!upper) return false;
+  const segments = upper.split('-');
+  return wanted.some((raw) => {
+    const w = raw.trim().toUpperCase();
+    if (!w) return false;
+    if (upper === w || upper.startsWith(`${w}-`)) return true;
+    return segments.some((seg) => seg === w || (w.length >= 3 && seg.startsWith(w)));
+  });
+}
+
 async function getOpp(opportunityId: number) {
   const data = await grantsPost<{
     errorcode?: number;
@@ -882,4 +1101,234 @@ function normalizeDetail(d: OpportunityDetail) {
   };
 }
 
+/* ----------------------------------------------------- mirror (local DB) */
+
+interface DbConfig {
+  url: string;
+  key: string;
+}
+
+async function sbRpc(cfg: DbConfig, fn: string, body: Record<string, unknown>): Promise<unknown[]> {
+  const url = `${cfg.url}/rest/v1/rpc/${fn}`;
+  const res = await pwFetch(url, {
+    method: 'POST',
+    headers: {
+      apikey: cfg.key,
+      Authorization: `Bearer ${cfg.key}`,
+      'Content-Type': 'application/json',
+      Prefer: 'params=single-object',
+    },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) throw await httpError(res, 'Grants.gov historical data');
+  const parsed = await res.json();
+  if (!Array.isArray(parsed)) {
+    throw new Error('Grants.gov historical data: RPC did not return a row array — treating this as a failure.');
+  }
+  return parsed;
+}
+
+let cachedDataAsOf: { value: string | null; coverage: Record<string, unknown> | null } | undefined;
+
+/** The last successful refresh + coverage stats, read once per Worker instance and reused across calls. */
+async function mirrorCoverage(cfg: DbConfig): Promise<{ value: string | null; coverage: Record<string, unknown> | null }> {
+  if (cachedDataAsOf !== undefined) return cachedDataAsOf;
+  try {
+    const rows = (await sbRpc(cfg, 'grants_gov_coverage', {})) as Record<string, unknown>[];
+    const row = rows[0] ?? null;
+    cachedDataAsOf = { value: (row?.data_as_of as string | undefined) ?? null, coverage: row };
+  } catch {
+    cachedDataAsOf = { value: null, coverage: null }; // freshness is metadata, never the reason a call fails
+  }
+  return cachedDataAsOf;
+}
+
+function withDataAsOf<T extends Record<string, unknown>>(result: T, asOf: string | null): T & { data_as_of: string | null } {
+  return {
+    ...result,
+    data_as_of: asOf,
+    ...(asOf
+      ? {}
+      : {
+          coverage_status:
+            'The Grants.gov historical dataset has not completed its first load yet — results may be empty or incomplete. This is a deployment state, not a query problem.',
+        }),
+  };
+}
+
+function agencyArg(args: Record<string, unknown>): string | undefined {
+  const raw = (args.agency_code ?? args.agency) as string | undefined;
+  return raw ? String(raw).trim() : undefined;
+}
+
+interface MirrorSearchRow {
+  opportunity_id: number;
+  opportunity_title: string | null;
+  opportunity_number: string | null;
+  agency_code: string | null;
+  agency_name: string | null;
+  status: string | null;
+  post_date: string | null;
+  close_date: string | null;
+  fiscal_year: number | null;
+  cfda_numbers: string[] | null;
+  award_ceiling: number | null;
+  estimated_total_program_funding: number | null;
+  total_count: number;
+}
+
+function shapeSearchRow(r: MirrorSearchRow) {
+  return {
+    id: r.opportunity_id,
+    title: r.opportunity_title,
+    number: r.opportunity_number,
+    agency_code: r.agency_code,
+    agency: r.agency_name,
+    status: r.status,
+    post_date: r.post_date,
+    close_date: r.close_date,
+    fiscal_year: r.fiscal_year,
+    assistance_listing_numbers: r.cfda_numbers ?? [],
+    award_ceiling: r.award_ceiling,
+    estimated_total_program_funding: r.estimated_total_program_funding,
+    grants_gov_url: `https://www.grants.gov/search-results-detail/${r.opportunity_id}`,
+  };
+}
+
+async function searchHistorical(cfg: DbConfig, args: Record<string, unknown>) {
+  const limit = Math.min(500, Math.max(1, Number(args.limit) || 25));
+  const offset = Math.max(0, Number(args.offset) || 0);
+  const rows = (await sbRpc(cfg, 'grants_gov_search', {
+    p_agency_code: agencyArg(args) ?? null,
+    p_cfda: (args.cfda ?? args.aln) ? String(args.cfda ?? args.aln) : null,
+    p_keyword: args.keyword ? String(args.keyword) : null,
+    p_status: args.status ? String(args.status).toLowerCase() : null,
+    p_opportunity_category: args.opportunity_category ? String(args.opportunity_category) : null,
+    p_post_date_from: args.post_date_from ? String(args.post_date_from) : null,
+    p_post_date_to: args.post_date_to ? String(args.post_date_to) : null,
+    p_limit: limit,
+    p_offset: offset,
+  })) as MirrorSearchRow[];
+
+  return {
+    total: rows.length ? rows[0].total_count : 0,
+    returned: rows.length,
+    offset,
+    opportunities: rows.map(shapeSearchRow),
+    source: 'Grants.gov\'s own full-catalog extract, refreshed daily — covers every status, not just currently-open (see search_opportunities for the live-only view).',
+  };
+}
+
+async function getHistorical(cfg: DbConfig, opportunityId: number) {
+  const rows = (await sbRpc(cfg, 'grants_gov_get', { p_opportunity_id: opportunityId })) as Record<string, unknown>[];
+  const row = rows[0];
+  if (!row) {
+    return {
+      found: false,
+      reason: `No opportunity with id ${opportunityId} in Grants.gov's historical dataset.`,
+      hint: 'Check the id with search_historical_opportunities, or the id may belong to an opportunity type not yet loaded.',
+    };
+  }
+  const status =
+    row.record_type === 'forecast'
+      ? 'forecasted'
+      : !row.close_date || (row.close_date as string) >= new Date().toISOString().slice(0, 10)
+        ? 'posted'
+        : !row.archive_date || (row.archive_date as string) >= new Date().toISOString().slice(0, 10)
+          ? 'closed'
+          : 'archived';
+  return {
+    found: true,
+    id: row.opportunity_id,
+    record_type: row.record_type,
+    status,
+    title: row.opportunity_title,
+    number: row.opportunity_number,
+    category: row.opportunity_category,
+    funding_instrument_type: row.funding_instrument_type,
+    funding_activity_categories: row.category_of_funding_activity ?? [],
+    assistance_listing_numbers: row.cfda_numbers ?? [],
+    eligible_applicant_codes: row.eligible_applicant_codes ?? [],
+    eligibility_note: row.additional_information_on_eligibility,
+    agency_code: row.agency_code,
+    agency: row.agency_name,
+    post_date: row.post_date,
+    close_date: row.close_date,
+    archive_date: row.archive_date,
+    last_updated_date: row.last_updated_date,
+    award_ceiling: row.award_ceiling,
+    award_floor: row.award_floor,
+    estimated_total_program_funding: row.estimated_total_program_funding,
+    expected_number_of_awards: row.expected_number_of_awards,
+    description: row.description,
+    cost_sharing_required: row.cost_sharing_or_matching_requirement,
+    contact_name: row.grantor_contact_name,
+    contact_email: row.grantor_contact_email,
+    contact_phone: row.grantor_contact_phone_number,
+    fiscal_year: row.fiscal_year,
+    estimated_synopsis_post_date: row.estimated_synopsis_post_date,
+    estimated_synopsis_close_date: row.estimated_synopsis_close_date,
+    estimated_award_date: row.estimated_award_date,
+    grants_gov_url: `https://www.grants.gov/search-results-detail/${row.opportunity_id}`,
+    source: 'Grants.gov\'s own full-catalog extract, refreshed daily.',
+  };
+}
+
+interface TrendRow {
+  fiscal_year: number;
+  opportunities_posted: number;
+  total_estimated_funding: number | null;
+  avg_award_ceiling: number | null;
+}
+
+async function agencyTrend(cfg: DbConfig, args: Record<string, unknown>) {
+  const agency = agencyArg(args);
+  if (!agency) {
+    throw new Error('agency_posting_trend needs an agency code. Pass agency_code (or its alias agency), e.g. "EPA" or "HHS-NIH11".');
+  }
+  const years = Math.min(40, Math.max(1, Number(args.years) || 10));
+  const rows = (await sbRpc(cfg, 'grants_gov_agency_trend', { p_agency_code: agency, p_years: years })) as TrendRow[];
+  return {
+    agency_code: agency,
+    years_returned: rows.length,
+    trend: rows.map((r) => ({
+      fiscal_year: r.fiscal_year,
+      opportunities_posted: r.opportunities_posted,
+      total_estimated_funding: r.total_estimated_funding,
+      avg_award_ceiling: r.avg_award_ceiling,
+    })),
+    source: 'Grants.gov\'s own full-catalog extract, refreshed daily; fiscal year derived from each opportunity\'s post_date (federal FY = Oct-Sep).',
+  };
+}
+
+async function callMirrorTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+  const url = (args._supabaseUrl as string | undefined)?.trim();
+  const key = (args._supabaseKey as string | undefined)?.trim();
+  if (!url || !key) {
+    throw new Error(
+      'The Grants.gov historical dataset is not configured on this deployment — an operator must enable its data credentials. This is a setup problem, not your arguments. search_opportunities/get_opportunity (the live tools) do not need this and still work.',
+    );
+  }
+  const cfg: DbConfig = { url, key };
+  const asOf = await mirrorCoverage(cfg);
+
+  let result: unknown;
+  switch (name) {
+    case 'search_historical_opportunities':
+      result = await searchHistorical(cfg, args);
+      break;
+    case 'get_historical_opportunity':
+      result = await getHistorical(cfg, reqNum(args, 'opportunity_id', '363992 (numeric ID)'));
+      break;
+    case 'agency_posting_trend':
+      result = await agencyTrend(cfg, args);
+      break;
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+  return result && typeof result === 'object' && !Array.isArray(result)
+    ? withDataAsOf(result as Record<string, unknown>, asOf.value)
+    : result;
+}
+
 export default { tools, callTool, meter: { credits: 1 } } satisfies McpToolExport;

package/src/server.ts

@@ -9,7 +9,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import pack from './index.js';
 
 const server = new Server(
-  { name: '@pipeworx/mcp-grants-gov', version: '0.1.2' },
+  { name: '@pipeworx/mcp-grants-gov', version: '0.1.4' },
   { capabilities: { tools: {} } },
 );