ecfr_search

Instructions

Implementation Reference

• src/ecfr.ts:53-107 (handler)

  The `search` function that executes the ecfr_search tool logic. Makes a request to eCFR /search/v1/results API with query, optional titleNumber (via hierarchy[title]), and perPage, then maps results to include type, hierarchy info, excerpt, score, and ecfrUrl.

  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 ?? "",
      })),
    };
  }

• src/server.ts:239-248 (schema)

  Zod schema `EcfrSearchInput` defining validation for the tool: query (required string), titleNumber (optional number 1-50), perPage (optional number 1-20).

  const EcfrSearchInput = z.object({
    query: z.string(),
    titleNumber: z
      .number()
      .optional()
      .describe(
        "CFR title (1-50). e.g. 48 = FAR (Federal Acquisition Regulation), 2 = Federal financial assistance.",
      ),
    perPage: z.number().min(1).max(20).optional(),
  });

• src/server.ts:492-498 (registration)

  Tool registration in the MCP server tool list: name 'ecfr_search', description explaining CFR search use cases, inputSchema referencing EcfrSearchInput.

  // ━━━ eCFR (2) ━━━
  {
    name: "ecfr_search",
    description:
      "Full-text search across the entire CFR (Code of Federal Regulations). Use for compliance questions — pass titleNumber=48 for FAR (Federal Acquisition Regulation), titleNumber=2 for federal financial assistance, etc. Returns excerpt + section path + ecfrUrl.",
    inputSchema: EcfrSearchInput,
  },

• src/server.ts:779-780 (registration)

  Case handler in the tool dispatch switch statement that routes 'ecfr_search' to ecfr.search() after parsing input via EcfrSearchInput.parse(args).

  case "ecfr_search":
    return await ecfr.search(EcfrSearchInput.parse(args));

• src/ecfr.ts:109-127 (helper)

  Helper functions `stripHtml` (removes HTML tags) and `buildEcfrUrl` (constructs stable ecfr.gov URL from hierarchy) used by the search handler.

  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;
  }