@cliwant/mcp-sam-gov 0.2.1

package/src/ecfr.ts

@@ -0,0 +1,127 @@
+/**
+ * eCFR (Electronic Code of Federal Regulations) wrappers (keyless).
+ *
+ * eCFR is the up-to-date version of the CFR — Title 48 = FAR (Federal
+ * Acquisition Regulation), Title 2 = Federal financial assistance, etc.
+ * For a federal contractor, eCFR is the primary source for regulation
+ * text the agent should quote when answering compliance questions.
+ *
+ * Endpoints:
+ *   - /versioner/v1/titles.json — list 50 CFR titles + last-amended dates
+ *   - /search/v1/results — full-text search across the entire CFR
+ *
+ * Both keyless. Documented at https://www.ecfr.gov/developers/.
+ */
+
+const ECFR = "https://www.ecfr.gov/api";
+
+async function fetchJson<T>(url: string): Promise<T> {
+  const r = await fetch(url, {
+    headers: { Accept: "application/json" },
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!r.ok) {
+    throw new Error(`eCFR ${url} returned ${r.status}`);
+  }
+  return (await r.json()) as T;
+}
+
+export async function listTitles() {
+  type Resp = {
+    titles?: {
+      number?: number;
+      name?: string;
+      latest_amended_on?: string;
+      latest_issue_date?: string;
+      up_to_date_as_of?: string;
+      reserved?: boolean;
+    }[];
+  };
+  const json = await fetchJson<Resp>(`${ECFR}/versioner/v1/titles.json`);
+  return {
+    titles: (json.titles ?? []).map((t) => ({
+      number: t.number ?? 0,
+      name: t.name ?? "",
+      latestAmendedOn: t.latest_amended_on,
+      latestIssueDate: t.latest_issue_date,
+      upToDateAsOf: t.up_to_date_as_of,
+      reserved: !!t.reserved,
+    })),
+  };
+}
+
+export async function search(args: {
+  query: string;
+  titleNumber?: number;
+  perPage?: number;
+}) {
+  const url = new URL(`${ECFR}/search/v1/results`);
+  url.searchParams.set("query", args.query);
+  url.searchParams.set("per_page", String(args.perPage ?? 5));
+  if (args.titleNumber) {
+    // eCFR search filter: hierarchy[title]=N (NOT just title=N — that's
+    // an "unpermitted parameter" error from the eCFR API).
+    url.searchParams.set("hierarchy[title]", String(args.titleNumber));
+  }
+
+  type Resp = {
+    results?: {
+      starts_on?: string;
+      ends_on?: string | null;
+      type?: string;
+      hierarchy?: {
+        title?: string;
+        chapter?: string;
+        subchapter?: string;
+        part?: string;
+        subpart?: string;
+        section?: string;
+      };
+      hierarchy_headings?: Record<string, string | null>;
+      headings?: Record<string, string | null>;
+      full_text_excerpt?: string;
+      score?: number;
+    }[];
+  };
+  const json = await fetchJson<Resp>(url.toString());
+  return {
+    results: (json.results ?? []).map((r) => ({
+      type: r.type ?? "",
+      title: r.hierarchy?.title ?? "",
+      chapter: r.hierarchy?.chapter,
+      part: r.hierarchy?.part,
+      subpart: r.hierarchy?.subpart,
+      section: r.hierarchy?.section,
+      headingPath: Object.values(r.hierarchy_headings ?? {})
+        .filter(Boolean)
+        .join(" › "),
+      excerpt: stripHtml(r.full_text_excerpt ?? ""),
+      score: r.score ?? 0,
+      // Stable ecfr.gov URL pattern from the hierarchy
+      ecfrUrl: r.hierarchy
+        ? buildEcfrUrl(r.hierarchy)
+        : "",
+      effectiveOn: r.starts_on ?? "",
+    })),
+  };
+}
+
+function stripHtml(s: string): string {
+  return s
+    .replace(/<[^>]+>/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function buildEcfrUrl(h: {
+  title?: string;
+  chapter?: string;
+  part?: string;
+  section?: string;
+}): string {
+  const base = `https://www.ecfr.gov/current/title-${h.title}`;
+  if (h.section) return `${base}/section-${h.section}`;
+  if (h.part) return `${base}/part-${h.part}`;
+  if (h.chapter) return `${base}/chapter-${h.chapter}`;
+  return base;
+}

package/src/federal-register.ts

@@ -0,0 +1,191 @@
+/**
+ * Federal Register API v1 wrappers (keyless, no registration).
+ *
+ * Federal Register is the daily journal of the US federal government —
+ * proposed rules, final rules, presidential documents, public notices.
+ * Critical context for any federal contracting question that touches
+ * regulation, set-aside policy, or new acquisition guidance.
+ *
+ * Endpoints:
+ *   - documents.json — search across documents (filters: agencies,
+ *     conditions, type, date range)
+ *   - documents/{number}.json — single document detail (full body URL,
+ *     abstract, citation, effective date)
+ *   - agencies.json — agency reference list
+ *
+ * All endpoints are public + keyless (no API key, no registration).
+ * Rate-limit: documented as ~1000 req/hour per IP (informal).
+ */
+
+const FED_REG = "https://www.federalregister.gov/api/v1";
+
+async function fetchJson<T>(url: string): Promise<T> {
+  const r = await fetch(url, {
+    headers: { Accept: "application/json" },
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!r.ok) {
+    throw new Error(`Federal Register ${url} returned ${r.status}`);
+  }
+  return (await r.json()) as T;
+}
+
+export type FedRegDocumentType =
+  | "RULE"
+  | "PRORULE"
+  | "NOTICE"
+  | "PRESDOCU"
+  | "UNKNOWN";
+
+const TYPE_MAP: Record<string, FedRegDocumentType> = {
+  Rule: "RULE",
+  "Proposed Rule": "PRORULE",
+  Notice: "NOTICE",
+  "Presidential Document": "PRESDOCU",
+};
+
+export async function searchDocuments(args: {
+  query?: string;
+  agencySlugs?: string[]; // e.g. ["veterans-affairs-department", "defense-department"]
+  type?: "RULE" | "PRORULE" | "NOTICE" | "PRESDOCU";
+  publicationDateFrom?: string; // YYYY-MM-DD
+  publicationDateTo?: string;
+  effectiveDateFrom?: string;
+  perPage?: number;
+}) {
+  const url = new URL(`${FED_REG}/documents.json`);
+  url.searchParams.set("per_page", String(args.perPage ?? 10));
+  if (args.query) {
+    url.searchParams.set("conditions[term]", args.query);
+  }
+  for (const slug of args.agencySlugs ?? []) {
+    url.searchParams.append("conditions[agencies][]", slug);
+  }
+  if (args.type) {
+    url.searchParams.append("conditions[type][]", args.type);
+  }
+  if (args.publicationDateFrom) {
+    url.searchParams.set(
+      "conditions[publication_date][gte]",
+      args.publicationDateFrom,
+    );
+  }
+  if (args.publicationDateTo) {
+    url.searchParams.set(
+      "conditions[publication_date][lte]",
+      args.publicationDateTo,
+    );
+  }
+  if (args.effectiveDateFrom) {
+    url.searchParams.set(
+      "conditions[effective_date][gte]",
+      args.effectiveDateFrom,
+    );
+  }
+
+  type Resp = {
+    count?: number;
+    total_pages?: number;
+    results?: {
+      title?: string;
+      type?: string;
+      abstract?: string;
+      document_number?: string;
+      html_url?: string;
+      pdf_url?: string;
+      publication_date?: string;
+      effective_on?: string;
+      agencies?: { name?: string; slug?: string }[];
+    }[];
+  };
+  const json = await fetchJson<Resp>(url.toString());
+  return {
+    totalRecords: json.count ?? 0,
+    totalPages: json.total_pages ?? 0,
+    documents: (json.results ?? []).map((d) => ({
+      documentNumber: d.document_number ?? "",
+      title: d.title ?? "",
+      type: TYPE_MAP[d.type ?? ""] ?? "UNKNOWN",
+      typeDisplay: d.type ?? "",
+      abstract: d.abstract ?? "",
+      htmlUrl: d.html_url ?? "",
+      pdfUrl: d.pdf_url,
+      publicationDate: d.publication_date ?? "",
+      effectiveDate: d.effective_on,
+      agencies: (d.agencies ?? []).map((a) => ({
+        name: a.name ?? "",
+        slug: a.slug ?? "",
+      })),
+    })),
+  };
+}
+
+export async function getDocument(documentNumber: string) {
+  type Resp = {
+    title?: string;
+    type?: string;
+    abstract?: string;
+    document_number?: string;
+    html_url?: string;
+    pdf_url?: string;
+    body_html_url?: string;
+    publication_date?: string;
+    effective_on?: string;
+    citation?: string;
+    page_length?: number;
+    raw_text_url?: string;
+    agencies?: { name?: string; slug?: string }[];
+    cfr_references?: { title?: string; part?: string; chapter?: string }[];
+  };
+  const json = await fetchJson<Resp>(
+    `${FED_REG}/documents/${encodeURIComponent(documentNumber)}.json`,
+  );
+  return {
+    documentNumber: json.document_number ?? "",
+    title: json.title ?? "",
+    type: TYPE_MAP[json.type ?? ""] ?? "UNKNOWN",
+    typeDisplay: json.type ?? "",
+    abstract: json.abstract ?? "",
+    htmlUrl: json.html_url ?? "",
+    pdfUrl: json.pdf_url,
+    rawTextUrl: json.raw_text_url,
+    publicationDate: json.publication_date ?? "",
+    effectiveDate: json.effective_on,
+    citation: json.citation,
+    pageCount: json.page_length,
+    agencies: (json.agencies ?? []).map((a) => ({
+      name: a.name ?? "",
+      slug: a.slug ?? "",
+    })),
+    cfrReferences: (json.cfr_references ?? []).map((c) => ({
+      title: c.title ?? "",
+      part: c.part,
+      chapter: c.chapter,
+    })),
+  };
+}
+
+export async function listAgencies(args: { perPage?: number }) {
+  type Resp = Array<{
+    id?: number;
+    name?: string;
+    short_name?: string;
+    slug?: string;
+    description?: string;
+    parent_id?: number | null;
+    json_url?: string;
+  }>;
+  const json = await fetchJson<Resp>(
+    `${FED_REG}/agencies.json?per_page=${args.perPage ?? 100}`,
+  );
+  return {
+    agencies: (json ?? []).map((a) => ({
+      id: a.id ?? 0,
+      name: a.name ?? "",
+      shortName: a.short_name,
+      slug: a.slug ?? "",
+      description: a.description ?? "",
+      parentId: a.parent_id,
+    })),
+  };
+}

package/src/grants.ts

@@ -0,0 +1,155 @@
+/**
+ * Grants.gov v1 API wrappers (keyless).
+ *
+ * Grants.gov hosts federal financial-assistance opportunities (grants,
+ * cooperative agreements). Distinct from SAM.gov contracts but the
+ * same pursuit ICP often cares about both.
+ *
+ * Endpoints (POST JSON, no key):
+ *   - /v1/api/search2 — search opportunities
+ *   - /v1/api/fetchOpportunity — single grant detail
+ *
+ * Documented at https://grants.gov/web/grants/s2s/grantor/schemas/grants-search-2-soap.html
+ */
+
+const GRANTS = "https://api.grants.gov/v1/api";
+
+async function postJson<T>(
+  endpoint: string,
+  body: Record<string, unknown>,
+): Promise<T> {
+  const r = await fetch(`${GRANTS}/${endpoint}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!r.ok) {
+    throw new Error(`Grants.gov ${endpoint} returned ${r.status}`);
+  }
+  return (await r.json()) as T;
+}
+
+export type GrantStatus = "forecasted" | "posted" | "closed" | "archived";
+
+export async function searchGrants(args: {
+  keyword?: string;
+  cfda?: string; // CFDA program number, e.g. "10.500"
+  agency?: string; // agency code, e.g. "DHS-FEMA"
+  oppNum?: string; // opportunity number
+  oppStatuses?: GrantStatus[];
+  rows?: number;
+}) {
+  const body: Record<string, unknown> = {
+    rows: args.rows ?? 10,
+    keyword: args.keyword ?? "",
+    cfda: args.cfda ?? "",
+    agencies: args.agency ?? "",
+    oppNum: args.oppNum ?? "",
+    oppStatuses: (args.oppStatuses ?? ["forecasted", "posted"]).join("|"),
+  };
+  type Resp = {
+    errorcode?: number;
+    msg?: string;
+    data?: {
+      hitCount?: number;
+      oppHits?: {
+        id?: string;
+        number?: string;
+        title?: string;
+        agencyCode?: string;
+        agencyName?: string;
+        openDate?: string;
+        closeDate?: string;
+        oppStatus?: string;
+        docType?: string;
+        cfdaList?: string;
+      }[];
+    };
+  };
+  const json = await postJson<Resp>("search2", body);
+  if (json.errorcode && json.errorcode !== 0) {
+    throw new Error(`Grants.gov error: ${json.msg ?? "unknown"}`);
+  }
+  return {
+    totalRecords: json.data?.hitCount ?? 0,
+    grants: (json.data?.oppHits ?? []).map((g) => ({
+      id: g.id ?? "",
+      opportunityNumber: g.number ?? "",
+      title: g.title ?? "",
+      agencyCode: g.agencyCode ?? "",
+      agencyName: g.agencyName ?? "",
+      openDate: g.openDate,
+      closeDate: g.closeDate,
+      status: g.oppStatus,
+      docType: g.docType,
+      cfdaList: g.cfdaList,
+    })),
+  };
+}
+
+export async function getGrant(args: { opportunityId: string }) {
+  type Resp = {
+    errorcode?: number;
+    msg?: string;
+    data?: {
+      id?: number;
+      opportunityNumber?: string;
+      opportunityTitle?: string;
+      owningAgencyCode?: string;
+      synopsisDesc?: string;
+      synopsis?: {
+        synopsisDesc?: string;
+        applicantTypes?: { description?: string }[];
+        fundingActivityCategories?: { description?: string }[];
+        fundingInstruments?: { description?: string }[];
+        responseDate?: string;
+        postingDate?: string;
+        archiveDate?: string;
+        awardCeiling?: number;
+        awardFloor?: number;
+        estimatedFunding?: number;
+        expectedNumberOfAwards?: number;
+        agencyName?: string;
+        agencyCode?: string;
+      };
+      opportunityHistoryDetails?: { actionType?: string; actionDate?: string }[];
+      cfdas?: { cfdaNumber?: string; programTitle?: string }[];
+    };
+  };
+  const json = await postJson<Resp>("fetchOpportunity", {
+    opportunityId: args.opportunityId,
+  });
+  if (json.errorcode && json.errorcode !== 0) {
+    throw new Error(`Grants.gov error: ${json.msg ?? "unknown"}`);
+  }
+  const d = json.data ?? {};
+  const s = d.synopsis ?? {};
+  return {
+    id: d.id ?? 0,
+    opportunityNumber: d.opportunityNumber ?? "",
+    title: d.opportunityTitle ?? "",
+    agency: { code: s.agencyCode ?? d.owningAgencyCode, name: s.agencyName },
+    description: s.synopsisDesc ?? d.synopsisDesc ?? "",
+    postingDate: s.postingDate,
+    responseDate: s.responseDate,
+    archiveDate: s.archiveDate,
+    awardCeiling: s.awardCeiling,
+    awardFloor: s.awardFloor,
+    estimatedFunding: s.estimatedFunding,
+    expectedNumberOfAwards: s.expectedNumberOfAwards,
+    applicantTypes: (s.applicantTypes ?? [])
+      .map((a) => a.description)
+      .filter(Boolean) as string[],
+    fundingInstruments: (s.fundingInstruments ?? [])
+      .map((f) => f.description)
+      .filter(Boolean) as string[],
+    fundingCategories: (s.fundingActivityCategories ?? [])
+      .map((f) => f.description)
+      .filter(Boolean) as string[],
+    cfdaPrograms: (d.cfdas ?? []).map((c) => ({
+      number: c.cfdaNumber ?? "",
+      title: c.programTitle ?? "",
+    })),
+  };
+}