@cyanheads/federal-regulations-mcp-server 0.1.0

package/changelog/template.md

@@ -0,0 +1,127 @@
+---
+# FORMAT REFERENCE — do not edit. Copy this file to
+# `changelog/<major.minor>.x/<version>.md` (e.g. `changelog/0.8.x/0.8.6.md`)
+# to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
+# with a concrete date.
+
+# Required. One-line GitHub Release-style headline. 350 character cap.
+# Default short and scannable. Don't pad, don't stitch unrelated changes with
+# semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
+# inside the value as a key separator and fails GitHub's strict parser.
+summary: ""
+
+# Set `true` when consumers must change code to upgrade: API removals,
+# signature changes, config renames, behavior changes that break existing
+# usage. Flagged as `Breaking` in the rollup.
+breaking: false
+
+# Set `true` if this release contains any security fix. Pairs with the
+# `## Security` section below. Flagged as `Security` in the rollup so
+# users can triage upgrade urgency at a glance.
+security: false
+
+# Optional free-form notes for maintenance agents processing this release.
+# Not rendered in CHANGELOG — consumed by agents running `maintenance` on
+# downstream servers. Use for adoption instructions that don't fit the
+# human-facing sections: new files to create, fields to populate, one-time
+# migration steps. Omit the field entirely when there's nothing to say.
+# agent-notes: |
+#   <instructions for downstream maintenance agents>
+---
+
+# <version> — YYYY-MM-DD
+
+<!--
+  AUTHORING GUIDE — applies to the new per-version file you create from this
+  template.
+
+  Audience: someone scanning release notes to decide what affects them. Lead
+  each bullet with the symbol or concept name in **bold** so they can skip
+  what's irrelevant and zoom in on what's not.
+
+  Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
+  name the symbol, state what changed, stop. Use a second sentence only when
+  it carries weight. If a bullet feels long, it is.
+
+  Cut: mechanism walkthroughs (those belong in JSDoc, CLAUDE.md/AGENTS.md, or the
+  relevant skill), ceremonial framings ("This release introduces…",
+  backwards-compat paragraphs), file-by-file test enumerations, internal
+  implementation notes. Prefer code/symbol names over English re-explanations.
+
+  Narrative intro: skip by default. Add one short sentence only when the
+  release theme genuinely needs framing the bullets can't carry.
+
+  Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
+  Fixed, Security. Include only sections with entries; delete the rest
+  (including the commented-out scaffolding below). Don't ship empty headers.
+
+  Include: every distinct fact a reader needs to adopt or audit the release —
+  new exports, signatures, lint rule IDs, env vars, breaking changes, version
+  bumps on shipped skills. Nothing more.
+
+  Links: link issues, PRs, docs, or skills where they help a reader jump to
+  context. Once per item per entry — don't re-link the same issue in summary,
+  narrative, and bullet. Skip links for inline symbol names; code spans speak
+  for themselves.
+
+  Issue/PR URLs: use full URLs. GitHub's bare `#NN` auto-link only resolves
+  inside its own UI, not in npm reads or local editors.
+
+      [#38](https://github.com/cyanheads/mcp-ts-core/issues/38)   ← issue
+      [#42](https://github.com/cyanheads/mcp-ts-core/pull/42)     ← PR
+
+  Verify numbers exist before linking (`gh issue view NN`, `gh pr view NN`).
+  Never speculate on a future number — `#42` for an upcoming PR silently
+  resolves to whatever real item already owns 42, and timeline previews pull
+  in that unrelated item's metadata.
+
+  TAG ANNOTATIONS — the annotated tag body renders as the GitHub Release body
+  via `gh release create --notes-from-tag`. The tag is a derivative of this
+  changelog entry — a condensed, scannable version, not a copy. Format:
+
+    <theme — omit version number, GitHub prepends it>
+                                                          ← blank line
+    <1-2 sentence context: what this release does>
+                                                          ← blank line
+    Dependency bumps:                                     ← section header
+                                                          ← blank line
+    - `@cyanheads/mcp-ts-core` ^0.9.1 → ^0.9.6          ← bullet
+                                                          ← blank line
+    Changed:                                              ← only sections with entries
+                                                          ← blank line
+    - `format()` output includes `query` in text mode
+                                                          ← blank line
+    Added:
+                                                          ← blank line
+    - `manifest.json` scaffolded for MCPB bundle support
+    - Install badges (Claude Desktop, Cursor, VS Code)
+                                                          ← blank line
+    <N> tests pass; `bun run devcheck` clean.             ← footer
+
+  Never a flat comma-separated string. Always structured markdown with
+  sections. The tag must scan well as a rendered GitHub Release page.
+-->
+
+## Added
+
+-
+
+## Changed
+
+-
+
+<!-- ## Deprecated
+
+- -->
+
+<!-- ## Removed
+
+- -->
+
+## Fixed
+
+-
+
+<!-- ## Security
+
+- -->

package/dist/config/server-config.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Server-specific environment configuration for
+ * federal-regulations-mcp-server. Lazy-parsed Zod schema, separate from the
+ * framework's own config. Maps the three data-source base URLs, the optional
+ * Regulations.gov API key, and the eCFR mirror settings.
+ *
+ * `REGULATIONS_GOV_API_KEY` is optional: the keyless core (Federal Register +
+ * eCFR tools) is a complete deployment without it. The two Regulations.gov tools
+ * enforce its presence per-call (an actionable `auth_required` error), so its
+ * absence is a valid startup state, not a configuration failure.
+ *
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+declare const ServerConfigSchema: z.ZodObject<{
+    regulationsGovApiKey: z.ZodOptional<z.ZodString>;
+    federalRegisterBaseUrl: z.ZodDefault<z.ZodString>;
+    ecfrBaseUrl: z.ZodDefault<z.ZodString>;
+    regulationsGovBaseUrl: z.ZodDefault<z.ZodString>;
+    ecfrMirrorPath: z.ZodDefault<z.ZodString>;
+    ecfrMirrorRefreshCron: z.ZodDefault<z.ZodString>;
+    ecfrMirrorTitles: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ServerConfig = z.infer<typeof ServerConfigSchema>;
+/**
+ * Lazily parse and cache the server config from the environment. Throws a
+ * `ConfigurationError` (rendered as a clean startup banner) when a provided
+ * value fails validation.
+ */
+export declare function getServerConfig(): ServerConfig;
+export {};
+//# sourceMappingURL=server-config.d.ts.map

package/dist/config/server-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;;;;;iBA+BtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAW9C"}

package/dist/config/server-config.js

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview Server-specific environment configuration for
+ * federal-regulations-mcp-server. Lazy-parsed Zod schema, separate from the
+ * framework's own config. Maps the three data-source base URLs, the optional
+ * Regulations.gov API key, and the eCFR mirror settings.
+ *
+ * `REGULATIONS_GOV_API_KEY` is optional: the keyless core (Federal Register +
+ * eCFR tools) is a complete deployment without it. The two Regulations.gov tools
+ * enforce its presence per-call (an actionable `auth_required` error), so its
+ * absence is a valid startup state, not a configuration failure.
+ *
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { parseEnvConfig } from '@cyanheads/mcp-ts-core/config';
+const ServerConfigSchema = z.object({
+    /** api.data.gov key for the Regulations.gov leg. Absent = keyless-core deployment. */
+    regulationsGovApiKey: z
+        .string()
+        .optional()
+        .describe('api.data.gov key for the Regulations.gov tools (get_docket, find_comments).'),
+    federalRegisterBaseUrl: z
+        .string()
+        .url()
+        .default('https://www.federalregister.gov/api/v1')
+        .describe('Federal Register API v1 base URL.'),
+    ecfrBaseUrl: z.string().url().default('https://www.ecfr.gov/api').describe('eCFR API base URL.'),
+    regulationsGovBaseUrl: z
+        .string()
+        .url()
+        .default('https://api.regulations.gov/v4')
+        .describe('Regulations.gov API v4 base URL.'),
+    ecfrMirrorPath: z
+        .string()
+        .default('./data/ecfr-mirror.sqlite')
+        .describe('Filesystem path for the eCFR SQLite mirror database.'),
+    ecfrMirrorRefreshCron: z
+        .string()
+        .default('0 4 * * 0')
+        .describe('Cron expression for the weekly eCFR mirror refresh.'),
+    ecfrMirrorTitles: z
+        .string()
+        .optional()
+        .describe('Comma-separated CFR title numbers to scope the mirror to (e.g. "21,40"). Omit to mirror all 50 titles. A partial mirror still serves its baked titles from the index; cites outside the set fall through to the live eCFR API.'),
+});
+let _config;
+/**
+ * Lazily parse and cache the server config from the environment. Throws a
+ * `ConfigurationError` (rendered as a clean startup banner) when a provided
+ * value fails validation.
+ */
+export function getServerConfig() {
+    _config ??= parseEnvConfig(ServerConfigSchema, {
+        regulationsGovApiKey: 'REGULATIONS_GOV_API_KEY',
+        federalRegisterBaseUrl: 'FEDERAL_REGISTER_BASE_URL',
+        ecfrBaseUrl: 'ECFR_BASE_URL',
+        regulationsGovBaseUrl: 'REGULATIONS_GOV_BASE_URL',
+        ecfrMirrorPath: 'ECFR_MIRROR_PATH',
+        ecfrMirrorRefreshCron: 'ECFR_MIRROR_REFRESH_CRON',
+        ecfrMirrorTitles: 'ECFR_MIRROR_TITLES',
+    });
+    return _config;
+}
+//# sourceMappingURL=server-config.js.map

package/dist/config/server-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,sFAAsF;IACtF,oBAAoB,EAAE,CAAC;SACpB,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,6EAA6E,CAAC;IAC1F,sBAAsB,EAAE,CAAC;SACtB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,wCAAwC,CAAC;SACjD,QAAQ,CAAC,mCAAmC,CAAC;IAChD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IAChG,qBAAqB,EAAE,CAAC;SACrB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,OAAO,CAAC,gCAAgC,CAAC;SACzC,QAAQ,CAAC,kCAAkC,CAAC;IAC/C,cAAc,EAAE,CAAC;SACd,MAAM,EAAE;SACR,OAAO,CAAC,2BAA2B,CAAC;SACpC,QAAQ,CAAC,sDAAsD,CAAC;IACnE,qBAAqB,EAAE,CAAC;SACrB,MAAM,EAAE;SACR,OAAO,CAAC,WAAW,CAAC;SACpB,QAAQ,CAAC,qDAAqD,CAAC;IAClE,gBAAgB,EAAE,CAAC;SAChB,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,gOAAgO,CACjO;CACJ,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,cAAc,CAAC,kBAAkB,EAAE;QAC7C,oBAAoB,EAAE,yBAAyB;QAC/C,sBAAsB,EAAE,2BAA2B;QACnD,WAAW,EAAE,eAAe;QAC5B,qBAAqB,EAAE,0BAA0B;QACjD,cAAc,EAAE,kBAAkB;QAClC,qBAAqB,EAAE,0BAA0B;QACjD,gBAAgB,EAAE,oBAAoB;KACvC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview federal-regulations-mcp-server entry point. Wires the three
+ * data-source services (Federal Register, eCFR, Regulations.gov) and registers
+ * the codified-CFR mirror's weekly refresh on a cron — gated to the HTTP
+ * transport so stdio operators (who run the mirror lifecycle out-of-band) don't
+ * double-run it. The mirror's full init is never run here; it is an out-of-band
+ * `mirror:init` CLI step.
+ * @module index
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG"}

package/dist/index.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview federal-regulations-mcp-server entry point. Wires the three
+ * data-source services (Federal Register, eCFR, Regulations.gov) and registers
+ * the codified-CFR mirror's weekly refresh on a cron — gated to the HTTP
+ * transport so stdio operators (who run the mirror lifecycle out-of-band) don't
+ * double-run it. The mirror's full init is never run here; it is an out-of-band
+ * `mirror:init` CLI step.
+ * @module index
+ */
+import { createApp } from '@cyanheads/mcp-ts-core';
+import { logger, requestContextService, schedulerService } from '@cyanheads/mcp-ts-core/utils';
+import { getServerConfig } from './config/server-config.js';
+import { allResourceDefinitions } from './mcp-server/resources/definitions/index.js';
+import { allToolDefinitions } from './mcp-server/tools/definitions/index.js';
+import { initEcfrService } from './services/ecfr/ecfr-service.js';
+import { ecfrMirror } from './services/ecfr-mirror/ecfr-mirror.js';
+import { initFederalRegisterService } from './services/federal-register/federal-register-service.js';
+import { initRegulationsGovService } from './services/regulations-gov/regulations-gov-service.js';
+const MIRROR_REFRESH_JOB = 'ecfr-mirror-refresh';
+await createApp({
+    name: 'federal-regulations-mcp-server',
+    title: 'federal-regulations-mcp-server',
+    tools: allToolDefinitions,
+    resources: allResourceDefinitions,
+    prompts: [],
+    instructions: 'US federal regulatory law over three official sources. The Federal Register (regulations_search_rules, regulations_get_document, regulations_list_open_comments) and eCFR (regulations_browse_cfr, regulations_get_cfr_section) tools are keyless. The Regulations.gov tools (regulations_get_docket, regulations_find_comments) need REGULATIONS_GOV_API_KEY (free at https://api.data.gov/signup/) and return an actionable auth_required error without it; regulations_list_open_comments runs keyless and only adds comment counts when the key is present. Trace a rule end to end: search_rules → get_document (yields docket ID + CFR parts) → find_comments → get_cfr_section.',
+    setup(core) {
+        initFederalRegisterService(core.config, core.storage);
+        initEcfrService(core.config, core.storage);
+        initRegulationsGovService(core.config, core.storage);
+        // Register the weekly mirror refresh on HTTP only. Stdio operators run the
+        // mirror lifecycle (init/refresh) out-of-band via the CLI scripts, so the
+        // cron would otherwise double-run. Init is never triggered here.
+        if (core.config.mcpTransportType === 'http') {
+            const cron = getServerConfig().ecfrMirrorRefreshCron;
+            void schedulerService
+                .schedule(MIRROR_REFRESH_JOB, cron, async () => {
+                await ecfrMirror.runSync({ mode: 'refresh' });
+            }, 'Weekly incremental refresh of the codified CFR mirror')
+                .then(() => schedulerService.start(MIRROR_REFRESH_JOB))
+                .catch((err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.warning(`Failed to schedule eCFR mirror refresh: ${message}`, requestContextService.createRequestContext({
+                    operation: 'setup:schedule-mirror-refresh',
+                }));
+            });
+        }
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAC/F,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,yDAAyD,CAAC;AACrG,OAAO,EAAE,yBAAyB,EAAE,MAAM,uDAAuD,CAAC;AAElG,MAAM,kBAAkB,GAAG,qBAAqB,CAAC;AAEjD,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,gCAAgC;IACtC,KAAK,EAAE,gCAAgC;IACvC,KAAK,EAAE,kBAAkB;IACzB,SAAS,EAAE,sBAAsB;IACjC,OAAO,EAAE,EAAE;IACX,YAAY,EACV,wpBAAwpB;IAC1pB,KAAK,CAAC,IAAI;QACR,0BAA0B,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACtD,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3C,yBAAyB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAErD,2EAA2E;QAC3E,0EAA0E;QAC1E,iEAAiE;QACjE,IAAI,IAAI,CAAC,MAAM,CAAC,gBAAgB,KAAK,MAAM,EAAE,CAAC;YAC5C,MAAM,IAAI,GAAG,eAAe,EAAE,CAAC,qBAAqB,CAAC;YACrD,KAAK,gBAAgB;iBAClB,QAAQ,CACP,kBAAkB,EAClB,IAAI,EACJ,KAAK,IAAI,EAAE;gBACT,MAAM,UAAU,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;YAChD,CAAC,EACD,uDAAuD,CACxD;iBACA,IAAI,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;iBACtD,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;gBACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACjE,MAAM,CAAC,OAAO,CACZ,2CAA2C,OAAO,EAAE,EACpD,qBAAqB,CAAC,oBAAoB,CAAC;oBACzC,SAAS,EAAE,+BAA+B;iBAC3C,CAAC,CACH,CAAC;YACJ,CAAC,CAAC,CAAC;QACP,CAAC;IACH,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/resources/definitions/cfr-section.resource.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview regulations://cfr/{title}/{part}/{section} — codified text of a
+ * current CFR section, the same payload as regulations_get_cfr_section at the
+ * current date, for clients that support injectable context. Mirror-backed with a
+ * live eCFR fallback. Every datum is also reachable through the tool surface.
+ * @module mcp-server/resources/definitions/cfr-section.resource
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const cfrSectionResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
+    title: z.ZodString;
+    part: z.ZodString;
+    section: z.ZodString;
+}, z.core.$strip>, undefined, undefined>;
+//# sourceMappingURL=cfr-section.resource.d.ts.map

package/dist/mcp-server/resources/definitions/cfr-section.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cfr-section.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/cfr-section.resource.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAKrD,eAAO,MAAM,kBAAkB;;;;wCAiF7B,CAAC"}

package/dist/mcp-server/resources/definitions/cfr-section.resource.js

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview regulations://cfr/{title}/{part}/{section} — codified text of a
+ * current CFR section, the same payload as regulations_get_cfr_section at the
+ * current date, for clients that support injectable context. Mirror-backed with a
+ * live eCFR fallback. Every datum is also reachable through the tool surface.
+ * @module mcp-server/resources/definitions/cfr-section.resource
+ */
+import { resource, z } from '@cyanheads/mcp-ts-core';
+import { notFound } from '@cyanheads/mcp-ts-core/errors';
+import { getEcfrService } from '../../../services/ecfr/ecfr-service.js';
+import { mirrorGetSection, mirrorReady } from '../../../services/ecfr-mirror/ecfr-mirror.js';
+export const cfrSectionResource = resource('regulations://cfr/{title}/{part}/{section}', {
+    name: 'cfr-section',
+    title: 'CFR section (current)',
+    description: 'Codified text of a current CFR section by title/part/section (e.g. regulations://cfr/40/50/50.1). Mirrors regulations_get_cfr_section at the current date — mirror-backed with a live eCFR fallback.',
+    mimeType: 'application/json',
+    params: z.object({
+        title: z
+            .string()
+            .regex(/^\d{1,2}$/)
+            .describe('CFR title number (1–50).'),
+        part: z.string().describe('CFR part (e.g. "50").'),
+        section: z.string().describe('Section identifier (e.g. "50.1").'),
+    }),
+    async handler(params, ctx) {
+        const titleNum = Number.parseInt(params.title, 10);
+        const service = getEcfrService();
+        if (await mirrorReady()) {
+            const hit = await mirrorGetSection(titleNum, params.part, params.section);
+            if (hit) {
+                const hierarchyPath = await service.hierarchyPath(titleNum, params.part, params.section, hit.date, ctx);
+                return {
+                    cfrCite: `${titleNum} CFR ${params.section}`,
+                    title: titleNum,
+                    part: params.part,
+                    section: params.section,
+                    heading: hit.heading,
+                    hierarchyPath,
+                    date: hit.date,
+                    source: 'mirror',
+                    bodyText: hit.bodyText,
+                };
+            }
+        }
+        const date = await service.latestIssueDate(titleNum, ctx);
+        const result = await service.getSectionText(titleNum, params.part, params.section, date, ctx);
+        if (!result.bodyText) {
+            throw notFound(`No codified text for ${titleNum} CFR ${params.section}.`, {
+                title: titleNum,
+                part: params.part,
+                section: params.section,
+            });
+        }
+        const hierarchyPath = await service.hierarchyPath(titleNum, params.part, params.section, result.date, ctx);
+        return {
+            cfrCite: `${titleNum} CFR ${params.section}`,
+            title: titleNum,
+            part: params.part,
+            section: params.section,
+            heading: result.heading,
+            hierarchyPath,
+            date: result.date,
+            source: 'live',
+            bodyText: result.bodyText,
+        };
+    },
+    list: () => ({
+        resources: [
+            {
+                uri: 'regulations://cfr/40/50/50.1',
+                name: 'Example CFR section (40 CFR 50.1)',
+                mimeType: 'application/json',
+            },
+        ],
+    }),
+});
+//# sourceMappingURL=cfr-section.resource.js.map

package/dist/mcp-server/resources/definitions/cfr-section.resource.js.map

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

package/dist/mcp-server/resources/definitions/document.resource.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview regulations://document/{documentNumber} — a single Federal
+ * Register document (metadata + cross-source handles, full text omitted), the
+ * same payload as regulations_get_document for clients that support injectable
+ * context. Every datum is also reachable through the tool surface.
+ * @module mcp-server/resources/definitions/document.resource
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const documentResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
+    documentNumber: z.ZodString;
+}, z.core.$strip>, undefined, undefined>;
+//# sourceMappingURL=document.resource.d.ts.map

package/dist/mcp-server/resources/definitions/document.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/document.resource.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAGrD,eAAO,MAAM,gBAAgB;;wCA8B3B,CAAC"}

package/dist/mcp-server/resources/definitions/document.resource.js

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview regulations://document/{documentNumber} — a single Federal
+ * Register document (metadata + cross-source handles, full text omitted), the
+ * same payload as regulations_get_document for clients that support injectable
+ * context. Every datum is also reachable through the tool surface.
+ * @module mcp-server/resources/definitions/document.resource
+ */
+import { resource, z } from '@cyanheads/mcp-ts-core';
+import { getFederalRegisterService } from '../../../services/federal-register/federal-register-service.js';
+export const documentResource = resource('regulations://document/{documentNumber}', {
+    name: 'federal-register-document',
+    title: 'Federal Register document',
+    description: 'A single Federal Register document by FR number: metadata plus the cross-source handles (docket ID, affected CFR parts, comment count) that chain into the comment and codified-text tools. Mirrors regulations_get_document (full text omitted).',
+    mimeType: 'application/json',
+    params: z.object({
+        documentNumber: z
+            .string()
+            .regex(/^[0-9]{4}-[0-9]+$/)
+            .describe('Federal Register document number (e.g. "2025-14555").'),
+    }),
+    async handler(params, ctx) {
+        const service = getFederalRegisterService();
+        const detail = await service.getDocument(params.documentNumber, false, ctx);
+        // Drop the (absent) fullText field; the resource omits the body by contract.
+        const { fullText: _omit, ...rest } = detail;
+        return rest;
+    },
+    list: () => ({
+        resources: [
+            {
+                uri: 'regulations://document/2025-14555',
+                name: 'Example Federal Register document',
+                mimeType: 'application/json',
+            },
+        ],
+    }),
+});
+//# sourceMappingURL=document.resource.js.map

package/dist/mcp-server/resources/definitions/document.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/document.resource.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,yBAAyB,EAAE,MAAM,yDAAyD,CAAC;AAEpG,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,CAAC,yCAAyC,EAAE;IAClF,IAAI,EAAE,2BAA2B;IACjC,KAAK,EAAE,2BAA2B;IAClC,WAAW,EACT,mPAAmP;IACrP,QAAQ,EAAE,kBAAkB;IAC5B,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,cAAc,EAAE,CAAC;aACd,MAAM,EAAE;aACR,KAAK,CAAC,mBAAmB,CAAC;aAC1B,QAAQ,CAAC,uDAAuD,CAAC;KACrE,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG;QACvB,MAAM,OAAO,GAAG,yBAAyB,EAAE,CAAC;QAC5C,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,cAAc,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QAC5E,6EAA6E;QAC7E,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;QACX,SAAS,EAAE;YACT;gBACE,GAAG,EAAE,mCAAmC;gBACxC,IAAI,EAAE,mCAAmC;gBACzC,QAAQ,EAAE,kBAAkB;aAC7B;SACF;KACF,CAAC;CACH,CAAC,CAAC"}

package/dist/mcp-server/resources/definitions/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Barrel of all resource definitions for federal-regulations-mcp-server.
+ * @module mcp-server/resources/definitions/index
+ */
+export declare const allResourceDefinitions: (import("@cyanheads/mcp-ts-core").ResourceDefinition<import("zod").ZodObject<{
+    title: import("zod").ZodString;
+    part: import("zod").ZodString;
+    section: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, undefined, undefined> | import("@cyanheads/mcp-ts-core").ResourceDefinition<import("zod").ZodObject<{
+    documentNumber: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, undefined, undefined>)[];
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp-server/resources/definitions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,eAAO,MAAM,sBAAsB;;;;;;0DAAyC,CAAC"}

package/dist/mcp-server/resources/definitions/index.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Barrel of all resource definitions for federal-regulations-mcp-server.
+ * @module mcp-server/resources/definitions/index
+ */
+import { cfrSectionResource } from './cfr-section.resource.js';
+import { documentResource } from './document.resource.js';
+export const allResourceDefinitions = [documentResource, cfrSectionResource];
+//# sourceMappingURL=index.js.map

package/dist/mcp-server/resources/definitions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAAC"}

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

@@ -0,0 +1,73 @@
+/**
+ * @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 { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const browseCfrTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    mode: z.ZodEnum<{
+        search: "search";
+        structure: "structure";
+    }>;
+    title: z.ZodOptional<z.ZodNumber>;
+    part: z.ZodOptional<z.ZodString>;
+    query: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>;
+    date: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>;
+    per_page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>, z.ZodObject<{
+    mode: z.ZodEnum<{
+        search: "search";
+        structure: "structure";
+    }>;
+    date: z.ZodOptional<z.ZodString>;
+    nodes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        identifier: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        reserved: z.ZodBoolean;
+        cfrCite: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>>;
+    source: z.ZodOptional<z.ZodEnum<{
+        mirror: "mirror";
+        live: "live";
+    }>>;
+    results: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodNumber;
+        part: z.ZodString;
+        section: z.ZodNullable<z.ZodString>;
+        heading: z.ZodString;
+        hierarchyPath: z.ZodString;
+        excerpt: z.ZodString;
+        cfrCite: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "query_required";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "mode=\"search\" with no query phrase.";
+    readonly recovery: "Provide a query phrase for search mode, or switch to mode=\"structure\" to browse.";
+}, {
+    readonly reason: "title_not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "Structure mode with a title outside 1–50, or a part not found in the title.";
+    readonly recovery: "Omit title to list all titles, or pick a number in 1–50 and a part that exists.";
+}, {
+    readonly reason: "no_results";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "Search mode returned zero matches.";
+    readonly recovery: "Broaden the phrase or drop the title filter and retry.";
+}, {
+    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 down.";
+}], {
+    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=browse-cfr.tool.d.ts.map

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

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