@cliwant/mcp-sam-gov 0.2.1 → 0.3.0

package/src/ecfr.ts

@@ -1,127 +1,134 @@
-/**
- * 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;
-}
+/**
+ * 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/.
+ */
+
+import { fetchWithRetry } from "./errors.js";
+import { memoize } from "./cache.js";
+
+const ECFR = "https://www.ecfr.gov/api";
+
+async function fetchJson<T>(url: string): Promise<T> {
+  const r = await fetchWithRetry(
+    url,
+    {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(15_000),
+    },
+    `ecfr:${url.split("/api/")[1] ?? url}`,
+  );
+  return (await r.json()) as T;
+}
+
+export async function listTitles() {
+  // 50 CFR titles change very infrequently. Cache aggressively (5 min).
+  return memoize("ecfr:titles", async () => {
+    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/errors.ts

@@ -0,0 +1,220 @@
+/**
+ * Structured error envelope for every tool response.
+ *
+ * Why this exists
+ * ----------------
+ * Federal APIs fail in 5 distinct ways: rate-limited (429), down
+ * (5xx), schema-drift (200 with unexpected shape), notice-not-found
+ * (404), and transient network. Each has a different retry strategy.
+ * If we just throw, the LLM sees "Tool error: TypeError: x is
+ * undefined" and gives up.
+ *
+ * Every tool should return either:
+ *   { ok: true, data: ... }
+ *   { ok: false, error: { kind, message, retryable, retryAfterSeconds? } }
+ *
+ * The MCP server layer surfaces this as JSON to the calling agent.
+ * The agent can then decide: retry now, retry later, or surface
+ * the error to the user with appropriate framing.
+ */
+
+export type ErrorKind =
+  /** HTTP 429. Retry after `retryAfterSeconds`. */
+  | "rate_limited"
+  /** HTTP 5xx or network error. Likely transient. */
+  | "upstream_unavailable"
+  /** HTTP 404 / empty results. Don't retry. */
+  | "not_found"
+  /** Caller passed bad input (e.g. malformed noticeId). Don't retry. */
+  | "invalid_input"
+  /** API returned 200 but we couldn't parse / shape doesn't match. */
+  | "schema_drift"
+  /** Anything else. Don't retry. */
+  | "unknown";
+
+export type ToolError = {
+  kind: ErrorKind;
+  message: string;
+  /** Whether the agent should retry. Pairs with retryAfterSeconds. */
+  retryable: boolean;
+  /** If rate-limited, advisory wait time. Honors `Retry-After` header. */
+  retryAfterSeconds?: number;
+  /** Echo upstream HTTP status when available — helps debug. */
+  upstreamStatus?: number;
+  /** Endpoint that failed — for ops. */
+  upstreamEndpoint?: string;
+};
+
+export type ToolResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; error: ToolError };
+
+const RATE_LIMIT_DEFAULT_SECONDS = 30;
+
+export class ToolErrorCarrier extends Error {
+  readonly toolError: ToolError;
+  constructor(toolError: ToolError) {
+    super(toolError.message);
+    this.toolError = toolError;
+    this.name = "ToolErrorCarrier";
+  }
+}
+
+/**
+ * Convert a fetch Response into a structured tool error.
+ *
+ * Honors `Retry-After` (both seconds-int and HTTP-date forms).
+ */
+export function errorFromResponse(
+  r: Response,
+  endpoint: string,
+): ToolError {
+  const upstreamStatus = r.status;
+  if (r.status === 429) {
+    const retryAfter = parseRetryAfter(r.headers.get("Retry-After"));
+    return {
+      kind: "rate_limited",
+      message: `Upstream rate-limited (HTTP 429) at ${endpoint}. Retry after ${retryAfter}s.`,
+      retryable: true,
+      retryAfterSeconds: retryAfter,
+      upstreamStatus,
+      upstreamEndpoint: endpoint,
+    };
+  }
+  if (r.status === 404) {
+    return {
+      kind: "not_found",
+      message: `Resource not found at ${endpoint} (HTTP 404).`,
+      retryable: false,
+      upstreamStatus,
+      upstreamEndpoint: endpoint,
+    };
+  }
+  if (r.status >= 500) {
+    return {
+      kind: "upstream_unavailable",
+      message: `Upstream server error (HTTP ${r.status}) at ${endpoint}. Try again later.`,
+      retryable: true,
+      retryAfterSeconds: 60,
+      upstreamStatus,
+      upstreamEndpoint: endpoint,
+    };
+  }
+  if (r.status >= 400) {
+    return {
+      kind: "invalid_input",
+      message: `Bad request (HTTP ${r.status}) at ${endpoint}.`,
+      retryable: false,
+      upstreamStatus,
+      upstreamEndpoint: endpoint,
+    };
+  }
+  return {
+    kind: "unknown",
+    message: `Unexpected status ${r.status} at ${endpoint}.`,
+    retryable: false,
+    upstreamStatus,
+    upstreamEndpoint: endpoint,
+  };
+}
+
+/**
+ * Wrap a fetch + json call in retry-with-backoff for transient errors.
+ *
+ * Strategy: up to 3 attempts. On 429: respect Retry-After up to 60s.
+ * On 5xx: 1s, 2s, 4s exponential. On parse error: no retry (schema
+ * drift — needs human investigation).
+ */
+export async function fetchWithRetry(
+  url: string,
+  init: RequestInit,
+  endpointLabel: string,
+): Promise<Response> {
+  const maxAttempts = 3;
+  let lastErr: ToolError | undefined;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const r = await fetch(url, init);
+      if (r.ok) return r;
+      const err = errorFromResponse(r, endpointLabel);
+      if (!err.retryable || attempt === maxAttempts) {
+        throw new ToolErrorCarrier(err);
+      }
+      lastErr = err;
+      const wait = err.retryAfterSeconds
+        ? Math.min(err.retryAfterSeconds, 60)
+        : Math.pow(2, attempt - 1);
+      await new Promise((res) => setTimeout(res, wait * 1000));
+    } catch (e) {
+      if (e instanceof ToolErrorCarrier) throw e;
+      // Network-level error
+      lastErr = {
+        kind: "upstream_unavailable",
+        message: `Network error reaching ${endpointLabel}: ${(e as Error).message}`,
+        retryable: true,
+        retryAfterSeconds: 30,
+        upstreamEndpoint: endpointLabel,
+      };
+      if (attempt === maxAttempts) {
+        throw new ToolErrorCarrier(lastErr);
+      }
+      await new Promise((res) =>
+        setTimeout(res, Math.pow(2, attempt - 1) * 1000),
+      );
+    }
+  }
+  throw new ToolErrorCarrier(
+    lastErr ?? {
+      kind: "unknown",
+      message: `${endpointLabel} failed after ${maxAttempts} attempts.`,
+      retryable: false,
+      upstreamEndpoint: endpointLabel,
+    },
+  );
+}
+
+function parseRetryAfter(value: string | null): number {
+  if (!value) return RATE_LIMIT_DEFAULT_SECONDS;
+  const asInt = Number.parseInt(value, 10);
+  if (Number.isFinite(asInt)) return asInt;
+  // HTTP-date form
+  const date = Date.parse(value);
+  if (!Number.isNaN(date)) {
+    return Math.max(1, Math.ceil((date - Date.now()) / 1000));
+  }
+  return RATE_LIMIT_DEFAULT_SECONDS;
+}
+
+/**
+ * Convert any thrown error into a serializable ToolError envelope.
+ * Used at the dispatcher boundary — server.ts catches everything
+ * and wraps before returning to the MCP client.
+ */
+export function toToolError(e: unknown, endpointLabel?: string): ToolError {
+  if (e instanceof ToolErrorCarrier) return e.toolError;
+  if (e instanceof Error) {
+    const msg = e.message;
+    // Common fetch timeout signature
+    if (e.name === "TimeoutError" || /timeout|aborted/i.test(msg)) {
+      return {
+        kind: "upstream_unavailable",
+        message: `${endpointLabel ?? "upstream"} timed out: ${msg}`,
+        retryable: true,
+        retryAfterSeconds: 30,
+        upstreamEndpoint: endpointLabel,
+      };
+    }
+    return {
+      kind: "unknown",
+      message: msg,
+      retryable: false,
+      upstreamEndpoint: endpointLabel,
+    };
+  }
+  return {
+    kind: "unknown",
+    message: String(e),
+    retryable: false,
+    upstreamEndpoint: endpointLabel,
+  };
+}