@cyanheads/federal-regulations-mcp-server 0.1.0

package/dist/mcp-server/tools/definitions/list-open-comments.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-open-comments.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/list-open-comments.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/search-rules.tool.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview regulations_search_rules — the 80% entry point. Searches the
+ * Federal Register for proposed rules, final rules, notices, and presidential
+ * documents, filterable by agency, document type, date range, topic, and
+ * open-for-comment window. Keyless (Federal Register API).
+ * @module mcp-server/tools/definitions/search-rules.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const searchRulesTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        PRORULE: "PRORULE";
+        RULE: "RULE";
+        NOTICE: "NOTICE";
+        PRESDOCU: "PRESDOCU";
+    }>>>;
+    agencies: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    published_after: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>;
+    published_before: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>;
+    per_page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>, z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        documentNumber: z.ZodString;
+        title: z.ZodString;
+        type: z.ZodString;
+        abstract: z.ZodNullable<z.ZodString>;
+        publicationDate: z.ZodString;
+        agencies: z.ZodArray<z.ZodString>;
+        docketIds: z.ZodArray<z.ZodString>;
+        regulationIdNumbers: z.ZodArray<z.ZodString>;
+        cfrReferences: z.ZodArray<z.ZodObject<{
+            title: z.ZodNumber;
+            part: z.ZodString;
+        }, z.core.$strip>>;
+        commentsCloseOn: z.ZodNullable<z.ZodString>;
+        effectiveOn: z.ZodNullable<z.ZodString>;
+        htmlUrl: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "no_results";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "Zero matches for the query and filters.";
+    readonly recovery: "Broaden the query, widen the date range, or drop an agency filter and retry.";
+}, {
+    readonly reason: "upstream_unavailable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "Federal Register returned a 5xx, timed out, or served an HTML error page.";
+    readonly recovery: "Retry after a brief wait; the Federal Register API may be momentarily down.";
+}], {
+    readonly totalCount: z.ZodNumber;
+    readonly truncated: z.ZodOptional<z.ZodBoolean>;
+    readonly shown: z.ZodOptional<z.ZodNumber>;
+    readonly notice: z.ZodOptional<z.ZodString>;
+}>;
+//# sourceMappingURL=search-rules.tool.d.ts.map

package/dist/mcp-server/tools/definitions/search-rules.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-rules.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-rules.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAOjE,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqM1B,CAAC"}

package/dist/mcp-server/tools/definitions/search-rules.tool.js

@@ -0,0 +1,185 @@
+/**
+ * @fileoverview regulations_search_rules — the 80% entry point. Searches the
+ * Federal Register for proposed rules, final rules, notices, and presidential
+ * documents, filterable by agency, document type, date range, topic, and
+ * open-for-comment window. Keyless (Federal Register API).
+ * @module mcp-server/tools/definitions/search-rules.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getFederalRegisterService } from '../../../services/federal-register/federal-register-service.js';
+import { escapePipes } from './format-utils.js';
+/** Above this match count the FR's 50-page navigation ceiling (5,000 records) bites. */
+const FR_NAV_CEILING = 5000;
+export const searchRulesTool = tool('regulations_search_rules', {
+    title: 'regulations_search_rules',
+    description: 'Search the Federal Register — the daily journal of US proposed rules, final rules, notices, and presidential documents (1994–present) — filtering by full-text query, document type, agency slug, publication date range, and whether the rule is open for comment. The primary discovery entry point: results carry the document number (open with regulations_get_document), docket IDs, RINs, and affected CFR parts that chain into the comment and codified-text tools. The Federal Register caps navigation at 50 pages and the match count at 10,000; when a result set is larger, narrow with published_after/published_before rather than paging deeper.',
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    input: z.object({
+        query: z
+            .string()
+            .optional()
+            .describe('Full-text search across document title and body. Omit to browse by filters alone (e.g. all EPA proposed rules in a date range).'),
+        type: z
+            .array(z.enum(['PRORULE', 'RULE', 'NOTICE', 'PRESDOCU']))
+            .optional()
+            .describe('Document types to include. PRORULE=Proposed Rule, RULE=Final Rule, NOTICE=Notice, PRESDOCU=Presidential Document. Omit for all types.'),
+        agencies: z
+            .array(z.string())
+            .optional()
+            .describe('Filter to one or more agencies by Federal Register agency slug (e.g. "environmental-protection-agency", "securities-and-exchange-commission"). Slugs are the kebab-case agency name; if unsure, search by query and read the agency slugs off the results.'),
+        published_after: z
+            .union([
+            z.literal(''),
+            z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .describe('ISO 8601 date (YYYY-MM-DD).'),
+        ])
+            .optional()
+            .describe('Earliest publication date, ISO 8601 (YYYY-MM-DD). Combine with published_before to window large result sets — the FR caps navigation at 50 pages.'),
+        published_before: z
+            .union([
+            z.literal(''),
+            z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .describe('ISO 8601 date (YYYY-MM-DD).'),
+        ])
+            .optional()
+            .describe('Latest publication date, ISO 8601 (YYYY-MM-DD).'),
+        per_page: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .default(20)
+            .describe('Results per page (1–100, default 20).'),
+        page: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .default(1)
+            .describe('Page number (1–50, default 1). The FR API caps total_pages at 50 — with per_page=100 this allows navigating up to 5,000 results. To reach beyond that window, narrow with published_after/published_before rather than paging deeper.'),
+    }),
+    output: z.object({
+        results: z
+            .array(z
+            .object({
+            documentNumber: z
+                .string()
+                .describe('Federal Register document number — chains into regulations_get_document.'),
+            title: z.string().describe('Document title.'),
+            type: z
+                .string()
+                .describe('Document type: Proposed Rule, Final Rule, Notice, or Presidential Document.'),
+            abstract: z.string().nullable().describe('Abstract summary, or null when absent.'),
+            publicationDate: z.string().describe('Publication date (ISO 8601).'),
+            agencies: z.array(z.string()).describe('Issuing agency names.'),
+            docketIds: z
+                .array(z.string())
+                .describe('Docket IDs — chain into regulations_get_docket / regulations_find_comments.'),
+            regulationIdNumbers: z
+                .array(z.string())
+                .describe('Regulation Identifier Number(s) (RIN).'),
+            cfrReferences: z
+                .array(z
+                .object({
+                title: z.number().describe('CFR title number.'),
+                part: z.string().describe('CFR part.'),
+            })
+                .describe('A single affected CFR title + part.'))
+                .describe('Affected CFR parts — chain into regulations_get_cfr_section.'),
+            commentsCloseOn: z
+                .string()
+                .nullable()
+                .describe('Comment-period close date (ISO 8601); when set, still open for comment.'),
+            effectiveOn: z.string().nullable().describe('Effective date (ISO 8601), or null.'),
+            htmlUrl: z.string().describe('Federal Register web URL for the document.'),
+        })
+            .describe('One matching Federal Register document.'))
+            .describe('Matching Federal Register documents (this page).'),
+    }),
+    enrichment: {
+        totalCount: z
+            .number()
+            .describe('Total matches before pagination (FR count; capped at 10,000 by the API window).'),
+        truncated: z
+            .boolean()
+            .optional()
+            .describe('True when matches exceed the FR 50-page (5,000-record) navigation ceiling.'),
+        shown: z.number().optional().describe('Results returned on this page.'),
+        notice: z
+            .string()
+            .optional()
+            .describe('Guidance when nothing matched or when results were truncated.'),
+    },
+    errors: [
+        {
+            reason: 'no_results',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'Zero matches for the query and filters.',
+            recovery: 'Broaden the query, widen the date range, or drop an agency filter and retry.',
+        },
+        {
+            reason: 'upstream_unavailable',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'Federal Register returned a 5xx, timed out, or served an HTML error page.',
+            recovery: 'Retry after a brief wait; the Federal Register API may be momentarily down.',
+        },
+    ],
+    async handler(input, ctx) {
+        const service = getFederalRegisterService();
+        const result = await service.search({
+            query: input.query || undefined,
+            types: input.type,
+            agencies: input.agencies?.length ? input.agencies : undefined,
+            publishedAfter: input.published_after || undefined,
+            publishedBefore: input.published_before || undefined,
+            perPage: input.per_page,
+            page: input.page,
+        }, ctx);
+        ctx.enrich.total(result.totalCount);
+        if (result.results.length === 0) {
+            ctx.enrich.notice('No Federal Register documents matched. Broaden the query, widen the date range, or drop an agency filter.');
+            return { results: [] };
+        }
+        if (result.totalCount > FR_NAV_CEILING) {
+            ctx.enrich.truncated({
+                shown: result.results.length,
+                cap: FR_NAV_CEILING,
+                guidance: `${result.totalCount} matches exceed the Federal Register's 5,000-record navigation ceiling. Narrow with published_after / published_before to reach the rest.`,
+            });
+        }
+        return { results: result.results };
+    },
+    format: (result) => {
+        const lines = [
+            '| FR Number | Type | Title | Agency | Published | Comments Close |',
+            '|---|---|---|---|---|---|',
+        ];
+        for (const r of result.results) {
+            const agency = r.agencies[0] ?? '—';
+            const cite = r.cfrReferences.map((c) => `${c.title} CFR ${c.part}`).join(', ');
+            lines.push(`| ${r.documentNumber} | ${r.type} | ${escapePipes(r.title)} | ${escapePipes(agency)} | ${r.publicationDate} | ${r.commentsCloseOn ?? '—'} |`);
+            const tail = [];
+            if (r.docketIds.length)
+                tail.push(`dockets: ${r.docketIds.join(', ')}`);
+            if (cite)
+                tail.push(`CFR: ${cite}`);
+            if (r.regulationIdNumbers.length)
+                tail.push(`RIN: ${r.regulationIdNumbers.join(', ')}`);
+            if (r.abstract)
+                tail.push(`abstract: ${r.abstract}`);
+            if (r.effectiveOn)
+                tail.push(`effective: ${r.effectiveOn}`);
+            tail.push(r.htmlUrl);
+            lines.push(`| | | ${escapePipes(tail.join(' · '))} | | | |`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=search-rules.tool.js.map

package/dist/mcp-server/tools/definitions/search-rules.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-rules.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search-rules.tool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,yBAAyB,EAAE,MAAM,yDAAyD,CAAC;AACpG,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,wFAAwF;AACxF,MAAM,cAAc,GAAG,IAAI,CAAC;AAE5B,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC,0BAA0B,EAAE;IAC9D,KAAK,EAAE,0BAA0B;IACjC,WAAW,EACT,moBAAmoB;IACroB,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;IACxD,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,iIAAiI,CAClI;QACH,IAAI,EAAE,CAAC;aACJ,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC;aACxD,QAAQ,EAAE;aACV,QAAQ,CACP,uIAAuI,CACxI;QACH,QAAQ,EAAE,CAAC;aACR,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;aACjB,QAAQ,EAAE;aACV,QAAQ,CACP,4PAA4P,CAC7P;QACH,eAAe,EAAE,CAAC;aACf,KAAK,CAAC;YACL,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;YACb,CAAC;iBACE,MAAM,EAAE;iBACR,KAAK,CAAC,qBAAqB,CAAC;iBAC5B,QAAQ,CAAC,6BAA6B,CAAC;SAC3C,CAAC;aACD,QAAQ,EAAE;aACV,QAAQ,CACP,mJAAmJ,CACpJ;QACH,gBAAgB,EAAE,CAAC;aAChB,KAAK,CAAC;YACL,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;YACb,CAAC;iBACE,MAAM,EAAE;iBACR,KAAK,CAAC,qBAAqB,CAAC;iBAC5B,QAAQ,CAAC,6BAA6B,CAAC;SAC3C,CAAC;aACD,QAAQ,EAAE;aACV,QAAQ,CAAC,iDAAiD,CAAC;QAC9D,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,GAAG,EAAE;aACL,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,GAAG,CAAC;aACR,QAAQ,EAAE;aACV,OAAO,CAAC,EAAE,CAAC;aACX,QAAQ,CAAC,uCAAuC,CAAC;QACpD,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,GAAG,EAAE;aACL,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,EAAE,CAAC;aACP,QAAQ,EAAE;aACV,OAAO,CAAC,CAAC,CAAC;aACV,QAAQ,CACP,uOAAuO,CACxO;KACJ,CAAC;IACF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,OAAO,EAAE,CAAC;aACP,KAAK,CACJ,CAAC;aACE,MAAM,CAAC;YACN,cAAc,EAAE,CAAC;iBACd,MAAM,EAAE;iBACR,QAAQ,CAAC,0EAA0E,CAAC;YACvF,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC;YAC7C,IAAI,EAAE,CAAC;iBACJ,MAAM,EAAE;iBACR,QAAQ,CACP,6EAA6E,CAC9E;YACH,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wCAAwC,CAAC;YAClF,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;YACpE,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,uBAAuB,CAAC;YAC/D,SAAS,EAAE,CAAC;iBACT,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;iBACjB,QAAQ,CACP,6EAA6E,CAC9E;YACH,mBAAmB,EAAE,CAAC;iBACnB,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;iBACjB,QAAQ,CAAC,wCAAwC,CAAC;YACrD,aAAa,EAAE,CAAC;iBACb,KAAK,CACJ,CAAC;iBACE,MAAM,CAAC;gBACN,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC;gBAC/C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;aACvC,CAAC;iBACD,QAAQ,CAAC,qCAAqC,CAAC,CACnD;iBACA,QAAQ,CAAC,8DAA8D,CAAC;YAC3E,eAAe,EAAE,CAAC;iBACf,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,yEAAyE,CAAC;YACtF,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;YAClF,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;SAC3E,CAAC;aACD,QAAQ,CAAC,yCAAyC,CAAC,CACvD;aACA,QAAQ,CAAC,kDAAkD,CAAC;KAChE,CAAC;IACF,UAAU,EAAE;QACV,UAAU,EAAE,CAAC;aACV,MAAM,EAAE;aACR,QAAQ,CAAC,iFAAiF,CAAC;QAC9F,SAAS,EAAE,CAAC;aACT,OAAO,EAAE;aACT,QAAQ,EAAE;aACV,QAAQ,CAAC,4EAA4E,CAAC;QACzF,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;QACvE,MAAM,EAAE,CAAC;aACN,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,+DAA+D,CAAC;KAC7E;IACD,MAAM,EAAE;QACN;YACE,MAAM,EAAE,YAAY;YACpB,IAAI,EAAE,gBAAgB,CAAC,QAAQ;YAC/B,IAAI,EAAE,yCAAyC;YAC/C,QAAQ,EAAE,8EAA8E;SACzF;QACD;YACE,MAAM,EAAE,sBAAsB;YAC9B,IAAI,EAAE,gBAAgB,CAAC,kBAAkB;YACzC,IAAI,EAAE,2EAA2E;YACjF,QAAQ,EAAE,6EAA6E;SACxF;KACF;IAED,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,MAAM,OAAO,GAAG,yBAAyB,EAAE,CAAC;QAC5C,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,CACjC;YACE,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,SAAS;YAC/B,KAAK,EAAE,KAAK,CAAC,IAAI;YACjB,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;YAC7D,cAAc,EAAE,KAAK,CAAC,eAAe,IAAI,SAAS;YAClD,eAAe,EAAE,KAAK,CAAC,gBAAgB,IAAI,SAAS;YACpD,OAAO,EAAE,KAAK,CAAC,QAAQ;YACvB,IAAI,EAAE,KAAK,CAAC,IAAI;SACjB,EACD,GAAG,CACJ,CAAC;QAEF,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAEpC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChC,GAAG,CAAC,MAAM,CAAC,MAAM,CACf,2GAA2G,CAC5G,CAAC;YACF,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QACzB,CAAC;QAED,IAAI,MAAM,CAAC,UAAU,GAAG,cAAc,EAAE,CAAC;YACvC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC;gBACnB,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM;gBAC5B,GAAG,EAAE,cAAc;gBACnB,QAAQ,EAAE,GAAG,MAAM,CAAC,UAAU,2IAA2I;aAC1K,CAAC,CAAC;QACL,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;IACrC,CAAC;IAED,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE;QACjB,MAAM,KAAK,GAAG;YACZ,oEAAoE;YACpE,2BAA2B;SAC5B,CAAC;QACF,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YAC/B,MAAM,MAAM,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;YACpC,MAAM,IAAI,GAAG,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC/E,KAAK,CAAC,IAAI,CACR,KAAK,CAAC,CAAC,cAAc,MAAM,CAAC,CAAC,IAAI,MAAM,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,eAAe,MAAM,CAAC,CAAC,eAAe,IAAI,GAAG,IAAI,CAC9I,CAAC;YACF,MAAM,IAAI,GAAa,EAAE,CAAC;YAC1B,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM;gBAAE,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACxE,IAAI,IAAI;gBAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;YACpC,IAAI,CAAC,CAAC,mBAAmB,CAAC,MAAM;gBAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACxF,IAAI,CAAC,CAAC,QAAQ;gBAAE,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;YACrD,IAAI,CAAC,CAAC,WAAW;gBAAE,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;YAC5D,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YACrB,KAAK,CAAC,IAAI,CAAC,SAAS,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;CACF,CAAC,CAAC"}

package/dist/services/ecfr/ecfr-service.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview EcfrService — keyless client for the eCFR API (ecfr.gov/api):
+ * the versioner (titles, structure, ancestry, full-text XML) and the search API.
+ * Backs `browse_cfr` and `get_cfr_section`, and supplies the title list + XML the
+ * eCFR mirror ingester walks. Section XML is parsed by `./xml.ts`. Retry wraps the
+ * full fetch + parse pipeline; HTML error pages become transient errors.
+ * @module services/ecfr/ecfr-service
+ */
+import type { Context } from '@cyanheads/mcp-ts-core';
+import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
+import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
+import type { EcfrSearchResponse, EcfrSectionResult, EcfrStructureNode, EcfrTitle } from './types.js';
+/** eCFR retains point-in-time versions back to roughly this date. */
+export declare const ECFR_EARLIEST_DATE = "2017-01-01";
+export declare class EcfrService {
+    private readonly baseUrl;
+    constructor(_config: AppConfig, _storage: StorageService);
+    /** List the CFR titles (`/versioner/v1/titles.json`). */
+    listTitles(ctx: Context): Promise<EcfrTitle[]>;
+    /**
+     * The latest issue date for a title — the point-in-time the versioner serves
+     * as "current". Falls back to today when the title can't be resolved.
+     */
+    latestIssueDate(title: number, ctx: Context): Promise<string>;
+    /**
+     * Browse a title's structure tree. With no `part`, returns the title's direct
+     * children; with a `part`, narrows to that part's subtree (flattened to one
+     * level of nodes for the agent). Each citable node carries an assembled cite.
+     */
+    browseStructure(title: number, part: string | undefined, date: string, ctx: Context): Promise<EcfrStructureNode[]>;
+    /** List all titles as structure nodes (the top of the browse tree). */
+    listTitleNodes(ctx: Context): Promise<EcfrStructureNode[]>;
+    /**
+     * Fetch codified text for a section (or whole part) from the versioner
+     * `/full/{date}/title-{n}.xml` endpoint, parsed into plain text.
+     */
+    getSectionText(title: number, part: string, section: string | undefined, date: string, ctx: Context): Promise<EcfrSectionResult>;
+    /**
+     * Fetch a whole title's full XML (no part/section filter) — the bulk payload
+     * the mirror ingester walks. Long timeout: Title 40 alone is ~150 MB.
+     */
+    fetchFullTitleXml(title: number, date: string, ctx: Context): Promise<string>;
+    /** Resolve a cite's full hierarchy path via the ancestry endpoint. */
+    hierarchyPath(title: number, part: string, section: string | undefined, date: string, ctx: Context): Promise<string>;
+    /** Full-text search the live eCFR (`/search/v1/results`). */
+    search(query: string, title: number | undefined, perPage: number, ctx: Context): Promise<EcfrSearchResponse>;
+    private fetchJson;
+    private fetchXml;
+}
+/** Today's date as YYYY-MM-DD (UTC). */
+export declare function today(): string;
+export declare function initEcfrService(config: AppConfig, storage: StorageService): void;
+export declare function getEcfrService(): EcfrService;
+//# sourceMappingURL=ecfr-service.d.ts.map

package/dist/services/ecfr/ecfr-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ecfr-service.d.ts","sourceRoot":"","sources":["../../../src/services/ecfr/ecfr-service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAO/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAIrE,OAAO,KAAK,EAEV,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,SAAS,EAKV,MAAM,YAAY,CAAC;AASpB,qEAAqE;AACrE,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAS/C,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc;IAIxD,yDAAyD;IACnD,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAmBpD;;;OAGG;IACG,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAMnE;;;;OAIG;IACG,eAAe,CACnB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAoB/B,uEAAuE;IACjE,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAYhE;;;OAGG;IACG,cAAc,CAClB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,iBAAiB,CAAC;IA2D7B;;;OAGG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAK7E,sEAAsE;IAChE,aAAa,CACjB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,MAAM,CAAC;IAqBlB,6DAA6D;IACvD,MAAM,CACV,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,kBAAkB,CAAC;IAc9B,OAAO,CAAC,SAAS;IAiBjB,OAAO,CAAC,QAAQ;CAuBjB;AA4ED,wCAAwC;AACxC,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAMD,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAEhF;AAED,wBAAgB,cAAc,IAAI,WAAW,CAK5C"}

package/dist/services/ecfr/ecfr-service.js

@@ -0,0 +1,303 @@
+/**
+ * @fileoverview EcfrService — keyless client for the eCFR API (ecfr.gov/api):
+ * the versioner (titles, structure, ancestry, full-text XML) and the search API.
+ * Backs `browse_cfr` and `get_cfr_section`, and supplies the title list + XML the
+ * eCFR mirror ingester walks. Section XML is parsed by `./xml.ts`. Retry wraps the
+ * full fetch + parse pipeline; HTML error pages become transient errors.
+ * @module services/ecfr/ecfr-service
+ */
+import { JsonRpcErrorCode, McpError, notFound, serviceUnavailable, } from '@cyanheads/mcp-ts-core/errors';
+import { fetchWithTimeout, withRetry } from '@cyanheads/mcp-ts-core/utils';
+import { getServerConfig } from '../../config/server-config.js';
+import { toRequestContext } from '../../services/request-context.js';
+import { parseSections } from './xml.js';
+const TIMEOUT_MS = 20_000;
+const XML_TIMEOUT_MS = 60_000;
+/** Bulk whole-title XML can be ~150 MB (Title 40); allow up to 10 minutes. */
+const FULL_TITLE_TIMEOUT_MS = 600_000;
+const BASE_DELAY_MS = 400;
+/** eCFR retains point-in-time versions back to roughly this date. */
+export const ECFR_EARLIEST_DATE = '2017-01-01';
+function looksLikeHtml(text) {
+    return /^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text);
+}
+/** Node types that carry a citable identifier into get_cfr_section. */
+const CITABLE_TYPES = new Set(['part', 'section']);
+export class EcfrService {
+    baseUrl;
+    constructor(_config, _storage) {
+        this.baseUrl = getServerConfig().ecfrBaseUrl.replace(/\/$/, '');
+    }
+    /** List the CFR titles (`/versioner/v1/titles.json`). */
+    async listTitles(ctx) {
+        const url = `${this.baseUrl}/versioner/v1/titles.json`;
+        const raw = await this.fetchJson(url, ctx, 'EcfrService.listTitles');
+        return (raw.titles ?? [])
+            .filter((t) => typeof t.number === 'number')
+            .map((t) => ({
+            number: t.number,
+            name: t.name ?? `Title ${t.number}`,
+            latestAmendedOn: t.latest_amended_on ?? null,
+            latestIssueDate: t.latest_issue_date ?? null,
+            upToDateAsOf: t.up_to_date_as_of ?? null,
+            reserved: t.reserved ?? false,
+        }));
+    }
+    /**
+     * The latest issue date for a title — the point-in-time the versioner serves
+     * as "current". Falls back to today when the title can't be resolved.
+     */
+    async latestIssueDate(title, ctx) {
+        const titles = await this.listTitles(ctx);
+        const match = titles.find((t) => t.number === title);
+        return match?.latestIssueDate ?? match?.upToDateAsOf ?? today();
+    }
+    /**
+     * Browse a title's structure tree. With no `part`, returns the title's direct
+     * children; with a `part`, narrows to that part's subtree (flattened to one
+     * level of nodes for the agent). Each citable node carries an assembled cite.
+     */
+    async browseStructure(title, part, date, ctx) {
+        const url = `${this.baseUrl}/versioner/v1/structure/${date}/title-${title}.json`;
+        const root = await this.fetchJson(url, ctx, 'EcfrService.browseStructure');
+        const partNode = part ? findPartNode(root, part) : root;
+        if (!partNode) {
+            throw notFound(`Part ${part} not found in CFR title ${title} as of ${date}.`, {
+                title,
+                part,
+                date,
+            });
+        }
+        const children = partNode.children ?? [];
+        return children.map((child) => normalizeNode(child, title));
+    }
+    /** List all titles as structure nodes (the top of the browse tree). */
+    async listTitleNodes(ctx) {
+        const titles = await this.listTitles(ctx);
+        return titles.map((t) => ({
+            type: 'title',
+            identifier: String(t.number),
+            label: `Title ${t.number}—${t.name}`,
+            description: t.name,
+            reserved: t.reserved,
+            cfrCite: null,
+        }));
+    }
+    /**
+     * Fetch codified text for a section (or whole part) from the versioner
+     * `/full/{date}/title-{n}.xml` endpoint, parsed into plain text.
+     */
+    async getSectionText(title, part, section, date, ctx) {
+        const search = new URLSearchParams({ part });
+        if (section)
+            search.set('section', section);
+        const url = `${this.baseUrl}/versioner/v1/full/${date}/title-${title}.xml?${search.toString()}`;
+        const cite = `${title} CFR ${part}${section ? ` § ${section}` : ''}`;
+        let xml;
+        try {
+            xml = await this.fetchXml(url, ctx, 'EcfrService.getSectionText');
+        }
+        catch (err) {
+            // The versioner 404s for a nonexistent part/section (or a date past the
+            // title's latest issue). Translate that into an actionable not_found so the
+            // tool's contract recovery surfaces, rather than a raw "Fetch failed 404".
+            if (err instanceof McpError && err.code === JsonRpcErrorCode.NotFound) {
+                throw notFound(`No codified text found for ${cite} as of ${date}.`, {
+                    title,
+                    part,
+                    section: section ?? null,
+                    date,
+                });
+            }
+            throw err;
+        }
+        const sections = parseSections(xml);
+        if (sections.length === 0) {
+            throw notFound(`No codified text found for ${cite} as of ${date}.`, {
+                title,
+                part,
+                section: section ?? null,
+                date,
+            });
+        }
+        if (section) {
+            // sections is non-empty (guarded above), so [0] is defined when find misses.
+            const found = sections.find((s) => s.section === section);
+            const match = found ?? sections[0];
+            return {
+                title,
+                part,
+                section,
+                heading: match?.heading ?? `§ ${section}`,
+                date,
+                bodyText: match?.bodyText ?? '',
+            };
+        }
+        return {
+            title,
+            part,
+            section: null,
+            heading: `Part ${part}`,
+            date,
+            bodyText: sections.map((s) => `${s.heading}\n${s.bodyText}`).join('\n\n'),
+            sections,
+        };
+    }
+    /**
+     * Fetch a whole title's full XML (no part/section filter) — the bulk payload
+     * the mirror ingester walks. Long timeout: Title 40 alone is ~150 MB.
+     */
+    fetchFullTitleXml(title, date, ctx) {
+        const url = `${this.baseUrl}/versioner/v1/full/${date}/title-${title}.xml`;
+        return this.fetchXml(url, ctx, 'EcfrService.fetchFullTitleXml', FULL_TITLE_TIMEOUT_MS);
+    }
+    /** Resolve a cite's full hierarchy path via the ancestry endpoint. */
+    async hierarchyPath(title, part, section, date, ctx) {
+        const search = new URLSearchParams({ part });
+        if (section)
+            search.set('section', section);
+        const url = `${this.baseUrl}/versioner/v1/ancestry/${date}/title-${title}.json?${search.toString()}`;
+        try {
+            const raw = await this.fetchJson(url, ctx, 'EcfrService.hierarchyPath');
+            const ancestors = raw.ancestors ?? [];
+            const parts = ancestors
+                .map((a) => labelForAncestor(a))
+                .filter((s) => s !== null);
+            return parts.length > 0 ? parts.join(' › ') : `Title ${title}`;
+        }
+        catch {
+            // Hierarchy is a nicety; never fail the whole read because ancestry 404s.
+            return `Title ${title}`;
+        }
+    }
+    /** Full-text search the live eCFR (`/search/v1/results`). */
+    async search(query, title, perPage, ctx) {
+        const search = new URLSearchParams({
+            query,
+            per_page: String(perPage),
+        });
+        if (typeof title === 'number')
+            search.set('conditions[title]', String(title));
+        const url = `${this.baseUrl}/search/v1/results?${search.toString()}`;
+        const raw = await this.fetchJson(url, ctx, 'EcfrService.search');
+        return {
+            totalCount: raw.meta?.total_count ?? (raw.results ?? []).length,
+            results: (raw.results ?? []).map((r) => normalizeSearchHit(r)),
+        };
+    }
+    fetchJson(url, ctx, operation) {
+        const reqCtx = toRequestContext(ctx, operation);
+        return withRetry(async () => {
+            const response = await fetchWithTimeout(url, TIMEOUT_MS, reqCtx, { signal: ctx.signal });
+            const text = await response.text();
+            if (looksLikeHtml(text)) {
+                throw serviceUnavailable('eCFR returned an HTML error page instead of JSON — likely momentarily unavailable.');
+            }
+            return JSON.parse(text);
+        }, { operation, context: reqCtx, baseDelayMs: BASE_DELAY_MS, signal: ctx.signal });
+    }
+    fetchXml(url, ctx, operation, timeoutMs = XML_TIMEOUT_MS) {
+        const reqCtx = toRequestContext(ctx, operation);
+        return withRetry(async () => {
+            const response = await fetchWithTimeout(url, timeoutMs, reqCtx, {
+                signal: ctx.signal,
+            });
+            const text = await response.text();
+            if (looksLikeHtml(text)) {
+                throw serviceUnavailable('eCFR returned an HTML error page instead of XML — likely momentarily unavailable.');
+            }
+            return text;
+        }, { operation, context: reqCtx, baseDelayMs: BASE_DELAY_MS, signal: ctx.signal });
+    }
+}
+/** Build a `${title} CFR ${identifier}` cite for citable node types. */
+function buildCite(node, title) {
+    if (!node.type || !CITABLE_TYPES.has(node.type) || !node.identifier)
+        return null;
+    return `${title} CFR ${node.identifier}`;
+}
+function normalizeNode(node, title) {
+    return {
+        type: node.type ?? 'unknown',
+        identifier: node.identifier ?? '',
+        label: node.label ?? node.identifier ?? '',
+        description: node.label_description ?? null,
+        reserved: node.reserved ?? false,
+        cfrCite: buildCite(node, title),
+    };
+}
+/** Depth-first search for a part node by identifier within a structure tree. */
+function findPartNode(root, part) {
+    if (root.type === 'part' && root.identifier === part)
+        return root;
+    for (const child of root.children ?? []) {
+        const found = findPartNode(child, part);
+        if (found)
+            return found;
+    }
+    return null;
+}
+function labelForAncestor(node) {
+    if (!node.type || !node.identifier)
+        return null;
+    const typeLabel = node.type.charAt(0).toUpperCase() + node.type.slice(1);
+    if (node.type === 'section')
+        return `§ ${node.identifier}`;
+    return `${typeLabel} ${node.identifier}`;
+}
+/**
+ * Strip HTML tags and collapse whitespace. The eCFR search API wraps matched
+ * terms in `<strong>` in both `full_text_excerpt` and the `headings.*` values;
+ * those tags must not leak into the agent-facing excerpt or heading.
+ */
+function stripSearchHtml(text) {
+    return text
+        .replace(/<[^>]+>/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function normalizeSearchHit(r) {
+    const h = r.hierarchy ?? {};
+    const headings = r.hierarchy_headings ?? {};
+    const title = typeof h.title === 'number' ? h.title : Number.parseInt(String(h.title ?? '0'), 10);
+    const part = h.part ?? '';
+    const section = h.section ?? null;
+    const pathSegments = [];
+    if (h.title)
+        pathSegments.push(`Title ${h.title}`);
+    if (headings.chapter)
+        pathSegments.push(stripSearchHtml(headings.chapter));
+    if (headings.subchapter)
+        pathSegments.push(stripSearchHtml(headings.subchapter));
+    if (headings.part)
+        pathSegments.push(stripSearchHtml(headings.part));
+    if (section)
+        pathSegments.push(`§ ${section}`);
+    const rawHeading = headings.section ?? headings.part ?? r.headings?.section ?? '(untitled)';
+    const cfrCite = section ? `${title} CFR ${section}` : `${title} CFR ${part}`;
+    return {
+        title: Number.isNaN(title) ? 0 : title,
+        part,
+        section,
+        heading: stripSearchHtml(rawHeading),
+        hierarchyPath: pathSegments.join(' › '),
+        excerpt: stripSearchHtml(r.full_text_excerpt ?? ''),
+        cfrCite,
+    };
+}
+/** Today's date as YYYY-MM-DD (UTC). */
+export function today() {
+    return new Date().toISOString().slice(0, 10);
+}
+// --- Init/accessor pattern ---
+let _service;
+export function initEcfrService(config, storage) {
+    _service = new EcfrService(config, storage);
+}
+export function getEcfrService() {
+    if (!_service) {
+        throw new Error('EcfrService not initialized — call initEcfrService() in setup()');
+    }
+    return _service;
+}
+//# sourceMappingURL=ecfr-service.js.map