@cyanheads/federal-regulations-mcp-server 0.1.0

package/dist/mcp-server/tools/definitions/get-cfr-section.tool.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview regulations_get_cfr_section — read the codified text of a CFR
+ * section (or whole part) via eCFR, current or as of a past date. Mirror row
+ * lookup is the primary path for a current single section; historical dates,
+ * whole-part fetches, and a cold mirror fall back to the live eCFR versioner.
+ * Keyless.
+ * @module mcp-server/tools/definitions/get-cfr-section.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const getCfrSectionTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    title: z.ZodNumber;
+    part: z.ZodString;
+    section: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>;
+    date: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>;
+}, z.core.$strip>, z.ZodObject<{
+    cfrCite: z.ZodString;
+    title: z.ZodNumber;
+    part: z.ZodString;
+    section: z.ZodNullable<z.ZodString>;
+    heading: z.ZodString;
+    hierarchyPath: z.ZodString;
+    date: z.ZodString;
+    source: z.ZodEnum<{
+        mirror: "mirror";
+        live: "live";
+    }>;
+    bodyText: z.ZodString;
+    sections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        section: z.ZodString;
+        heading: z.ZodString;
+        bodyText: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No such title/part/section at that date.";
+    readonly recovery: "Verify the cite with regulations_browse_cfr (structure mode); the part or section may not exist or may be reserved.";
+}, {
+    readonly reason: "date_out_of_range";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "The requested date precedes eCFR historical coverage.";
+    readonly recovery: "Use a date from ~2017 onward, or omit date for the current text.";
+}, {
+    readonly reason: "upstream_unavailable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "eCFR returned a 5xx, timed out, or served an HTML error page (live path).";
+    readonly recovery: "Retry after a brief wait; the eCFR API may be momentarily unavailable.";
+}], undefined>;
+//# sourceMappingURL=get-cfr-section.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-cfr-section.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-cfr-section.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-cfr-section.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,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA4K5B,CAAC"}

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

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview regulations_get_cfr_section — read the codified text of a CFR
+ * section (or whole part) via eCFR, current or as of a past date. Mirror row
+ * lookup is the primary path for a current single section; historical dates,
+ * whole-part fetches, and a cold mirror fall back to the live eCFR versioner.
+ * Keyless.
+ * @module mcp-server/tools/definitions/get-cfr-section.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { ECFR_EARLIEST_DATE, getEcfrService } from '../../../services/ecfr/ecfr-service.js';
+import { mirrorGetSection, mirrorReady } from '../../../services/ecfr-mirror/ecfr-mirror.js';
+export const getCfrSectionTool = tool('regulations_get_cfr_section', {
+    title: 'regulations_get_cfr_section',
+    description: 'Read the codified text of a specific CFR section (or a whole part) via eCFR — current or as of a past date. Answers "what does 40 CFR 50.1 say today?" and "...as of 2019-01-01?". Provide title + part + section for one section, or omit section to fetch the whole part (large parts can be very long; prefer a specific section when you know it). eCFR retains historical versions back to roughly 2017; a date before coverage is rejected with guidance. Current single-section reads are served from a synced local mirror when available; the source is reported.',
+    annotations: { readOnlyHint: true, idempotentHint: true },
+    input: z.object({
+        title: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .describe('CFR title number (1–50). E.g. 40 for "Protection of Environment".'),
+        part: z
+            .string()
+            .describe('CFR part within the title (e.g. "50"). Parts can be alphanumeric. Obtain from regulations_browse_cfr or a Federal Register document\'s cfrReferences.'),
+        section: z
+            .union([z.literal(''), z.string().describe('Section identifier (e.g. "50.1").')])
+            .optional()
+            .describe('Section identifier within the part (e.g. "50.1"). Omit to fetch the entire part — large parts can be very long; prefer a specific section when you know it.'),
+        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). Default current. eCFR retains historical versions back to ~2017; a date before coverage is rejected.'),
+    }),
+    output: z.object({
+        cfrCite: z.string().describe('Assembled cite, e.g. "40 CFR 50.1".'),
+        title: z.number().describe('CFR title number.'),
+        part: z.string().describe('CFR part.'),
+        section: z
+            .string()
+            .nullable()
+            .describe('Section identifier; null when a whole part was fetched.'),
+        heading: z.string().describe('Section/part heading.'),
+        hierarchyPath: z.string().describe('Human-readable hierarchy path.'),
+        date: z.string().describe('The issue/point-in-time date the text reflects (ISO 8601).'),
+        source: z
+            .enum(['mirror', 'live'])
+            .describe('Provenance: the synced mirror, or the live eCFR API.'),
+        bodyText: z
+            .string()
+            .describe('Section text, XML stripped to plain text (paragraph structure preserved).'),
+        sections: z
+            .array(z
+            .object({
+            section: z.string().describe('Section identifier.'),
+            heading: z.string().describe('Section heading.'),
+            bodyText: z.string().describe('Section text.'),
+        })
+            .describe('One section within the part.'))
+            .optional()
+            .describe('Present only when a whole part was fetched — each section in the part.'),
+    }),
+    errors: [
+        {
+            reason: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No such title/part/section at that date.',
+            recovery: 'Verify the cite with regulations_browse_cfr (structure mode); the part or section may not exist or may be reserved.',
+        },
+        {
+            reason: 'date_out_of_range',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'The requested date precedes eCFR historical coverage.',
+            recovery: 'Use a date from ~2017 onward, or omit date for the current text.',
+        },
+        {
+            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 unavailable.',
+        },
+    ],
+    async handler(input, ctx) {
+        const service = getEcfrService();
+        const section = input.section?.trim() || undefined;
+        const requestedDate = input.date?.trim() || undefined;
+        if (requestedDate && requestedDate < ECFR_EARLIEST_DATE) {
+            throw ctx.fail('date_out_of_range', `Date ${requestedDate} precedes eCFR coverage (~${ECFR_EARLIEST_DATE}).`, {
+                ...ctx.recoveryFor('date_out_of_range'),
+            });
+        }
+        // Fast path: current single section served from the mirror when ready.
+        if (section && !requestedDate && (await mirrorReady())) {
+            const hit = await mirrorGetSection(input.title, input.part, section);
+            if (hit) {
+                const hierarchyPath = await service.hierarchyPath(input.title, input.part, section, hit.date, ctx);
+                return {
+                    cfrCite: `${input.title} CFR ${section}`,
+                    title: input.title,
+                    part: input.part,
+                    section,
+                    heading: hit.heading,
+                    hierarchyPath,
+                    date: hit.date,
+                    source: 'mirror',
+                    bodyText: hit.bodyText,
+                };
+            }
+            // Mirror miss → fall through to the live versioner.
+        }
+        const date = requestedDate ?? (await service.latestIssueDate(input.title, ctx));
+        const result = await service.getSectionText(input.title, input.part, section, date, ctx);
+        const hierarchyPath = await service.hierarchyPath(input.title, input.part, section, result.date, ctx);
+        return {
+            cfrCite: section ? `${input.title} CFR ${section}` : `${input.title} CFR ${input.part}`,
+            title: input.title,
+            part: input.part,
+            section: result.section,
+            heading: result.heading,
+            hierarchyPath,
+            date: result.date,
+            source: 'live',
+            bodyText: result.bodyText,
+            ...(result.sections ? { sections: result.sections } : {}),
+        };
+    },
+    format: (result) => {
+        const lines = [];
+        lines.push(`# ${result.cfrCite} — ${result.heading}`);
+        lines.push(`Title ${result.title} · Part ${result.part}${result.section ? ` · § ${result.section}` : ' (whole part)'}`);
+        lines.push(`_${result.hierarchyPath}_ · as of ${result.date} · source: ${result.source}`);
+        lines.push('');
+        lines.push(result.bodyText);
+        if (result.sections) {
+            lines.push('');
+            for (const s of result.sections) {
+                lines.push(`## § ${s.section} — ${s.heading}`);
+                lines.push(s.bodyText);
+                lines.push('');
+            }
+        }
+        return [{ type: 'text', text: lines.join('\n').trim() }];
+    },
+});
+//# sourceMappingURL=get-cfr-section.tool.js.map

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

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

package/dist/mcp-server/tools/definitions/get-docket.tool.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview regulations_get_docket — pull a rulemaking docket from
+ * Regulations.gov by docket ID: docket metadata plus the documents filed in it.
+ * Key-gated: returns an actionable auth_required error when REGULATIONS_GOV_API_KEY
+ * is absent. Each document's objectId feeds regulations_find_comments.
+ * @module mcp-server/tools/definitions/get-docket.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const getDocketTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    docket_id: z.ZodString;
+    document_types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        "Proposed Rule": "Proposed Rule";
+        Rule: "Rule";
+        Notice: "Notice";
+        "Supporting & Related Material": "Supporting & Related Material";
+        Other: "Other";
+    }>>>;
+    per_page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>, z.ZodObject<{
+    docketId: z.ZodString;
+    title: z.ZodString;
+    docketType: z.ZodNullable<z.ZodString>;
+    agencyId: z.ZodNullable<z.ZodString>;
+    rin: z.ZodNullable<z.ZodString>;
+    abstract: z.ZodNullable<z.ZodString>;
+    modifyDate: z.ZodNullable<z.ZodString>;
+    objectId: z.ZodNullable<z.ZodString>;
+    documentCount: z.ZodNumber;
+    documents: z.ZodArray<z.ZodObject<{
+        documentId: z.ZodString;
+        objectId: z.ZodString;
+        title: z.ZodString;
+        documentType: z.ZodString;
+        postedDate: z.ZodString;
+        frDocNum: z.ZodNullable<z.ZodString>;
+        commentEndDate: z.ZodNullable<z.ZodString>;
+        withdrawn: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, 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: "not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No docket exists with that ID.";
+    readonly recovery: "Verify the docket ID from a Federal Register document's docketId; format is like \"EPA-HQ-OAR-2025-0194\".";
+}, {
+    readonly reason: "rate_limited";
+    readonly code: JsonRpcErrorCode.RateLimited;
+    readonly when: "Regulations.gov returned 429 (1,000 requests/hour per key).";
+    readonly retryable: true;
+    readonly recovery: "Wait and retry — the per-key hourly limit 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 truncated: z.ZodOptional<z.ZodBoolean>;
+    readonly shown: z.ZodOptional<z.ZodNumber>;
+    readonly notice: z.ZodOptional<z.ZodString>;
+}>;
+//# sourceMappingURL=get-docket.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-docket.tool.d.ts.map

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

package/dist/mcp-server/tools/definitions/get-docket.tool.js

@@ -0,0 +1,154 @@
+/**
+ * @fileoverview regulations_get_docket — pull a rulemaking docket from
+ * Regulations.gov by docket ID: docket metadata plus the documents filed in it.
+ * Key-gated: returns an actionable auth_required error when REGULATIONS_GOV_API_KEY
+ * is absent. Each document's objectId feeds regulations_find_comments.
+ * @module mcp-server/tools/definitions/get-docket.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 getDocketTool = tool('regulations_get_docket', {
+    title: 'regulations_get_docket',
+    description: 'Pull a rulemaking docket from Regulations.gov by docket ID (e.g. "EPA-HQ-OAR-2025-0194") — the docket\'s metadata (title, agency, RIN, abstract) and the documents filed in it (NPRM, final rule, supporting materials). The docket is the folder holding a rule\'s whole paper trail; each returned document\'s objectId feeds regulations_find_comments. A docket often contains hundreds of supporting materials — filter document_types to "Proposed Rule"/"Rule" to find the rule documents themselves. Requires REGULATIONS_GOV_API_KEY (free at https://api.data.gov/signup/); the Federal Register and eCFR tools work without it.',
+    annotations: { readOnlyHint: true, idempotentHint: true },
+    input: z.object({
+        docket_id: z
+            .string()
+            .regex(/^[A-Za-z0-9_-]+$/)
+            .describe('Regulations.gov docket ID (e.g. "EPA-HQ-OAR-2025-0194"). Obtain from a Federal Register document\'s docketId (regulations_get_document) or an agency rulemaking reference.'),
+        document_types: z
+            .array(z.enum(['Proposed Rule', 'Rule', 'Notice', 'Supporting & Related Material', 'Other']))
+            .optional()
+            .describe('Filter the docket\'s documents to these types. Omit for all. A docket often contains hundreds of "Supporting & Related Material" items — filter to "Proposed Rule"/"Rule" to find the rule documents.'),
+        per_page: z
+            .number()
+            .int()
+            .min(5)
+            .max(250)
+            .optional()
+            .default(25)
+            .describe('Documents 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); beyond that, narrow with document_types.'),
+    }),
+    output: z.object({
+        docketId: z.string().describe('Regulations.gov docket ID.'),
+        title: z.string().describe('Docket title.'),
+        docketType: z.string().nullable().describe('Docket type (e.g. "Rulemaking"), or null.'),
+        agencyId: z.string().nullable().describe('Agency ID (e.g. "EPA"), or null.'),
+        rin: z
+            .string()
+            .nullable()
+            .describe('Regulation Identifier Number ("Not Assigned" when none), or null.'),
+        abstract: z.string().nullable().describe('Docket abstract, or null.'),
+        modifyDate: z.string().nullable().describe('Last-modified date, or null.'),
+        objectId: z.string().nullable().describe('Docket object ID, or null.'),
+        documentCount: z.number().describe('Total documents in the docket (before pagination).'),
+        documents: z
+            .array(z
+            .object({
+            documentId: z.string().describe('Regulations.gov document ID.'),
+            objectId: z
+                .string()
+                .describe('Document object ID — chains into regulations_find_comments(document_object_id).'),
+            title: z.string().describe('Document title.'),
+            documentType: z.string().describe('Document type.'),
+            postedDate: z.string().describe('Posted date.'),
+            frDocNum: z
+                .string()
+                .nullable()
+                .describe('Federal Register document number — chains back into regulations_get_document. Null when absent.'),
+            commentEndDate: z
+                .string()
+                .nullable()
+                .describe('Comment-period end date; when set, open for comment.'),
+            withdrawn: z.boolean().describe('True when the document was withdrawn.'),
+        })
+            .describe('One document filed in the docket.'))
+            .describe('Documents filed in the docket (this page).'),
+    }),
+    enrichment: {
+        truncated: z
+            .boolean()
+            .optional()
+            .describe('True when documentCount exceeds the returned set / 5,000 ceiling.'),
+        shown: z.number().optional().describe('Documents returned on this page.'),
+        notice: z.string().optional().describe('Guidance when the docket has no documents.'),
+    },
+    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: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No docket exists with that ID.',
+            recovery: 'Verify the docket ID from a Federal Register document\'s docketId; format is like "EPA-HQ-OAR-2025-0194".',
+        },
+        {
+            reason: 'rate_limited',
+            code: JsonRpcErrorCode.RateLimited,
+            when: 'Regulations.gov returned 429 (1,000 requests/hour per key).',
+            retryable: true,
+            recovery: 'Wait and retry — the per-key hourly limit 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') });
+        }
+        const result = await service.getDocket({
+            docketId: input.docket_id,
+            documentTypes: input.document_types,
+            perPage: input.per_page,
+            page: input.page,
+        }, ctx);
+        if (result.documents.length === 0) {
+            ctx.enrich.notice(`Docket ${input.docket_id} returned no documents${input.document_types?.length ? ' for the requested document_types' : ''}. Drop the document_types filter to see all.`);
+        }
+        else if (result.documentCount > result.documents.length) {
+            ctx.enrich.truncated({
+                shown: result.documents.length,
+                cap: input.per_page,
+                guidance: `${result.documentCount} documents total. Raise per_page (max 250), page forward (max 20 pages), or filter document_types.`,
+            });
+        }
+        return result;
+    },
+    format: (result) => {
+        const lines = [];
+        lines.push(`# Docket ${result.docketId} — ${result.title}`);
+        lines.push(`${result.agencyId ?? '—'} · ${result.docketType ?? '—'} · RIN ${result.rin ?? '—'}${result.modifyDate ? ` · modified ${result.modifyDate}` : ''}`);
+        lines.push(`Docket object ID: ${result.objectId ?? '—'}`);
+        if (result.abstract)
+            lines.push(`\n${result.abstract}`);
+        lines.push(`\n**${result.documentCount} documents** (showing ${result.documents.length}):\n`);
+        lines.push('| Type | Title | Posted | Comments Close | Document ID | Object ID (→ find_comments) |');
+        lines.push('|---|---|---|---|---|---|');
+        for (const d of result.documents) {
+            const fr = d.frDocNum ? ` [FR ${d.frDocNum}]` : '';
+            const wd = d.withdrawn ? ' (withdrawn)' : '';
+            lines.push(`| ${d.documentType} | ${escapePipes(d.title)}${fr}${wd} | ${d.postedDate} | ${d.commentEndDate ?? '—'} | ${d.documentId} | \`${d.objectId}\` |`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-docket.tool.js.map

package/dist/mcp-server/tools/definitions/get-docket.tool.js.map

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

package/dist/mcp-server/tools/definitions/get-document.tool.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview regulations_get_document — fetch one Federal Register document by
+ * FR number: full metadata plus the cross-source handles (docket ID, affected CFR
+ * parts, Regulations.gov document ID, comment count) that chain into the comment
+ * and codified-text tools. The stitching tool of this server. Keyless.
+ * @module mcp-server/tools/definitions/get-document.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const getDocumentTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    document_number: z.ZodString;
+    include_full_text: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>, z.ZodObject<{
+    documentNumber: z.ZodString;
+    title: z.ZodString;
+    type: z.ZodString;
+    abstract: z.ZodNullable<z.ZodString>;
+    action: z.ZodNullable<z.ZodString>;
+    dates: z.ZodNullable<z.ZodString>;
+    publicationDate: z.ZodString;
+    effectiveOn: z.ZodNullable<z.ZodString>;
+    commentsCloseOn: z.ZodNullable<z.ZodString>;
+    agencies: z.ZodArray<z.ZodString>;
+    regulationIdNumbers: z.ZodArray<z.ZodString>;
+    cfrReferences: z.ZodArray<z.ZodObject<{
+        title: z.ZodNumber;
+        part: z.ZodString;
+    }, z.core.$strip>>;
+    docketId: z.ZodNullable<z.ZodString>;
+    regulationsGovDocumentId: z.ZodNullable<z.ZodString>;
+    commentCount: z.ZodNullable<z.ZodNumber>;
+    supportingDocuments: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        documentId: z.ZodString;
+    }, z.core.$strip>>;
+    bodyHtmlUrl: z.ZodString;
+    rawTextUrl: z.ZodString;
+    htmlUrl: z.ZodString;
+    fullText: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No Federal Register document exists with that number.";
+    readonly recovery: "Verify the number via regulations_search_rules; FR numbers look like \"2025-14555\".";
+}, {
+    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.";
+}], undefined>;
+//# sourceMappingURL=get-document.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-document.tool.d.ts.map

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

package/dist/mcp-server/tools/definitions/get-document.tool.js

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview regulations_get_document — fetch one Federal Register document by
+ * FR number: full metadata plus the cross-source handles (docket ID, affected CFR
+ * parts, Regulations.gov document ID, comment count) that chain into the comment
+ * and codified-text tools. The stitching tool of this server. Keyless.
+ * @module mcp-server/tools/definitions/get-document.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';
+export const getDocumentTool = tool('regulations_get_document', {
+    title: 'regulations_get_document',
+    description: 'Fetch one Federal Register document by its FR document number — full metadata (title, type, agencies, abstract, action, effective/comment dates, RINs) plus the cross-source handles that make this a workflow server. The output carries the docket ID (chain into regulations_get_docket or regulations_find_comments) and the affected CFR parts (chain into regulations_get_cfr_section). Set include_full_text only when the rule body itself is needed — final rules can run tens of thousands of words.',
+    annotations: { readOnlyHint: true, idempotentHint: true },
+    input: z.object({
+        document_number: z
+            .string()
+            .regex(/^[0-9]{4}-[0-9]+$/)
+            .describe('Federal Register document number (e.g. "2025-14555"). Obtain from regulations_search_rules results (the documentNumber field).'),
+        include_full_text: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('When true, fetch and inline the document body as plain text (can be large). Default false returns the body URLs only; fetch full text only when you need to read the rule itself, not just its metadata and cross-links.'),
+    }),
+    output: z.object({
+        documentNumber: z.string().describe('Federal Register document number.'),
+        title: z.string().describe('Document title.'),
+        type: z.string().describe('Document type.'),
+        abstract: z.string().nullable().describe('Abstract summary, or null.'),
+        action: z.string().nullable().describe('Action line (e.g. "Final rule."), or null.'),
+        dates: z.string().nullable().describe('Free-text dates summary from the rule, or null.'),
+        publicationDate: z.string().describe('Publication date (ISO 8601).'),
+        effectiveOn: z.string().nullable().describe('Effective date (ISO 8601), or null.'),
+        commentsCloseOn: z
+            .string()
+            .nullable()
+            .describe('Comment-period close date (ISO 8601); when set, still open for comment.'),
+        agencies: z.array(z.string()).describe('Issuing agency names.'),
+        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.'),
+        docketId: z
+            .string()
+            .nullable()
+            .describe('Regulations.gov docket ID — chain into regulations_get_docket / find_comments. Null when not on Regulations.gov.'),
+        regulationsGovDocumentId: z
+            .string()
+            .nullable()
+            .describe('Regulations.gov document ID — chain into regulations_find_comments (document-scoped). Null when absent.'),
+        commentCount: z
+            .number()
+            .nullable()
+            .describe('FR-reported comment count from Regulations.gov; null when not on Regulations.gov.'),
+        supportingDocuments: z
+            .array(z
+            .object({
+            title: z.string().describe('Supporting document title.'),
+            documentId: z.string().describe('Regulations.gov document ID.'),
+        })
+            .describe('One related Regulations.gov supporting document.'))
+            .describe('Related Regulations.gov supporting documents.'),
+        bodyHtmlUrl: z.string().describe('URL of the rendered HTML body.'),
+        rawTextUrl: z.string().describe('URL of the plain-text body.'),
+        htmlUrl: z.string().describe('Federal Register web URL for the document.'),
+        fullText: z
+            .string()
+            .optional()
+            .describe('Inlined plain-text body — present only when include_full_text=true.'),
+    }),
+    errors: [
+        {
+            reason: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No Federal Register document exists with that number.',
+            recovery: 'Verify the number via regulations_search_rules; FR numbers look like "2025-14555".',
+        },
+        {
+            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();
+        return await service.getDocument(input.document_number, input.include_full_text, ctx);
+    },
+    format: (result) => {
+        const lines = [];
+        lines.push(`# ${result.title}`);
+        lines.push(`**FR ${result.documentNumber}** · ${result.type} · ${result.agencies.join(', ') || '—'} · published ${result.publicationDate}`);
+        if (result.action)
+            lines.push(`**Action:** ${result.action}`);
+        if (result.dates)
+            lines.push(`**Dates:** ${result.dates}`);
+        if (result.effectiveOn)
+            lines.push(`**Effective:** ${result.effectiveOn}`);
+        if (result.commentsCloseOn)
+            lines.push(`**Comments close:** ${result.commentsCloseOn}`);
+        if (result.regulationIdNumbers.length)
+            lines.push(`**RIN:** ${result.regulationIdNumbers.join(', ')}`);
+        if (result.abstract)
+            lines.push(`\n${result.abstract}`);
+        lines.push('\n## Cross-source handles');
+        lines.push(result.docketId
+            ? `- **Docket ID:** \`${result.docketId}\` → regulations_get_docket / regulations_find_comments(docket_id)`
+            : '- **Docket ID:** not on Regulations.gov');
+        if (result.regulationsGovDocumentId) {
+            lines.push(`- **Regulations.gov document ID:** \`${result.regulationsGovDocumentId}\` → regulations_find_comments(document_object_id)`);
+        }
+        lines.push(`- **Comment count:** ${result.commentCount ?? 'unknown'} → regulations_find_comments(fr_document_number="${result.documentNumber}")`);
+        if (result.cfrReferences.length) {
+            const cites = result.cfrReferences.map((c) => `${c.title} CFR ${c.part}`).join(', ');
+            lines.push(`- **Affected CFR parts:** ${cites} → regulations_get_cfr_section`);
+        }
+        else {
+            lines.push('- **Affected CFR parts:** none listed');
+        }
+        if (result.supportingDocuments.length) {
+            lines.push(`- **Supporting documents:** ${result.supportingDocuments.map((d) => `${d.title} (${d.documentId})`).join('; ')}`);
+        }
+        lines.push('\n## Body');
+        lines.push(`- HTML: ${result.bodyHtmlUrl}`);
+        lines.push(`- Raw text: ${result.rawTextUrl}`);
+        lines.push(`- Federal Register page: ${result.htmlUrl}`);
+        if (result.fullText)
+            lines.push(`\n---\n\n${result.fullText}`);
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-document.tool.js.map