@cyanheads/federal-regulations-mcp-server 0.1.0

package/dist/mcp-server/tools/definitions/browse-cfr.tool.js

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview regulations_browse_cfr — navigate the CFR hierarchy (structure
+ * mode) or full-text-search the codified CFR (search mode) via eCFR. Search runs
+ * against the local mirror's FTS5 index when ready, falling back to the live eCFR
+ * search API on a cold deploy. Keyless. Feeds regulations_get_cfr_section.
+ * @module mcp-server/tools/definitions/browse-cfr.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getEcfrService, today } from '../../../services/ecfr/ecfr-service.js';
+import { mirrorReady, mirrorSearch } from '../../../services/ecfr-mirror/ecfr-mirror.js';
+const structureNode = z
+    .object({
+    type: z
+        .string()
+        .describe('Node type: title, chapter, subchapter, subpart, part, section, appendix, subject_group, or other (treat unknown types as passthrough).'),
+    identifier: z.string().describe('Node identifier (e.g. "40", "I", "50", "50.1").'),
+    label: z.string().describe('Human-readable label.'),
+    description: z.string().nullable().describe('Label description, or null.'),
+    reserved: z.boolean().describe('True when the node is reserved/empty.'),
+    cfrCite: z
+        .string()
+        .nullable()
+        .describe('Assembled cite for a part/section → regulations_get_cfr_section; null otherwise.'),
+})
+    .describe('One hierarchy node.');
+const searchHit = z
+    .object({
+    title: z.number().describe('CFR title number.'),
+    part: z.string().describe('CFR part.'),
+    section: z.string().nullable().describe('Section identifier, or null.'),
+    heading: z.string().describe('Section/part heading.'),
+    hierarchyPath: z.string().describe('Human-readable hierarchy path.'),
+    excerpt: z.string().describe('Matched text snippet.'),
+    cfrCite: z.string().describe('Assembled cite → regulations_get_cfr_section.'),
+})
+    .describe('One matching CFR section.');
+export const browseCfrTool = tool('regulations_browse_cfr', {
+    title: 'regulations_browse_cfr',
+    description: 'Explore the codified Code of Federal Regulations via eCFR in two modes. "structure" walks the CFR hierarchy (all 50 titles, or one title\'s chapters → parts → sections) to discover a cite when the exact citation is unknown. "search" runs a full-text query across the codified CFR and returns matching sections with their hierarchy path and a snippet. Both modes feed regulations_get_cfr_section. The source (mirror or live) is reported on each search result.',
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    input: z.object({
+        mode: z
+            .enum(['structure', 'search'])
+            .describe('"structure": browse the CFR tree (titles, or one title\'s chapters/parts/sections) to find a cite. "search": full-text search the codified CFR for sections matching a phrase.'),
+        title: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe('CFR title number (1–50). Structure mode: omit to list all 50 titles, or provide to expand one title. Search mode: optional filter to restrict to one title.'),
+        part: z
+            .string()
+            .optional()
+            .describe("CFR part within the title (structure mode, optional) — narrows the returned tree to one part's sections. Parts can be alphanumeric."),
+        query: z
+            .union([z.literal(''), z.string().min(2).describe('Search phrase, at least 2 characters.')])
+            .optional()
+            .describe('Full-text search phrase (search mode, required in that mode). Ignored in structure mode.'),
+        date: z
+            .union([
+            z.literal(''),
+            z
+                .string()
+                .regex(/^\d{4}-\d{2}-\d{2}$/)
+                .describe('ISO 8601 date (YYYY-MM-DD).'),
+        ])
+            .optional()
+            .describe('Point-in-time date, ISO 8601 (YYYY-MM-DD). Defaults to current. Structure mode uses this date for historical hierarchy; in search mode, a past date enables point-in-time search.'),
+        per_page: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .default(20)
+            .describe('Results per page in search mode (1–50, default 20). Ignored in structure mode.'),
+    }),
+    output: z.object({
+        mode: z.enum(['structure', 'search']).describe('Which mode produced this result.'),
+        date: z.string().optional().describe('Resolved point-in-time date (structure mode).'),
+        nodes: z
+            .array(structureNode)
+            .optional()
+            .describe('Hierarchy nodes at the requested level (structure mode).'),
+        source: z
+            .enum(['mirror', 'live'])
+            .optional()
+            .describe('Provenance: the synced mirror index, or the live eCFR search fallback (search mode).'),
+        results: z
+            .array(searchHit)
+            .optional()
+            .describe('Matching CFR sections, this page (search mode).'),
+    }),
+    enrichment: {
+        totalCount: z
+            .number()
+            .optional()
+            .describe('Total search matches before pagination (search mode).'),
+        truncated: z.boolean().optional().describe('True when search results were capped at per_page.'),
+        shown: z.number().optional().describe('Results returned on this page (search mode).'),
+        notice: z.string().optional().describe('Guidance when nothing matched.'),
+    },
+    errors: [
+        {
+            reason: 'query_required',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'mode="search" with no query phrase.',
+            recovery: 'Provide a query phrase for search mode, or switch to mode="structure" to browse.',
+        },
+        {
+            reason: 'title_not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'Structure mode with a title outside 1–50, or a part not found in the title.',
+            recovery: 'Omit title to list all titles, or pick a number in 1–50 and a part that exists.',
+        },
+        {
+            reason: 'no_results',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'Search mode returned zero matches.',
+            recovery: 'Broaden the phrase or drop the title filter and retry.',
+        },
+        {
+            reason: 'upstream_unavailable',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'eCFR returned a 5xx, timed out, or served an HTML error page (live path).',
+            recovery: 'Retry after a brief wait; the eCFR API may be momentarily down.',
+        },
+    ],
+    async handler(input, ctx) {
+        const service = getEcfrService();
+        if (input.mode === 'structure') {
+            if (input.title === undefined) {
+                const nodes = await service.listTitleNodes(ctx);
+                return { mode: 'structure', date: input.date || today(), nodes };
+            }
+            // The eCFR versioner 404s when the date is past the title's most recent
+            // issue date (e.g. "today" before a title's next amendment publishes), so
+            // resolve an explicit-free request to the title's latest issue date rather
+            // than today(). A user-supplied historical date is honored as given.
+            const date = input.date || (await service.latestIssueDate(input.title, ctx));
+            const nodes = await service.browseStructure(input.title, input.part || undefined, date, ctx);
+            return { mode: 'structure', date, nodes };
+        }
+        // search mode
+        const query = input.query?.trim();
+        if (!query) {
+            throw ctx.fail('query_required', undefined, { ...ctx.recoveryFor('query_required') });
+        }
+        const ready = await mirrorReady();
+        const useMirror = ready && !input.date;
+        const response = useMirror
+            ? await mirrorSearch(query, input.title, input.per_page)
+            : await service.search(query, input.title, input.per_page, ctx);
+        ctx.enrich.total(response.totalCount);
+        if (response.results.length === 0) {
+            ctx.enrich.notice(`No CFR sections matched "${query}". Broaden the phrase or drop the title filter.`);
+            return {
+                mode: 'search',
+                source: useMirror ? 'mirror' : 'live',
+                results: [],
+            };
+        }
+        if (response.results.length >= input.per_page && response.totalCount > input.per_page) {
+            ctx.enrich.truncated({
+                shown: response.results.length,
+                cap: input.per_page,
+                guidance: `${response.totalCount} total matches. Raise per_page (max 50) or narrow the phrase.`,
+            });
+        }
+        return {
+            mode: 'search',
+            source: useMirror ? 'mirror' : 'live',
+            results: response.results,
+        };
+    },
+    format: (result) => {
+        const lines = [];
+        // Render by field presence (not `mode`): structure and search results are
+        // mutually exclusive at runtime, so a real payload renders exactly one block.
+        if (result.nodes) {
+            lines.push(`**CFR structure** (mode: ${result.mode}, as of ${result.date ?? 'current'})`);
+            lines.push('');
+            for (const n of result.nodes) {
+                const reserved = n.reserved ? ' _(reserved)_' : '';
+                const cite = n.cfrCite ? ` — \`${n.cfrCite}\` → regulations_get_cfr_section` : '';
+                const desc = n.description && n.description !== n.label ? ` — ${n.description}` : '';
+                lines.push(`- **${n.type}** ${n.identifier}: ${n.label}${desc}${reserved}${cite}`);
+            }
+        }
+        if (result.results || result.source) {
+            lines.push(`**CFR full-text search** (mode: ${result.mode}, source: ${result.source ?? 'live'})`);
+            lines.push('');
+            for (const h of result.results ?? []) {
+                lines.push(`### ${h.cfrCite} — ${h.heading} [Title ${h.title}, Part ${h.part}, § ${h.section ?? 'n/a'}]`);
+                lines.push(`_${h.hierarchyPath}_`);
+                lines.push(h.excerpt);
+                lines.push('');
+            }
+        }
+        return [{ type: 'text', text: lines.join('\n').trim() }];
+    },
+});
+//# sourceMappingURL=browse-cfr.tool.js.map

package/dist/mcp-server/tools/definitions/browse-cfr.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browse-cfr.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/browse-cfr.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,cAAc,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAElF,MAAM,aAAa,GAAG,CAAC;KACpB,MAAM,CAAC;IACN,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,QAAQ,CACP,wIAAwI,CACzI;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;IAClF,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;IACnD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;IAC1E,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;IACvE,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,kFAAkF,CAAC;CAChG,CAAC;KACD,QAAQ,CAAC,qBAAqB,CAAC,CAAC;AAEnC,MAAM,SAAS,GAAG,CAAC;KAChB,MAAM,CAAC;IACN,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC;IAC/C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;IACtC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;IACvE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;IACrD,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;IACpE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;IACrD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;CAC9E,CAAC;KACD,QAAQ,CAAC,2BAA2B,CAAC,CAAC;AAEzC,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,CAAC,wBAAwB,EAAE;IAC1D,KAAK,EAAE,wBAAwB;IAC/B,WAAW,EACT,4cAA4c;IAC9c,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;IACxD,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,IAAI,EAAE,CAAC;aACJ,IAAI,CAAC,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;aAC7B,QAAQ,CACP,gLAAgL,CACjL;QACH,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,GAAG,EAAE;aACL,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,EAAE,CAAC;aACP,QAAQ,EAAE;aACV,QAAQ,CACP,6JAA6J,CAC9J;QACH,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,qIAAqI,CACtI;QACH,KAAK,EAAE,CAAC;aACL,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,uCAAuC,CAAC,CAAC,CAAC;aAC3F,QAAQ,EAAE;aACV,QAAQ,CACP,0FAA0F,CAC3F;QACH,IAAI,EAAE,CAAC;aACJ,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,mLAAmL,CACpL;QACH,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,GAAG,EAAE;aACL,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,EAAE,CAAC;aACP,QAAQ,EAAE;aACV,OAAO,CAAC,EAAE,CAAC;aACX,QAAQ,CAAC,gFAAgF,CAAC;KAC9F,CAAC;IACF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,kCAAkC,CAAC;QAClF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;QACrF,KAAK,EAAE,CAAC;aACL,KAAK,CAAC,aAAa,CAAC;aACpB,QAAQ,EAAE;aACV,QAAQ,CAAC,0DAA0D,CAAC;QACvE,MAAM,EAAE,CAAC;aACN,IAAI,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;aACxB,QAAQ,EAAE;aACV,QAAQ,CACP,sFAAsF,CACvF;QACH,OAAO,EAAE,CAAC;aACP,KAAK,CAAC,SAAS,CAAC;aAChB,QAAQ,EAAE;aACV,QAAQ,CAAC,iDAAiD,CAAC;KAC/D,CAAC;IACF,UAAU,EAAE;QACV,UAAU,EAAE,CAAC;aACV,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,uDAAuD,CAAC;QACpE,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;QAC/F,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC;QACrF,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;KACzE;IACD,MAAM,EAAE;QACN;YACE,MAAM,EAAE,gBAAgB;YACxB,IAAI,EAAE,gBAAgB,CAAC,aAAa;YACpC,IAAI,EAAE,qCAAqC;YAC3C,QAAQ,EAAE,kFAAkF;SAC7F;QACD;YACE,MAAM,EAAE,iBAAiB;YACzB,IAAI,EAAE,gBAAgB,CAAC,QAAQ;YAC/B,IAAI,EAAE,6EAA6E;YACnF,QAAQ,EAAE,iFAAiF;SAC5F;QACD;YACE,MAAM,EAAE,YAAY;YACpB,IAAI,EAAE,gBAAgB,CAAC,QAAQ;YAC/B,IAAI,EAAE,oCAAoC;YAC1C,QAAQ,EAAE,wDAAwD;SACnE;QACD;YACE,MAAM,EAAE,sBAAsB;YAC9B,IAAI,EAAE,gBAAgB,CAAC,kBAAkB;YACzC,IAAI,EAAE,2EAA2E;YACjF,QAAQ,EAAE,iEAAiE;SAC5E;KACF;IAED,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,MAAM,OAAO,GAAG,cAAc,EAAE,CAAC;QAEjC,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAC/B,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;gBAC9B,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;gBAChD,OAAO,EAAE,IAAI,EAAE,WAAoB,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC;YAC5E,CAAC;YACD,wEAAwE;YACxE,0EAA0E;YAC1E,2EAA2E;YAC3E,qEAAqE;YACrE,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;YAC7E,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,IAAI,SAAS,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;YAC7F,OAAO,EAAE,IAAI,EAAE,WAAoB,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QACrD,CAAC;QAED,cAAc;QACd,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,GAAG,CAAC,IAAI,CAAC,gBAAgB,EAAE,SAAS,EAAE,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;QACxF,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,WAAW,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;QACvC,MAAM,QAAQ,GAAG,SAAS;YACxB,CAAC,CAAC,MAAM,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC;YACxD,CAAC,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAElE,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QAEtC,IAAI,QAAQ,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClC,GAAG,CAAC,MAAM,CAAC,MAAM,CACf,4BAA4B,KAAK,iDAAiD,CACnF,CAAC;YACF,OAAO;gBACL,IAAI,EAAE,QAAiB;gBACvB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAE,QAAkB,CAAC,CAAC,CAAE,MAAgB;gBAC3D,OAAO,EAAE,EAAE;aACZ,CAAC;QACJ,CAAC;QAED,IAAI,QAAQ,CAAC,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC,QAAQ,IAAI,QAAQ,CAAC,UAAU,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;YACtF,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC;gBACnB,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM;gBAC9B,GAAG,EAAE,KAAK,CAAC,QAAQ;gBACnB,QAAQ,EAAE,GAAG,QAAQ,CAAC,UAAU,+DAA+D;aAChG,CAAC,CAAC;QACL,CAAC;QAED,OAAO;YACL,IAAI,EAAE,QAAiB;YACvB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAE,QAAkB,CAAC,CAAC,CAAE,MAAgB;YAC3D,OAAO,EAAE,QAAQ,CAAC,OAAO;SAC1B,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE;QACjB,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,0EAA0E;QAC1E,8EAA8E;QAC9E,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,KAAK,CAAC,IAAI,CAAC,4BAA4B,MAAM,CAAC,IAAI,WAAW,MAAM,CAAC,IAAI,IAAI,SAAS,GAAG,CAAC,CAAC;YAC1F,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBAC7B,MAAM,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnD,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,kCAAkC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClF,MAAM,IAAI,GAAG,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACrF,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,KAAK,GAAG,IAAI,GAAG,QAAQ,GAAG,IAAI,EAAE,CAAC,CAAC;YACrF,CAAC;QACH,CAAC;QAED,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YACpC,KAAK,CAAC,IAAI,CACR,mCAAmC,MAAM,CAAC,IAAI,aAAa,MAAM,CAAC,MAAM,IAAI,MAAM,GAAG,CACtF,CAAC;YACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;gBACrC,KAAK,CAAC,IAAI,CACR,OAAO,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,OAAO,WAAW,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,IAAI,KAAK,GAAG,CAC9F,CAAC;gBACF,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC;gBACnC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;gBACtB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACjB,CAAC;QACH,CAAC;QAED,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC3D,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/find-comments.tool.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview regulations_find_comments — fetch public comments on a Federal
+ * Register document or a Regulations.gov docket, or one comment's full detail and
+ * attachments. The unique corpus of what citizens and organizations submitted.
+ * Key-gated. Flags when a comment's substance lives in an attachment rather than
+ * inline text, surfacing the attachment download URLs.
+ * @module mcp-server/tools/definitions/find-comments.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const findCommentsTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    docket_id: z.ZodOptional<z.ZodString>;
+    document_object_id: z.ZodOptional<z.ZodString>;
+    fr_document_number: z.ZodOptional<z.ZodString>;
+    comment_id: z.ZodOptional<z.ZodString>;
+    per_page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>, z.ZodObject<{
+    mode: z.ZodEnum<{
+        list: "list";
+        detail: "detail";
+    }>;
+    target: z.ZodOptional<z.ZodString>;
+    comments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        commentId: z.ZodString;
+        title: z.ZodString;
+        documentType: z.ZodString;
+        postedDate: z.ZodString;
+        agencyId: z.ZodNullable<z.ZodString>;
+        objectId: z.ZodString;
+        withdrawn: z.ZodBoolean;
+    }, z.core.$strip>>>;
+    commentId: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    docketId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    commentOnDocumentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    postedDate: z.ZodOptional<z.ZodString>;
+    receivedDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    submitterName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    organization: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    bodyText: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    attachmentOnly: z.ZodOptional<z.ZodBoolean>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        formats: z.ZodArray<z.ZodObject<{
+            format: z.ZodString;
+            fileUrl: z.ZodString;
+            size: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    withdrawn: z.ZodOptional<z.ZodBoolean>;
+    restrictReason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "auth_required";
+    readonly code: JsonRpcErrorCode.Unauthorized;
+    readonly when: "REGULATIONS_GOV_API_KEY is not configured.";
+    readonly recovery: "Set the REGULATIONS_GOV_API_KEY env var (free key at https://api.data.gov/signup/). The Federal Register and eCFR tools work without it.";
+}, {
+    readonly reason: "target_required";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "None of docket_id / document_object_id / fr_document_number / comment_id was given.";
+    readonly recovery: "Provide one targeting parameter — a docket ID, a document object ID, an FR document number, or a comment ID.";
+}, {
+    readonly reason: "not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "The target docket/document/comment has no comments or does not exist.";
+    readonly recovery: "Verify the ID; comments often attach to the docket's primary document — try docket_id to widen, or check the docket reached its comment period.";
+}, {
+    readonly reason: "rate_limited";
+    readonly code: JsonRpcErrorCode.RateLimited;
+    readonly when: "Regulations.gov returned 429.";
+    readonly retryable: true;
+    readonly recovery: "Wait and retry — the per-key hourly limit (1,000/hr) was hit.";
+}, {
+    readonly reason: "upstream_unavailable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "Regulations.gov returned a 5xx or timed out.";
+    readonly recovery: "Retry after a brief wait.";
+}], {
+    readonly totalCount: z.ZodOptional<z.ZodNumber>;
+    readonly truncated: z.ZodOptional<z.ZodBoolean>;
+    readonly shown: z.ZodOptional<z.ZodNumber>;
+    readonly notice: z.ZodOptional<z.ZodString>;
+}>;
+//# sourceMappingURL=find-comments.tool.d.ts.map

package/dist/mcp-server/tools/definitions/find-comments.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-comments.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/find-comments.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAIjE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiU3B,CAAC"}

package/dist/mcp-server/tools/definitions/find-comments.tool.js

@@ -0,0 +1,271 @@
+/**
+ * @fileoverview regulations_find_comments — fetch public comments on a Federal
+ * Register document or a Regulations.gov docket, or one comment's full detail and
+ * attachments. The unique corpus of what citizens and organizations submitted.
+ * Key-gated. Flags when a comment's substance lives in an attachment rather than
+ * inline text, surfacing the attachment download URLs.
+ * @module mcp-server/tools/definitions/find-comments.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getRegulationsGovService } from '../../../services/regulations-gov/regulations-gov-service.js';
+import { escapePipes } from './format-utils.js';
+export const findCommentsTool = tool('regulations_find_comments', {
+    title: 'regulations_find_comments',
+    description: "Fetch public comments on a Federal Register document or a Regulations.gov docket — the unique corpus of what citizens and organizations actually submitted. Provide exactly one targeting parameter: docket_id (all comments in a docket, broadest), document_object_id (comments on one document, from regulations_get_docket), fr_document_number (convenience — resolves the FR number to its Regulations.gov document internally), or comment_id (one comment's full detail and attachments). The list endpoint returns no body text or attachment info — call with comment_id to read a comment's body. When a comment's real content is a PDF/DOCX attachment, the body is a stub and attachmentOnly is true; the attachment download URLs are returned. Requires REGULATIONS_GOV_API_KEY (free at https://api.data.gov/signup/).",
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    input: z.object({
+        docket_id: z
+            .string()
+            .optional()
+            .describe('Fetch all comments in a docket by docket ID (e.g. "EPA-HQ-OAR-2025-0194"). Broadest scope. One of docket_id / document_object_id / fr_document_number / comment_id is required.'),
+        document_object_id: z
+            .string()
+            .optional()
+            .describe("Fetch comments on one specific document by its Regulations.gov object ID (the objectId from regulations_get_docket's documents). Comments usually attach to the docket's primary (proposed-rule) document."),
+        fr_document_number: z
+            .string()
+            .optional()
+            .describe('Convenience: fetch comments for a Federal Register document by its FR number (e.g. "2025-14555"). Resolves to the Regulations.gov document internally. Saves a get_document → get_docket hop.'),
+        comment_id: z
+            .string()
+            .optional()
+            .describe('Fetch one comment\'s full detail and attachments by its Regulations.gov comment ID (e.g. "EPA-HQ-OAR-2025-0194-31102"). Use to read a single comment\'s body after finding it in a list.'),
+        per_page: z
+            .number()
+            .int()
+            .min(5)
+            .max(250)
+            .optional()
+            .default(25)
+            .describe('Comments per page (5–250, default 25). Regulations.gov requires a minimum page size of 5.'),
+        page: z
+            .number()
+            .int()
+            .min(1)
+            .max(20)
+            .optional()
+            .default(1)
+            .describe('Page number (1-based). Regulations.gov caps a query at 20 pages (5,000 records); for a high-volume docket this surfaces a sample — narrow by document_object_id.'),
+    }),
+    output: z.object({
+        mode: z.enum(['list', 'detail']).describe('Which mode produced this result.'),
+        // --- list mode ---
+        target: z
+            .string()
+            .optional()
+            .describe('What was queried — docket / document / FR doc (list mode).'),
+        comments: z
+            .array(z
+            .object({
+            commentId: z.string().describe('Comment ID — chains into comment_id for full detail.'),
+            title: z.string().describe('Comment title (e.g. "Comment from Gates, Andrew").'),
+            documentType: z.string().describe('Document type (e.g. "Public Submission").'),
+            postedDate: z.string().describe('Posted date.'),
+            agencyId: z.string().nullable().describe('Agency ID, or null.'),
+            objectId: z.string().describe('Comment object ID.'),
+            withdrawn: z.boolean().describe('True when the comment was withdrawn.'),
+        })
+            .describe('One comment summary.'))
+            .optional()
+            .describe('Comments matching the target, this page (list mode). Bodies/attachments require comment_id detail mode.'),
+        // --- detail mode ---
+        commentId: z.string().optional().describe('Comment ID (detail mode).'),
+        title: z.string().optional().describe('Comment title (detail mode).'),
+        docketId: z.string().nullable().optional().describe('Docket ID, or null (detail mode).'),
+        commentOnDocumentId: z
+            .string()
+            .nullable()
+            .optional()
+            .describe('Document the comment was filed on, or null (detail mode).'),
+        postedDate: z.string().optional().describe('Posted date (detail mode).'),
+        receivedDate: z
+            .string()
+            .nullable()
+            .optional()
+            .describe('Received date, or null (detail mode).'),
+        submitterName: z
+            .string()
+            .nullable()
+            .optional()
+            .describe('Submitter name when public, or null (detail mode).'),
+        organization: z
+            .string()
+            .nullable()
+            .optional()
+            .describe('Submitter organization, or null (detail mode).'),
+        bodyText: z
+            .string()
+            .nullable()
+            .optional()
+            .describe('Comment body, HTML-stripped. A stub ("See Attached") when content is in attachments; null when empty (detail mode).'),
+        attachmentOnly: z
+            .boolean()
+            .optional()
+            .describe('True when attachments exist and the body is a stub/empty — the substance is in the attachment files (detail mode).'),
+        attachments: z
+            .array(z
+            .object({
+            title: z.string().describe('Attachment title.'),
+            formats: z
+                .array(z
+                .object({
+                format: z.string().describe('File format (e.g. "pdf").'),
+                fileUrl: z.string().describe('Download URL.'),
+                size: z.number().nullable().describe('File size in bytes, or null.'),
+            })
+                .describe('One downloadable file format.'))
+                .describe('Available file formats for the attachment.'),
+        })
+            .describe('One attachment with its available formats.'))
+            .optional()
+            .describe('Attachment files — substance lives here when attachmentOnly is true (detail mode).'),
+        withdrawn: z
+            .boolean()
+            .optional()
+            .describe('True when the comment was withdrawn (detail mode).'),
+        restrictReason: z
+            .string()
+            .nullable()
+            .optional()
+            .describe('Reason the comment is restricted, or null (detail mode).'),
+    }),
+    enrichment: {
+        totalCount: z.number().optional().describe('Total comments matching the target (list mode).'),
+        truncated: z
+            .boolean()
+            .optional()
+            .describe('True when comments exceed the 5,000-record ceiling (list mode).'),
+        shown: z.number().optional().describe('Comments returned on this page (list mode).'),
+        notice: z
+            .string()
+            .optional()
+            .describe('Guidance — empty results, or that bodies need comment_id detail mode.'),
+    },
+    errors: [
+        {
+            reason: 'auth_required',
+            code: JsonRpcErrorCode.Unauthorized,
+            when: 'REGULATIONS_GOV_API_KEY is not configured.',
+            recovery: 'Set the REGULATIONS_GOV_API_KEY env var (free key at https://api.data.gov/signup/). The Federal Register and eCFR tools work without it.',
+        },
+        {
+            reason: 'target_required',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'None of docket_id / document_object_id / fr_document_number / comment_id was given.',
+            recovery: 'Provide one targeting parameter — a docket ID, a document object ID, an FR document number, or a comment ID.',
+        },
+        {
+            reason: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'The target docket/document/comment has no comments or does not exist.',
+            recovery: "Verify the ID; comments often attach to the docket's primary document — try docket_id to widen, or check the docket reached its comment period.",
+        },
+        {
+            reason: 'rate_limited',
+            code: JsonRpcErrorCode.RateLimited,
+            when: 'Regulations.gov returned 429.',
+            retryable: true,
+            recovery: 'Wait and retry — the per-key hourly limit (1,000/hr) was hit.',
+        },
+        {
+            reason: 'upstream_unavailable',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'Regulations.gov returned a 5xx or timed out.',
+            recovery: 'Retry after a brief wait.',
+        },
+    ],
+    async handler(input, ctx) {
+        const service = getRegulationsGovService();
+        if (!service.hasKey()) {
+            throw ctx.fail('auth_required', undefined, { ...ctx.recoveryFor('auth_required') });
+        }
+        // Detail mode: one comment by ID.
+        if (input.comment_id) {
+            const detail = await service.getComment(input.comment_id, ctx);
+            if (detail.attachmentOnly) {
+                ctx.enrich.notice(`The substance of this comment is in ${detail.attachments.length} attachment(s) — see the attachment download URLs.`);
+            }
+            return { mode: 'detail', ...detail };
+        }
+        // List mode: resolve the target.
+        let filter;
+        let target;
+        if (input.document_object_id) {
+            filter = { commentOnId: input.document_object_id };
+            target = `document ${input.document_object_id}`;
+        }
+        else if (input.fr_document_number) {
+            const objectId = await service.resolveFrDocumentObjectId(input.fr_document_number, ctx);
+            if (!objectId) {
+                throw ctx.fail('not_found', `Federal Register document ${input.fr_document_number} has no Regulations.gov document to pull comments from.`, { recovery: { hint: 'Verify the FR number, or try docket_id to widen the search.' } });
+            }
+            filter = { commentOnId: objectId };
+            target = `FR document ${input.fr_document_number}`;
+        }
+        else if (input.docket_id) {
+            filter = { docketId: input.docket_id };
+            target = `docket ${input.docket_id}`;
+        }
+        else {
+            throw ctx.fail('target_required', undefined, { ...ctx.recoveryFor('target_required') });
+        }
+        const result = await service.listComments({ filter, perPage: input.per_page, page: input.page }, ctx);
+        ctx.enrich.total(result.totalCount);
+        if (result.comments.length === 0) {
+            ctx.enrich.notice(`No comments found for ${target}. Comments often attach to the docket's primary document — try docket_id to widen, or check the comment period has opened.`);
+        }
+        else {
+            const COMMENT_CEILING = 5000;
+            if (result.totalCount > COMMENT_CEILING) {
+                ctx.enrich.truncated({
+                    shown: result.comments.length,
+                    cap: COMMENT_CEILING,
+                    guidance: `${result.totalCount} comments exceed the 5,000-record ceiling — this is a sample. Narrow by document_object_id to scope the set.`,
+                });
+            }
+        }
+        return { mode: 'list', target, comments: result.comments };
+    },
+    format: (result) => {
+        const lines = [];
+        // Render by field presence (not `mode`): a real payload is one mode only, so
+        // detail keys on the top-level commentId and list keys on comments[].
+        if (result.commentId !== undefined) {
+            const attachments = result.attachments ?? [];
+            lines.push(`# ${result.title ?? '(untitled comment)'}`);
+            lines.push(`Comment \`${result.commentId ?? '—'}\` · posted ${result.postedDate ?? '—'} · received ${result.receivedDate ?? '—'}`);
+            lines.push(`Submitter: ${result.submitterName ?? '—'} · organization: ${result.organization ?? '—'}`);
+            lines.push(`Docket: ${result.docketId ?? '—'} · on document: ${result.commentOnDocumentId ?? '—'}`);
+            lines.push(`attachmentOnly: ${result.attachmentOnly ? 'yes' : 'no'} · withdrawn: ${result.withdrawn ? 'yes' : 'no'} · restrictReason: ${result.restrictReason ?? 'none'}`);
+            lines.push('');
+            if (result.attachmentOnly) {
+                lines.push(`> The substance of this comment is in ${attachments.length} attachment(s):`);
+            }
+            lines.push(result.bodyText ?? '_(no inline body text)_');
+            if (attachments.length) {
+                lines.push('\n## Attachments');
+                for (const a of attachments) {
+                    const fmts = a.formats
+                        .map((f) => `${f.format}: [${f.fileUrl}](${f.fileUrl}) (${f.size != null ? `${f.size} bytes` : 'size unknown'})`)
+                        .join(', ');
+                    lines.push(`- **${a.title}**: ${fmts}`);
+                }
+            }
+            lines.push('');
+        }
+        if (result.comments !== undefined) {
+            lines.push(`**Comments on ${result.target ?? 'target'}**`);
+            lines.push('');
+            lines.push('| Commenter | Type | Posted | Agency | Object ID | Comment ID (→ comment_id for body) |');
+            lines.push('|---|---|---|---|---|---|');
+            for (const c of result.comments ?? []) {
+                const wd = c.withdrawn ? ' (withdrawn)' : '';
+                lines.push(`| ${escapePipes(c.title)}${wd} | ${c.documentType} | ${c.postedDate} | ${c.agencyId ?? '—'} | ${c.objectId} | \`${c.commentId}\` |`);
+            }
+            lines.push('\n_Comment bodies and attachments are only available via detail mode (pass comment_id)._');
+        }
+        return [{ type: 'text', text: lines.join('\n').trim() }];
+    },
+});
+//# sourceMappingURL=find-comments.tool.js.map

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

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

package/dist/mcp-server/tools/definitions/format-utils.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Shared formatting helpers for tool format() renderers.
+ * @module mcp-server/tools/definitions/format-utils
+ */
+/** Escape `|` so cell content doesn't break markdown tables. */
+export declare function escapePipes(text: string): string;
+//# sourceMappingURL=format-utils.d.ts.map

package/dist/mcp-server/tools/definitions/format-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-utils.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/format-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/dist/mcp-server/tools/definitions/format-utils.js

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Shared formatting helpers for tool format() renderers.
+ * @module mcp-server/tools/definitions/format-utils
+ */
+/** Escape `|` so cell content doesn't break markdown tables. */
+export function escapePipes(text) {
+    return text.replace(/\|/g, '\\|');
+}
+//# sourceMappingURL=format-utils.js.map

package/dist/mcp-server/tools/definitions/format-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-utils.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/format-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,gEAAgE;AAChE,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AACpC,CAAC"}