@cyanheads/federal-regulations-mcp-server 0.5.4 → 0.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +21 -9
- package/CLAUDE.md +21 -9
- package/Dockerfile +2 -0
- package/README.md +46 -139
- package/changelog/0.6.x/0.6.0.md +30 -0
- package/changelog/0.6.x/0.6.1.md +29 -0
- package/dist/config/server-config.d.ts +3 -1
- package/dist/config/server-config.d.ts.map +1 -1
- package/dist/config/server-config.js +7 -1
- package/dist/config/server-config.js.map +1 -1
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/resources/definitions/cfr-section.resource.d.ts.map +1 -1
- package/dist/mcp-server/resources/definitions/cfr-section.resource.js +6 -4
- package/dist/mcp-server/resources/definitions/cfr-section.resource.js.map +1 -1
- package/dist/mcp-server/resources/definitions/document.resource.js +1 -1
- package/dist/mcp-server/resources/definitions/document.resource.js.map +1 -1
- package/dist/mcp-server/tools/definitions/browse-cfr.tool.d.ts +41 -8
- package/dist/mcp-server/tools/definitions/browse-cfr.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/browse-cfr.tool.js +189 -40
- package/dist/mcp-server/tools/definitions/browse-cfr.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/find-comments.tool.d.ts +6 -3
- package/dist/mcp-server/tools/definitions/find-comments.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/find-comments.tool.js +64 -39
- package/dist/mcp-server/tools/definitions/find-comments.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/format-utils.d.ts +17 -0
- package/dist/mcp-server/tools/definitions/format-utils.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/format-utils.js +36 -1
- package/dist/mcp-server/tools/definitions/format-utils.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-cfr-section.tool.d.ts +1 -1
- package/dist/mcp-server/tools/definitions/get-cfr-section.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-cfr-section.tool.js +19 -15
- package/dist/mcp-server/tools/definitions/get-cfr-section.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-docket.tool.d.ts +67 -16
- package/dist/mcp-server/tools/definitions/get-docket.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-docket.tool.js +224 -56
- package/dist/mcp-server/tools/definitions/get-docket.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-document.tool.d.ts +11 -1
- package/dist/mcp-server/tools/definitions/get-document.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-document.tool.js +20 -13
- package/dist/mcp-server/tools/definitions/get-document.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +287 -170
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/list-open-comments.tool.d.ts +1 -1
- package/dist/mcp-server/tools/definitions/list-open-comments.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/list-open-comments.tool.js +12 -14
- package/dist/mcp-server/tools/definitions/list-open-comments.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/presidential-schema.d.ts +17 -0
- package/dist/mcp-server/tools/definitions/presidential-schema.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/presidential-schema.js +31 -0
- package/dist/mcp-server/tools/definitions/presidential-schema.js.map +1 -0
- package/dist/mcp-server/tools/definitions/search-rules.tool.d.ts +35 -3
- package/dist/mcp-server/tools/definitions/search-rules.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-rules.tool.js +144 -28
- package/dist/mcp-server/tools/definitions/search-rules.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/size-limit.d.ts +50 -0
- package/dist/mcp-server/tools/definitions/size-limit.d.ts.map +1 -0
- package/dist/mcp-server/tools/definitions/size-limit.js +93 -0
- package/dist/mcp-server/tools/definitions/size-limit.js.map +1 -0
- package/dist/services/ecfr/ecfr-service.d.ts +50 -6
- package/dist/services/ecfr/ecfr-service.d.ts.map +1 -1
- package/dist/services/ecfr/ecfr-service.js +128 -12
- package/dist/services/ecfr/ecfr-service.js.map +1 -1
- package/dist/services/ecfr/read-section.d.ts +12 -3
- package/dist/services/ecfr/read-section.d.ts.map +1 -1
- package/dist/services/ecfr/read-section.js +12 -5
- package/dist/services/ecfr/read-section.js.map +1 -1
- package/dist/services/ecfr/types.d.ts +68 -0
- package/dist/services/ecfr/types.d.ts.map +1 -1
- package/dist/services/federal-register/federal-register-service.d.ts +2 -1
- package/dist/services/federal-register/federal-register-service.d.ts.map +1 -1
- package/dist/services/federal-register/federal-register-service.js +82 -12
- package/dist/services/federal-register/federal-register-service.js.map +1 -1
- package/dist/services/federal-register/types.d.ts +52 -2
- package/dist/services/federal-register/types.d.ts.map +1 -1
- package/dist/services/federal-register/types.js +10 -1
- package/dist/services/federal-register/types.js.map +1 -1
- package/dist/services/regulations-gov/regulations-gov-service.d.ts +21 -2
- package/dist/services/regulations-gov/regulations-gov-service.d.ts.map +1 -1
- package/dist/services/regulations-gov/regulations-gov-service.js +86 -13
- package/dist/services/regulations-gov/regulations-gov-service.js.map +1 -1
- package/dist/services/regulations-gov/types.d.ts +58 -15
- package/dist/services/regulations-gov/types.d.ts.map +1 -1
- package/dist/services/request-budget.d.ts +2 -2
- package/dist/services/request-budget.js +2 -2
- package/dist/services/upstream-failure.d.ts +5 -0
- package/dist/services/upstream-failure.d.ts.map +1 -1
- package/dist/services/upstream-failure.js +1 -0
- package/dist/services/upstream-failure.js.map +1 -1
- package/package.json +7 -6
- package/server.json +17 -3
- package/skills/federal-regulations-guide/SKILL.md +71 -0
package/AGENTS.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# Developer Protocol
|
|
2
2
|
|
|
3
3
|
**Server:** federal-regulations-mcp-server
|
|
4
|
-
**Version:** 0.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `0.13.
|
|
4
|
+
**Version:** 0.6.1
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `0.13.18`
|
|
6
6
|
**Engines:** Bun ≥1.4.0, Node ≥24.0.0
|
|
7
|
-
**MCP SDK:** `@modelcontextprotocol/server` ^2.
|
|
7
|
+
**MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
|
|
8
8
|
**Zod:** ^4.6.7
|
|
9
9
|
|
|
10
10
|
> **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
|
|
@@ -237,7 +237,9 @@ src/
|
|
|
237
237
|
regulations-gov/ # Regulations.gov v4 client (X-Api-Key) — dockets, comments
|
|
238
238
|
mcp-server/
|
|
239
239
|
tools/definitions/ # 7 regulations_* tools (search-rules, get-document, browse-cfr,
|
|
240
|
-
# get-cfr-section, get-docket, find-comments, list-open-comments)
|
|
240
|
+
# get-cfr-section, get-docket, find-comments, list-open-comments);
|
|
241
|
+
# size-limit.ts is the shared per_page / max_chars field, clamp, and notice;
|
|
242
|
+
# presidential-schema.ts the presidential output object shared by search-rules and get-document
|
|
241
243
|
resources/definitions/ # 2 resources (document, cfr-section)
|
|
242
244
|
scripts/
|
|
243
245
|
ecfr-mirror-init.ts # out-of-band mirror lifecycle (init / refresh / verify)
|
|
@@ -248,7 +250,7 @@ scripts/
|
|
|
248
250
|
|
|
249
251
|
No prompts in v1 — `createApp({ prompts: [] })`.
|
|
250
252
|
|
|
251
|
-
**`scripts/` is typechecked
|
|
253
|
+
**`scripts/` is typechecked.** `tsconfig.json` includes `scripts/**/*` and `tests/**/*`; the mirror lifecycle scripts also ship in npm and Docker. `scripts/lint-mcp.ts` and `scripts/lint-packaging.ts` import the installed framework's linter directly, omitting upstream fallbacks to framework-only source files that do not exist here. Preserve those consumer imports after maintenance syncs. The bundle scripts also anchor dependency agent-doc matching at package roots so SDK `dist/ext/skills` runtime modules survive pruning; `tests/scripts/bundle-agent-docs.test.ts` guards both matching literals.
|
|
252
254
|
|
|
253
255
|
---
|
|
254
256
|
|
|
@@ -265,9 +267,18 @@ No prompts in v1 — `createApp({ prompts: [] })`.
|
|
|
265
267
|
|
|
266
268
|
## Skills
|
|
267
269
|
|
|
268
|
-
|
|
270
|
+
Two skill trees live at the project root, written for different readers:
|
|
269
271
|
|
|
270
|
-
|
|
272
|
+
| Tree | For | Written by |
|
|
273
|
+
|:-----|:----|:-----------|
|
|
274
|
+
| `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |
|
|
275
|
+
| `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | You, deliberately, with the `add-skill` skill. Absent by default; usually none is needed |
|
|
276
|
+
|
|
277
|
+
Development skills are modular instructions. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. Their directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand them to every agent that installs it.
|
|
278
|
+
|
|
279
|
+
A published skill in root `skills/` reaches plugin installs and the `.mcpb` bundle as-is, ships in the npm package and the Docker image, and reaches MCP clients when the server opts in with `createApp({ skills: 'skills' })`. `lint:packaging` validates the tree.
|
|
280
|
+
|
|
281
|
+
**Agent skill directory:** Copy `framework-skills/` into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
|
|
271
282
|
|
|
272
283
|
Available skills:
|
|
273
284
|
|
|
@@ -279,6 +290,7 @@ Available skills:
|
|
|
279
290
|
| `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
|
|
280
291
|
| `add-resource` | Scaffold a new resource definition |
|
|
281
292
|
| `add-prompt` | Scaffold a new prompt definition |
|
|
293
|
+
| `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
|
|
282
294
|
| `add-service` | Scaffold a new service integration |
|
|
283
295
|
| `add-test` | Scaffold test file for a tool, resource, or service |
|
|
284
296
|
| `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
|
|
@@ -326,7 +338,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
326
338
|
| `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
|
|
327
339
|
| `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
|
|
328
340
|
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
329
|
-
| `bun run lint:packaging` | Packaging surface checks —
|
|
341
|
+
| `bun run lint:packaging` | Packaging surface checks — env-var parity, `.mcpbignore` coverage, plugin manifests, published `skills/` tree (run by devcheck) |
|
|
330
342
|
| `bun run list-skills` | Print the skill registry |
|
|
331
343
|
| `bun run tree` | Generate directory structure doc |
|
|
332
344
|
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
@@ -347,7 +359,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
347
359
|
|
|
348
360
|
## Bundling
|
|
349
361
|
|
|
350
|
-
`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips
|
|
362
|
+
`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `mcpb pack` reads `.mcpbignore`, not `.gitignore`, so every root path the bundle must not ship — source, tests, docs, caches, logs, agent docs, plugin manifests, gitignored local files — needs a root-anchored line there (`/docs/`, never `docs/`, which also strips `node_modules/*/docs/`); `lint:packaging` names each missing or unanchored line. Root `skills/` ships on purpose. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips four classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`); platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on; node-gyp build output beside a `binding.gyp` (`config.gypi`, Makefiles, `obj.target/`, `.deps/`, object files and debug symbols), which records the packing machine's paths — compiled `*.node` addons stay; and build-only package files — the framework's `changelog/`, `scripts/`, `templates/`, `CLAUDE.md`, `AGENTS.md`, and config bases (`biome.json`, `vitest.config.base.mjs`, `config/tsconfig.base.json`), and `better-sqlite3`'s `deps/` and `src/` C sources. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
|
|
351
363
|
|
|
352
364
|
**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
|
|
353
365
|
|
package/CLAUDE.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# Developer Protocol
|
|
2
2
|
|
|
3
3
|
**Server:** federal-regulations-mcp-server
|
|
4
|
-
**Version:** 0.
|
|
5
|
-
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `0.13.
|
|
4
|
+
**Version:** 0.6.1
|
|
5
|
+
**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `0.13.18`
|
|
6
6
|
**Engines:** Bun ≥1.4.0, Node ≥24.0.0
|
|
7
|
-
**MCP SDK:** `@modelcontextprotocol/server` ^2.
|
|
7
|
+
**MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
|
|
8
8
|
**Zod:** ^4.6.7
|
|
9
9
|
|
|
10
10
|
> **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
|
|
@@ -237,7 +237,9 @@ src/
|
|
|
237
237
|
regulations-gov/ # Regulations.gov v4 client (X-Api-Key) — dockets, comments
|
|
238
238
|
mcp-server/
|
|
239
239
|
tools/definitions/ # 7 regulations_* tools (search-rules, get-document, browse-cfr,
|
|
240
|
-
# get-cfr-section, get-docket, find-comments, list-open-comments)
|
|
240
|
+
# get-cfr-section, get-docket, find-comments, list-open-comments);
|
|
241
|
+
# size-limit.ts is the shared per_page / max_chars field, clamp, and notice;
|
|
242
|
+
# presidential-schema.ts the presidential output object shared by search-rules and get-document
|
|
241
243
|
resources/definitions/ # 2 resources (document, cfr-section)
|
|
242
244
|
scripts/
|
|
243
245
|
ecfr-mirror-init.ts # out-of-band mirror lifecycle (init / refresh / verify)
|
|
@@ -248,7 +250,7 @@ scripts/
|
|
|
248
250
|
|
|
249
251
|
No prompts in v1 — `createApp({ prompts: [] })`.
|
|
250
252
|
|
|
251
|
-
**`scripts/` is typechecked
|
|
253
|
+
**`scripts/` is typechecked.** `tsconfig.json` includes `scripts/**/*` and `tests/**/*`; the mirror lifecycle scripts also ship in npm and Docker. `scripts/lint-mcp.ts` and `scripts/lint-packaging.ts` import the installed framework's linter directly, omitting upstream fallbacks to framework-only source files that do not exist here. Preserve those consumer imports after maintenance syncs. The bundle scripts also anchor dependency agent-doc matching at package roots so SDK `dist/ext/skills` runtime modules survive pruning; `tests/scripts/bundle-agent-docs.test.ts` guards both matching literals.
|
|
252
254
|
|
|
253
255
|
---
|
|
254
256
|
|
|
@@ -265,9 +267,18 @@ No prompts in v1 — `createApp({ prompts: [] })`.
|
|
|
265
267
|
|
|
266
268
|
## Skills
|
|
267
269
|
|
|
268
|
-
|
|
270
|
+
Two skill trees live at the project root, written for different readers:
|
|
269
271
|
|
|
270
|
-
|
|
272
|
+
| Tree | For | Written by |
|
|
273
|
+
|:-----|:----|:-----------|
|
|
274
|
+
| `framework-skills/` | The agent developing this server — framework skills (`metadata.audience: external`) plus any development-time skills of the server's own | `init` and the `maintenance` sync (framework skills); you (your own) |
|
|
275
|
+
| `skills/` | The agents that install the server and call its tools — tool chains, identifier sources, gates | You, deliberately, with the `add-skill` skill. Absent by default; usually none is needed |
|
|
276
|
+
|
|
277
|
+
Development skills are modular instructions. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. Their directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand them to every agent that installs it.
|
|
278
|
+
|
|
279
|
+
A published skill in root `skills/` reaches plugin installs and the `.mcpb` bundle as-is, ships in the npm package and the Docker image, and reaches MCP clients when the server opts in with `createApp({ skills: 'skills' })`. `lint:packaging` validates the tree.
|
|
280
|
+
|
|
281
|
+
**Agent skill directory:** Copy `framework-skills/` into the directory your agent discovers (Claude Code: `.claude/skills/`, others: equivalent). Skills then load as context without referencing `framework-skills/` paths. After framework updates, run the `maintenance` skill — Phase B re-syncs the agent directory.
|
|
271
282
|
|
|
272
283
|
Available skills:
|
|
273
284
|
|
|
@@ -279,6 +290,7 @@ Available skills:
|
|
|
279
290
|
| `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
|
|
280
291
|
| `add-resource` | Scaffold a new resource definition |
|
|
281
292
|
| `add-prompt` | Scaffold a new prompt definition |
|
|
293
|
+
| `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — when one earns its place, structure, validation, delivery |
|
|
282
294
|
| `add-service` | Scaffold a new service integration |
|
|
283
295
|
| `add-test` | Scaffold test file for a tool, resource, or service |
|
|
284
296
|
| `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
|
|
@@ -326,7 +338,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
326
338
|
| `bun run audit:fix` | `bun audit fix` — upgrade vulnerable packages to the lowest safe version within existing ranges (`--dry-run` previews, `--latest` rewrites ranges). First response when `devcheck` flags a transitive advisory; then `bun update <name>`, then `bun dedupe` |
|
|
327
339
|
| `bun run audit:refresh` | Delete `bun.lock` and reinstall. Last resort after `audit:fix`, `bun update <name>`, and `bun dedupe` — re-resolves every ranged dep (the framework pin included) and rewrites the lockfile as `lockfileVersion: 2` |
|
|
328
340
|
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
329
|
-
| `bun run lint:packaging` | Packaging surface checks —
|
|
341
|
+
| `bun run lint:packaging` | Packaging surface checks — env-var parity, `.mcpbignore` coverage, plugin manifests, published `skills/` tree (run by devcheck) |
|
|
330
342
|
| `bun run list-skills` | Print the skill registry |
|
|
331
343
|
| `bun run tree` | Generate directory structure doc |
|
|
332
344
|
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
@@ -347,7 +359,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
347
359
|
|
|
348
360
|
## Bundling
|
|
349
361
|
|
|
350
|
-
`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips
|
|
362
|
+
`npm run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. `mcpb pack` reads `.mcpbignore`, not `.gitignore`, so every root path the bundle must not ship — source, tests, docs, caches, logs, agent docs, plugin manifests, gitignored local files — needs a root-anchored line there (`/docs/`, never `docs/`, which also strips `node_modules/*/docs/`); `lint:packaging` names each missing or unanchored line. Root `skills/` ships on purpose. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips four classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`); platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on; node-gyp build output beside a `binding.gyp` (`config.gypi`, Makefiles, `obj.target/`, `.deps/`, object files and debug symbols), which records the packing machine's paths — compiled `*.node` addons stay; and build-only package files — the framework's `changelog/`, `scripts/`, `templates/`, `CLAUDE.md`, `AGENTS.md`, and config bases (`biome.json`, `vitest.config.base.mjs`, `config/tsconfig.base.json`), and `better-sqlite3`'s `deps/` and `src/` C sources. A server using DataCanvas therefore ships a portable bundle without the DuckDB native — `@duckdb/node-api` is an optional peer loaded lazily, so canvas tools report an actionable install hint and every other tool works normally. MCPB is stdio-only — HTTP and Cloudflare Workers deployments are unaffected. Consumers who don't need it can delete `manifest.json` and `.mcpbignore`; `lint:packaging` skips cleanly.
|
|
351
363
|
|
|
352
364
|
**Adding an env var requires both files:** `server.json` (registry discovery, `environmentVariables[]`) and `manifest.json` (bundle install UX, `mcp_config.env` + `user_config`). `lint:packaging` (run by `devcheck`) verifies the env var names match, that every `user_config` option is wired into `mcp_config.env` as `"X": "${user_config.X}"` (the host substitutes nothing else — `"${X}"` reaches the server as that literal string), and that an optional string option carries `"default": ""`.
|
|
353
365
|
|
package/Dockerfile
CHANGED
|
@@ -29,6 +29,7 @@ RUN --mount=type=cache,target=/root/.bun/install/cache \
|
|
|
29
29
|
|
|
30
30
|
# Copy the rest of the source code
|
|
31
31
|
COPY . .
|
|
32
|
+
RUN mkdir -p skills
|
|
32
33
|
|
|
33
34
|
# Build the application
|
|
34
35
|
RUN bun run build
|
|
@@ -138,6 +139,7 @@ COPY --from=deps /usr/src/app/node_modules ./node_modules
|
|
|
138
139
|
|
|
139
140
|
# Copy the compiled application code from the build stage
|
|
140
141
|
COPY --from=build /usr/src/app/dist ./dist
|
|
142
|
+
COPY --from=build /usr/src/app/skills ./skills
|
|
141
143
|
|
|
142
144
|
# eCFR mirror CLI (MirrorService — Tier 3). The shared context shim
|
|
143
145
|
# (_mirror-context.ts) is imported by the three named scripts, so it travels with
|
package/README.md
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
<h1>@cyanheads/federal-regulations-mcp-server</h1>
|
|
3
|
-
<p><b>Search and trace US federal rules across the Federal Register (proposed/final rules and
|
|
4
|
-
<div>7 Tools •
|
|
3
|
+
<p><b>Search and trace US federal rules across the Federal Register (proposed/final rules, notices, and presidential documents), the eCFR (codified, point-in-time CFR full text and amendment history, locally mirrored), and Regulations.gov (rulemaking dockets, document files, and public comments) via MCP. STDIO or Streamable HTTP.</b>
|
|
4
|
+
<div>7 Tools • 3 Resources</div>
|
|
5
5
|
</p>
|
|
6
6
|
</div>
|
|
7
7
|
|
|
8
8
|
<div align="center">
|
|
9
9
|
|
|
10
|
-
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/federal-regulations-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/federal-regulations-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
|
|
11
11
|
|
|
12
12
|
</div>
|
|
13
13
|
|
|
@@ -35,11 +35,11 @@ US federal regulations from the Federal Register, the eCFR, and Regulations.gov.
|
|
|
35
35
|
|
|
36
36
|
| Tool | Description |
|
|
37
37
|
|:---|:---|
|
|
38
|
-
| `regulations_search_rules` | Search Federal Register proposed rules, final rules, notices, and presidential documents by query, type, agency, date range, CFR part, docket number, and
|
|
39
|
-
| `regulations_get_document` | Fetch one Federal Register document by number, with the docket IDs, CFR parts, citation, comment count, and comment URL that chain into other tools |
|
|
40
|
-
| `regulations_browse_cfr` | List CFR titles, a title's chapters, or every section and appendix in a part,
|
|
38
|
+
| `regulations_search_rules` | Search Federal Register proposed rules, final rules, notices, and presidential documents by query, type, agency, date range, CFR part, docket number, RIN, significance, effective date, and executive order number, president, or signing date, or resolve a page cite to its document |
|
|
39
|
+
| `regulations_get_document` | Fetch one Federal Register document by number, with the docket IDs, CFR parts, citation, significance, comment count, and comment URL that chain into other tools |
|
|
40
|
+
| `regulations_browse_cfr` | List CFR titles, a title's chapters, or every section and appendix in a part, full-text-search the codified CFR, or list when a part's or section's text changed |
|
|
41
41
|
| `regulations_get_cfr_section` | Read codified CFR text for a section, whole part, or appendix, current or as of a past date |
|
|
42
|
-
| `regulations_get_docket` | Pull a rulemaking docket and its filed documents from Regulations.gov (key required) |
|
|
42
|
+
| `regulations_get_docket` | Pull a rulemaking docket and its filed documents from Regulations.gov, or read one document's files and attachments (key required) |
|
|
43
43
|
| `regulations_find_comments` | Fetch public comments on a document or docket, or one comment's full body and attachments (key required) |
|
|
44
44
|
| `regulations_list_open_comments` | List documents currently open for public comment, soonest closing first |
|
|
45
45
|
|
|
@@ -49,29 +49,32 @@ US federal regulations from the Federal Register, the eCFR, and Regulations.gov.
|
|
|
49
49
|
|:---|:---|
|
|
50
50
|
| `regulations://document/{documentNumber}` | One Federal Register document's metadata and cross-source handles |
|
|
51
51
|
| `regulations://cfr/{title}/{part}/{section}` | Codified text of a current CFR section |
|
|
52
|
+
| `skill://federal-regulations-guide/SKILL.md` | Guide to tracing rulemaking, CFR text, and public-comment evidence across sources |
|
|
52
53
|
|
|
53
|
-
|
|
54
|
+
The two data resources mirror `regulations_get_document` and `regulations_get_cfr_section`. The [federal-regulations guide](./skills/federal-regulations-guide/SKILL.md) also ships with plugin installs, npm, Docker, and the desktop bundle.
|
|
54
55
|
|
|
55
56
|
## Capability reference
|
|
56
57
|
|
|
57
58
|
### `regulations_search_rules` <sub>tool</sub>
|
|
58
59
|
|
|
59
|
-
- Optional full-text `query`, filtered by `type` (`PRORULE` / `RULE` / `NOTICE` / `PRESDOCU`), `agencies` (Federal Register slugs such as `environmental-protection-agency`, not names or acronyms), `published_after` / `published_before`, `cfr_title` + `cfr_part` (a part number or range such as `140-143`; `cfr_part` needs `cfr_title`, else `title_required_for_part`), `docket_id` (a docket number as the Federal Register prints it), and `
|
|
60
|
-
- `
|
|
61
|
-
-
|
|
60
|
+
- Optional full-text `query`, filtered by `type` (`PRORULE` / `RULE` / `NOTICE` / `PRESDOCU`), `agencies` (Federal Register slugs such as `environmental-protection-agency`, not names or acronyms), `published_after` / `published_before`, `cfr_title` + `cfr_part` (a part number or range such as `140-143`; `cfr_part` needs `cfr_title`, else `title_required_for_part`), `docket_id` (a docket number as the Federal Register prints it), `rin`, `significant` (the Federal Register's EO 12866 flag: `true` and `false` each match only documents with a determination), and `effective_after` / `effective_before`, all combined; `per_page` from 2 (default 20; above 100 serves 100 with a notice), `page` 1–50
|
|
61
|
+
- Presidential documents narrow by `executive_order_number` (bare digits, `14192`), `presidential_document_type` (`executive_order`, `proclamation`, `memorandum`, `determination`, `notice`, `presidential_order`, `other`), `president` (a slug such as `donald-trump`), and a `signed_after` / `signed_before` window, which differs from the publication window because signing precedes publication. These filters beside a `type` that leaves out `PRESDOCU`, or `significant` beside them or beside `type` of `PRESDOCU` alone, fail with `type_conflict`
|
|
62
|
+
- `citation` (`"89 FR 49102"`) with `citation_date` (the date its source note prints beside it) returns the documents printed on that page, in page order, volume 59 (1994) onward, narrowed by any other filter. A cite missing its date, or combined with the publication date window, fails with `citation_incomplete`; a volume before 59 or a date from another year fails with `citation_out_of_range`. When no document spans the page, the notice gives that day's page range
|
|
63
|
+
- Each result carries `documentNumber`, `citation` / `startPage` / `endPage`, `agencies[].slug`, the printed `docketIds`, `regulationsGovDocketId` and `regulationsGovDocumentId`, `commentCount`, `commentUrl`, `commentsCloseOn` with `commentPeriodOpen` (open through 11:59 PM Eastern on the close date), `regulationIdNumbers`, `significant` (null when no determination is recorded), `presidential` (`type`, `number`, `signingDate`, and `president`; null unless the document is a presidential document), and `cfrReferences` for the follow-up tools. `totalPages` and `nextPage` page the results. The Federal Register serves 50 pages, so `truncated` marks a set larger than 50 × `per_page` (1,000 at the default, 5,000 at 100); narrow the date window rather than paging deeper. `totalCount` stops at 10,000, which means at least that many. A window whose start falls after its end (publication, signing, or effective) fails with `date_range_inverted`, and `invalid_filter` names a rejected parameter
|
|
62
64
|
|
|
63
65
|
---
|
|
64
66
|
|
|
65
67
|
### `regulations_get_document` <sub>tool</sub>
|
|
66
68
|
|
|
67
|
-
- `document_number` in any form the Federal Register issues: `2024-07773` from 2010 on, and older and correction numbers such as `98-1572`, `E9-25990`, or `C1-2009-30484`; `include_full_text` adds the plain-text body as one window of `max_chars` (default 64,000,
|
|
68
|
-
- Returns metadata plus the handles other tools take: the Regulations.gov `docketId` and `regulationsGovDocumentId`, the printed `docketIds`, `citation` / `startPage` / `endPage`, `commentCount`, `commentUrl`, `commentPeriodOpen`, and `cfrReferences`. With text, `fullTextLength` and `fullTextNextOffset` (present while text remains) page the body; a major final rule runs past a million characters
|
|
69
|
+
- `document_number` in any form the Federal Register issues: `2024-07773` from 2010 on, and older and correction numbers such as `98-1572`, `E9-25990`, or `C1-2009-30484`; `include_full_text` adds the plain-text body as one window of `max_chars` (default 64,000; above 200,000 serves 200,000 with a notice) starting at `offset`, and passing either of those implies it
|
|
70
|
+
- Returns metadata plus the handles other tools take: the Regulations.gov `docketId` and `regulationsGovDocumentId`, the printed `docketIds`, `citation` / `startPage` / `endPage`, `commentCount`, `commentUrl`, `commentPeriodOpen`, `significant`, `presidential` for a presidential document, and `cfrReferences`. With text, `fullTextLength` and `fullTextNextOffset` (present while text remains) page the body; a major final rule runs past a million characters
|
|
69
71
|
|
|
70
72
|
---
|
|
71
73
|
|
|
72
74
|
### `regulations_browse_cfr` <sub>tool</sub>
|
|
73
75
|
|
|
74
|
-
- `mode: "structure"` lists the 50 titles, a title's top-level divisions, or, with `title` + `part`, every section and appendix in the part with its `subpart` and `subjectGroup`; `mode: "search"` full-text-searches the codified CFR and requires `query
|
|
76
|
+
- `mode: "structure"` lists the 50 titles, a title's top-level divisions, or, with `title` + `part`, every section and appendix in the part with its `subpart` and `subjectGroup`; `mode: "search"` full-text-searches the codified CFR and requires `query`; `mode: "versions"` lists the dates a part's or one section's text changed. `title`, `part` (needs `title`), and a point-in-time `date` scope structure and search, and `per_page` from 1 (default 20; above 50 serves 50 with a notice) pages search results, part listings, and versions
|
|
77
|
+
- Versions mode takes `title` with `part` (and optionally `section`, written as `regulations_get_cfr_section` accepts it) or with `changed_since` (`YYYY-MM-DD`: versions published by an eCFR issue on or after it, across the whole title when no `part` is given); any other scope fails with `versions_scope_required`, and a `section` citing another title fails with `conflicting_title`. `versions[]` rows carry `cfrCite`, `heading`, `part`, `subpart`, `date`, `issueDate`, `substantive`, and `removed`, in eCFR's order (by identifier, oldest first within each), and `latestAmendmentDate` covers the whole filtered set. Pass a row's `date` as `date` to `regulations_get_cfr_section` to read that version: a row dated before 2017-01-01 reads at 2017-01-01, and a removed row's date reads nothing
|
|
75
78
|
- Search rows carry `cfrCite`, `heading`, `hierarchyPath`, and `excerpt`, one per section. `source` (`mirror` / `live`) and `sourceScope` name the corpus that answered and what it covers, and `countBasis` says whether `totalCount` counts `sections` or `section_versions`; live search reaches eCFR's first 10,000 hits only (`page_out_of_window` past them)
|
|
76
79
|
|
|
77
80
|
---
|
|
@@ -79,7 +82,8 @@ Both resources mirror a tool (`regulations_get_document`, `regulations_get_cfr_s
|
|
|
79
82
|
### `regulations_get_cfr_section` <sub>tool</sub>
|
|
80
83
|
|
|
81
84
|
- One section (`title` + `part` + `section`), a whole part (`section` omitted), or one appendix (`appendix`, verbatim as `regulations_browse_cfr` emits it, e.g. `Appendix A-1 to Part 50`). `section` also takes cites as people write them (`"61"`, `"§ 141.61"`, `"141.61(c)"`) and the `cfrCite` the server returns (`"40 CFR 141.61"`, `"14 CFR 241 § 25"`; a cite naming another title fails with `conflicting_title`), `part` takes `"Part 141"`, and `date` reads text from 2017-01-01 through the title's up-to-date date
|
|
82
|
-
- Text comes back as one `bodyText` window (`max_chars` default 64,000,
|
|
85
|
+
- Text comes back as one `bodyText` window (`max_chars` default 64,000, above 200,000 serves 200,000 with a notice, from `offset`), paged by `bodyTextLength` and `bodyTextNextOffset`. A whole-part read adds a `sections[]` index with each section's `offset` and names its `appendices` without their text; `source` (`mirror` / `live`) reports provenance
|
|
86
|
+
- `hierarchyPath` runs from the title down to the location read. If eCFR cannot supply it, the read still answers, with only the cited levels (`Title 40 › Part 141 › § 141.61`), and `notice` says so
|
|
83
87
|
- A whole-part read also returns the part's `heading`, `authority`, `sourceNote`, and `notes`, and each `sections[]` entry carries the Authority or Source its subpart or subject group states for it
|
|
84
88
|
- Superscripts read `^x` and subscripts `_x` (`3 × 10^−8`, `CO_{2}e`), footnote markers `[n]`, and diacritics and overlines are combining marks (`x̄`)
|
|
85
89
|
|
|
@@ -87,23 +91,26 @@ Both resources mirror a tool (`regulations_get_document`, `regulations_get_cfr_s
|
|
|
87
91
|
|
|
88
92
|
### `regulations_get_docket` <sub>tool</sub> · key required
|
|
89
93
|
|
|
90
|
-
-
|
|
91
|
-
-
|
|
94
|
+
- Exactly one of `docket_id` (list mode) or `document_id` (detail mode): neither fails with `target_required`, both with `multiple_targets`, and `search_term` or `document_types` beside `document_id` with `filter_requires_list_mode`. IDs are case-insensitive
|
|
95
|
+
- List mode takes `docket_id`, the Regulations.gov docket ID (e.g. `EPA-HQ-OAR-2025-0194`) — `regulationsGovDocketId` on a search or open-comments row, `docketId` from `regulations_get_document`, not a printed `docketIds` entry. `search_term` keeps the documents whose text matches, ranked by relevance instead of newest first; `document_types` filters to `Proposed Rule`, `Rule`, `Notice`, `Supporting & Related Material`, or `Other`, and combines with it; `per_page` from 5 (default 25; above 250 serves 250 with a notice), `page` 1–40
|
|
96
|
+
- List mode returns the docket's metadata, `documentCount`, and `documents[]`, each with an `objectId` for `regulations_find_comments`, a `frDocNum` back to `regulations_get_document`, and `commentPeriodOpen` as Regulations.gov reports it. `totalPages` and `nextPage` page the documents; Regulations.gov serves 40 pages, so `truncated` marks a docket larger than 40 × `per_page` (10,000 at 250)
|
|
97
|
+
- Detail mode takes `document_id` (`documentId` from a listing, or `regulationsGovDocumentId` from `regulations_get_document`) and returns one `document` with `fileFormats` (the main file's download URLs), `attachments` in upload order with withheld ones kept, `pageCount`, `abstract`, and `restrictReasonType`. A document whose content is only in attachments, or that has no file at all, gets a notice saying so
|
|
92
98
|
|
|
93
99
|
---
|
|
94
100
|
|
|
95
101
|
### `regulations_find_comments` <sub>tool</sub> · key required
|
|
96
102
|
|
|
97
|
-
- Exactly one of `docket_id`, `document_object_id`, `fr_document_number`, or `comment_id`; list scopes take `per_page` 5
|
|
98
|
-
- `document_object_id` takes an object ID (`0900006485883ec6`) or a document ID (`EPA-HQ-OW-2022-0114-0027`). `fr_document_number` resolves to the Regulations.gov document carrying that exact number and answers `not_found` when none does
|
|
103
|
+
- Exactly one of `docket_id`, `document_object_id`, `fr_document_number`, or `comment_id`; list scopes take `per_page` from 5 (default 25; above 250 serves 250 with a notice) and `page` 1–40
|
|
104
|
+
- `document_object_id` takes an object ID (`0900006485883ec6`) or a document ID (`EPA-HQ-OW-2022-0114-0027`). `fr_document_number` resolves to the Regulations.gov document carrying that exact number and answers `not_found` when none does. Docket, document, and comment IDs are case-insensitive
|
|
105
|
+
- A `docket_id` that lists no comments is looked up: a docket Regulations.gov does not hold (a printed docket number such as `REG-101355-26`) answers `not_found`, and an existing docket answers an empty list with a notice
|
|
99
106
|
- Lists narrow by comment text with `search_term`, and each hit then carries `highlightedContent`, the matched passages. `posted_after` / `posted_before` set an inclusive posted-date window. A backwards window fails with `date_range_inverted`, and filters passed with `comment_id` fail with `filter_requires_list_mode`
|
|
100
|
-
- `mode` is `list` or `detail`. Lists return comment summaries without body text. `comment_id` returns the body, submitter, `receivedDate`, `postmarkDate`, `duplicateComments` (above 1 marks a mass-mail campaign record), and `attachments
|
|
107
|
+
- `mode` is `list` or `detail`. Lists return comment summaries without body text. `comment_id` returns the body, submitter, `receivedDate`, `postmarkDate`, `duplicateComments` (above 1 marks a mass-mail campaign record), and `attachments` in upload order, with `attachmentOnly: true` when the substance is in a PDF/DOCX file. An attachment whose file is withheld stays in the list with empty `formats` and its `restrictReasonType` (e.g. `Copyrighted`). Lists carry `totalPages` and `nextPage`; `truncated` marks a set larger than the 40 pages Regulations.gov serves reach (40 × `per_page`, 10,000 at 250), and posted-date windows take it one slice at a time
|
|
101
108
|
|
|
102
109
|
---
|
|
103
110
|
|
|
104
111
|
### `regulations_list_open_comments` <sub>tool</sub>
|
|
105
112
|
|
|
106
|
-
- Optional `query`, `type` (`PRORULE`, `RULE`, `NOTICE`; default `["PRORULE", "RULE"]`), `agencies` (Federal Register slugs), and `closing_before`; `per_page` 1
|
|
113
|
+
- Optional `query`, `type` (`PRORULE`, `RULE`, `NOTICE`; default `["PRORULE", "RULE"]`), `agencies` (Federal Register slugs), and `closing_before`; `per_page` from 1 (default 20; above 100 serves 100 with a notice)
|
|
107
114
|
- Rows sort by closing date, soonest first, and carry `commentsCloseOn`, `daysRemaining`, `documentNumber`, the printed `docketIds`, `regulationsGovDocketId` and `regulationsGovDocumentId`, `commentCount`, and `commentUrl`. `asOf` is today's date in Eastern time, so a document stays listed through its close day. `totalPages` and `nextPage` page the window; `truncated` means the Federal Register's 10,000-document limit was reached
|
|
108
115
|
- Keyless. `keyed` reports whether `REGULATIONS_GOV_API_KEY` is set, which `regulations_get_docket` and `regulations_find_comments` need to follow up on a row
|
|
109
116
|
|
|
@@ -119,7 +126,7 @@ Both resources mirror a tool (`regulations_get_document`, `regulations_get_cfr_s
|
|
|
119
126
|
### `regulations://cfr/{title}/{part}/{section}` <sub>resource</sub>
|
|
120
127
|
|
|
121
128
|
- Sections only, at the current date and the tool's default 64,000-character window; the `part` and `section` segments resolve the way the tool resolves them (`"Part 141"`; `"61"`, `"§ 141.61"`, `"40 CFR 141.61"`)
|
|
122
|
-
- `source` (`mirror` / `live`) reports provenance. `bodyTextNextOffset` marks a section longer than the window; read the rest through `regulations_get_cfr_section` with `offset`
|
|
129
|
+
- `source` (`mirror` / `live`) reports provenance, and `notice` says how a part or section written another way resolved and when `hierarchyPath` holds only the cited levels. `bodyTextNextOffset` marks a section longer than the window; read the rest through `regulations_get_cfr_section` with `offset`
|
|
123
130
|
|
|
124
131
|
## Features
|
|
125
132
|
|
|
@@ -141,140 +148,32 @@ Agent-friendly output:
|
|
|
141
148
|
|
|
142
149
|
## Getting started
|
|
143
150
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
A public instance is available at `https://federal-regulations.caseyjhand.com/mcp` — no installation required. It serves Streamable HTTP; each client takes its own config shape.
|
|
147
|
-
|
|
148
|
-
For Claude Code:
|
|
151
|
+
Connect to the hosted instance:
|
|
149
152
|
|
|
150
153
|
```sh
|
|
151
154
|
claude mcp add --transport http federal-regulations-mcp-server https://federal-regulations.caseyjhand.com/mcp
|
|
152
155
|
```
|
|
153
156
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
```json
|
|
157
|
-
{
|
|
158
|
-
"mcpServers": {
|
|
159
|
-
"federal-regulations-mcp-server": {
|
|
160
|
-
"type": "streamableHttp",
|
|
161
|
-
"url": "https://federal-regulations.caseyjhand.com/mcp"
|
|
162
|
-
}
|
|
163
|
-
}
|
|
164
|
-
}
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
For Cursor (`mcp.json`):
|
|
168
|
-
|
|
169
|
-
```json
|
|
170
|
-
{
|
|
171
|
-
"mcpServers": {
|
|
172
|
-
"federal-regulations-mcp-server": {
|
|
173
|
-
"url": "https://federal-regulations.caseyjhand.com/mcp"
|
|
174
|
-
}
|
|
175
|
-
}
|
|
176
|
-
}
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
Claude Desktop adds remote servers under Settings → Connectors.
|
|
180
|
-
|
|
181
|
-
### Self-Hosted / Local
|
|
157
|
+
Or run it locally:
|
|
182
158
|
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
```json
|
|
186
|
-
{
|
|
187
|
-
"mcpServers": {
|
|
188
|
-
"federal-regulations-mcp-server": {
|
|
189
|
-
"type": "stdio",
|
|
190
|
-
"command": "bunx",
|
|
191
|
-
"args": ["@cyanheads/federal-regulations-mcp-server@latest"],
|
|
192
|
-
"env": {
|
|
193
|
-
"MCP_TRANSPORT_TYPE": "stdio",
|
|
194
|
-
"MCP_LOG_LEVEL": "info",
|
|
195
|
-
"REGULATIONS_GOV_API_KEY": "your-key-here"
|
|
196
|
-
}
|
|
197
|
-
}
|
|
198
|
-
}
|
|
199
|
-
}
|
|
159
|
+
```sh
|
|
160
|
+
claude mcp add federal-regulations-mcp-server -- npx -y @cyanheads/federal-regulations-mcp-server
|
|
200
161
|
```
|
|
201
162
|
|
|
202
|
-
|
|
163
|
+
For other clients, add this to your MCP configuration file:
|
|
203
164
|
|
|
204
165
|
```json
|
|
205
166
|
{
|
|
206
167
|
"mcpServers": {
|
|
207
168
|
"federal-regulations-mcp-server": {
|
|
208
|
-
"type": "stdio",
|
|
209
169
|
"command": "npx",
|
|
210
|
-
"args": ["-y", "@cyanheads/federal-regulations-mcp-server
|
|
211
|
-
"env": {
|
|
212
|
-
"MCP_TRANSPORT_TYPE": "stdio",
|
|
213
|
-
"MCP_LOG_LEVEL": "info",
|
|
214
|
-
"REGULATIONS_GOV_API_KEY": "your-key-here"
|
|
215
|
-
}
|
|
216
|
-
}
|
|
217
|
-
}
|
|
218
|
-
}
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
Or with Docker:
|
|
222
|
-
|
|
223
|
-
```json
|
|
224
|
-
{
|
|
225
|
-
"mcpServers": {
|
|
226
|
-
"federal-regulations-mcp-server": {
|
|
227
|
-
"type": "stdio",
|
|
228
|
-
"command": "docker",
|
|
229
|
-
"args": [
|
|
230
|
-
"run", "-i", "--rm",
|
|
231
|
-
"-e", "MCP_TRANSPORT_TYPE=stdio",
|
|
232
|
-
"-e", "REGULATIONS_GOV_API_KEY=your-key-here",
|
|
233
|
-
"ghcr.io/cyanheads/federal-regulations-mcp-server:latest"
|
|
234
|
-
]
|
|
170
|
+
"args": ["-y", "@cyanheads/federal-regulations-mcp-server"]
|
|
235
171
|
}
|
|
236
172
|
}
|
|
237
173
|
}
|
|
238
174
|
```
|
|
239
175
|
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
```sh
|
|
243
|
-
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
|
|
244
|
-
# Server listens at http://localhost:3010/mcp
|
|
245
|
-
```
|
|
246
|
-
|
|
247
|
-
### Prerequisites
|
|
248
|
-
|
|
249
|
-
- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
|
|
250
|
-
- Optional: a free [api.data.gov key](https://api.data.gov/signup/) for the Regulations.gov tools.
|
|
251
|
-
|
|
252
|
-
### Installation
|
|
253
|
-
|
|
254
|
-
1. **Clone the repository:**
|
|
255
|
-
|
|
256
|
-
```sh
|
|
257
|
-
git clone https://github.com/cyanheads/federal-regulations-mcp-server.git
|
|
258
|
-
```
|
|
259
|
-
|
|
260
|
-
2. **Navigate into the directory:**
|
|
261
|
-
|
|
262
|
-
```sh
|
|
263
|
-
cd federal-regulations-mcp-server
|
|
264
|
-
```
|
|
265
|
-
|
|
266
|
-
3. **Install dependencies:**
|
|
267
|
-
|
|
268
|
-
```sh
|
|
269
|
-
bun install
|
|
270
|
-
```
|
|
271
|
-
|
|
272
|
-
4. **Configure environment:**
|
|
273
|
-
|
|
274
|
-
```sh
|
|
275
|
-
cp .env.example .env
|
|
276
|
-
# optionally set REGULATIONS_GOV_API_KEY
|
|
277
|
-
```
|
|
176
|
+
Set optional `REGULATIONS_GOV_API_KEY` to enable docket and comment tools; get a free key at [api.data.gov/signup](https://api.data.gov/signup/). The Federal Register and eCFR tools work without it. For Docker or a source build, see [Running the server](#running-the-server).
|
|
278
177
|
|
|
279
178
|
## Configuration
|
|
280
179
|
|
|
@@ -287,6 +186,7 @@ cp .env.example .env
|
|
|
287
186
|
| `ECFR_MIRROR_PATH` | Path to the eCFR SQLite mirror database. | `./data/ecfr-mirror.sqlite` |
|
|
288
187
|
| `ECFR_MIRROR_REFRESH_CRON` | Cron expression for an in-process mirror refresh (HTTP transport only), e.g. `0 4 * * 0`. Each run re-harvests every configured title in full. | none (no job) |
|
|
289
188
|
| `ECFR_MIRROR_TITLES` | Comma-separated CFR titles to mirror (e.g. `21,40`). Reads and searches outside the set, and all-titles searches, go to the live eCFR API. | all 50 titles |
|
|
189
|
+
| `REGULATIONS_CLAMP_LIMITS` | Serve a `per_page` or `max_chars` above its ceiling at the ceiling, with a notice. `false` advertises the ceiling as a schema maximum and rejects a larger value instead. | `true` |
|
|
290
190
|
| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
|
|
291
191
|
| `MCP_HTTP_PORT` | HTTP server port. | `3010` |
|
|
292
192
|
| `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth`. | `none` |
|
|
@@ -300,6 +200,14 @@ See [`.env.example`](./.env.example) for the full list of optional overrides.
|
|
|
300
200
|
|
|
301
201
|
### Local development
|
|
302
202
|
|
|
203
|
+
Requires Bun v1.4.0 or higher (or Node.js v24+).
|
|
204
|
+
|
|
205
|
+
```sh
|
|
206
|
+
git clone https://github.com/cyanheads/federal-regulations-mcp-server.git
|
|
207
|
+
cd federal-regulations-mcp-server && bun install
|
|
208
|
+
cp .env.example .env
|
|
209
|
+
```
|
|
210
|
+
|
|
303
211
|
- **Build and run:**
|
|
304
212
|
|
|
305
213
|
```sh
|
|
@@ -330,8 +238,7 @@ See [`.env.example`](./.env.example) for the full list of optional overrides.
|
|
|
330
238
|
### Docker
|
|
331
239
|
|
|
332
240
|
```sh
|
|
333
|
-
docker
|
|
334
|
-
docker run --rm -e REGULATIONS_GOV_API_KEY=your-key -p 3010:3010 federal-regulations-mcp-server
|
|
241
|
+
docker run --rm -e REGULATIONS_GOV_API_KEY=your-key -p 3010:3010 ghcr.io/cyanheads/federal-regulations-mcp-server:latest
|
|
335
242
|
```
|
|
336
243
|
|
|
337
244
|
The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/federal-regulations-mcp-server`. Build the mirror inside a running container with `docker exec <container> bun run mirror:init`, and mount a volume over `/usr/src/app/data` so it survives recreation. OpenTelemetry peer dependencies are installed by default; build with `--build-arg OTEL_ENABLED=false` to omit them.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
summary: "Publish a regulatory research guide over MCP, adopt mcp-ts-core 0.13.18, and repair desktop bundle packaging."
|
|
3
|
+
breaking: false
|
|
4
|
+
security: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 0.6.0 — 2026-10-28
|
|
8
|
+
|
|
9
|
+
## Added
|
|
10
|
+
|
|
11
|
+
- Add the federal-regulations-guide skill as an MCP resource for tracing rules, CFR text, and public comments.
|
|
12
|
+
- **Agent Plugins metadata** — add root `plugin.json` and `mcp.json` alongside the client overlays.
|
|
13
|
+
|
|
14
|
+
## Changed
|
|
15
|
+
|
|
16
|
+
- **Guide delivery** — include the published skill in npm, Docker, and desktop bundles.
|
|
17
|
+
- **Development guidance** — sync framework skills and tooling, consolidate the bug-report environment fields, and shorten installation examples.
|
|
18
|
+
- **Comment documentation** — distinguish list metadata from comment-detail bodies and attachment URLs.
|
|
19
|
+
- **Dependency release age** — use the framework's one-day installation floor.
|
|
20
|
+
|
|
21
|
+
## Fixed
|
|
22
|
+
|
|
23
|
+
- **Desktop bundles** — preserve SDK runtime skill modules while pruning dependency agent docs, node-gyp output, and build-only package files; exclude source, tests, caches, logs, and development metadata from the bundle root.
|
|
24
|
+
|
|
25
|
+
## Dependencies
|
|
26
|
+
|
|
27
|
+
- `@cyanheads/mcp-ts-core` 0.13.16 → 0.13.18: HTTP request retention fix from 0.13.17; MCP skill serving from 0.13.18.
|
|
28
|
+
- `@biomejs/biome` 2.6.2 → 2.6.3.
|
|
29
|
+
- `ignore` ^7.0.13 → ^7.0.14.
|
|
30
|
+
- `tsc-alias` ^1.9.8 → ^1.9.9.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
---
|
|
2
|
+
summary: "Search executive orders and other presidential documents by number, president, and signing date, list a CFR section's amendment dates, search a docket's documents for file downloads, and clamp oversized page sizes instead of rejecting them."
|
|
3
|
+
breaking: false
|
|
4
|
+
security: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 0.6.1 — 2026-10-29
|
|
8
|
+
|
|
9
|
+
## Added
|
|
10
|
+
|
|
11
|
+
- **`regulations_search_rules` filters** — `executive_order_number`, `presidential_document_type`, `president`, `signed_after`/`signed_before`, `significant`, and `effective_after`/`effective_before`. A combination that cannot match (an executive-order filter with `type: RULE`) answers `type_conflict` before any request (#66).
|
|
12
|
+
- **`significant` and `presidential`** — on `regulations_get_document`, search rows, and the `document` resource: `significant` is a boolean or null; `presidential` carries type, number, signing date, and president, and is null for non-presidential documents (#66).
|
|
13
|
+
- **`regulations_browse_cfr` `mode: "versions"`** — lists the dates a part's or one section's codified text changed (`section`, `changed_since`); each date reads through `regulations_get_cfr_section`'s `date` (#67).
|
|
14
|
+
- **`regulations_get_docket` `search_term`** — relevance-ranked document search within a docket (#68).
|
|
15
|
+
- **`regulations_get_docket` `document_id`** — detail mode returning the document's file download links (format, size, page count) and attachments (#68).
|
|
16
|
+
- **`REGULATIONS_CLAMP_LIMITS`** — `false` restores strict rejection of an over-ceiling `per_page` or `max_chars` (#70).
|
|
17
|
+
|
|
18
|
+
## Changed
|
|
19
|
+
|
|
20
|
+
- **`per_page` and `max_chars` ceilings** — a value above a tool's ceiling is served at the ceiling with a notice naming the requested and applied values, on all seven tools; it was rejected with a validation error (#70).
|
|
21
|
+
- **`regulations_search_rules` truncation guidance** — names the new filters.
|
|
22
|
+
- **Documentation** — the README, design doc, and published guide skill describe the new surface.
|
|
23
|
+
|
|
24
|
+
## Fixed
|
|
25
|
+
|
|
26
|
+
- **`regulations_find_comments` unknown docket** — a docket Regulations.gov does not hold answers `not_found`; it returned an empty success (#69).
|
|
27
|
+
- **Lowercase Regulations.gov IDs** — `regulations_get_docket`'s `docket_id` and `regulations_find_comments`' `comment_id` and `document_object_id` (a document ID) resolve a lowercase ID; they answered `not_found` (#69).
|
|
28
|
+
- **`regulations_get_cfr_section` hierarchy failure** — when eCFR's hierarchy lookup fails, the tool and the `cfr-section` resource return the text with a path built from the cited levels (`Title 40 › Part 141 › § 141.61`) and a notice; the path was a bare `Title 40` with no notice. The lookup gets one attempt of at most 8 seconds (#71).
|
|
29
|
+
- **`regulations_find_comments` attachments** — every attachment is listed in upload order (`docOrder`), including ones with no downloadable file (`formats: []` plus `restrictReasonType`, e.g. `Copyrighted`); those were dropped and the rest listed in the order Regulations.gov returned them (#73).
|
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
* @fileoverview Server-specific environment configuration for
|
|
3
3
|
* federal-regulations-mcp-server. Lazy-parsed Zod schema, separate from the
|
|
4
4
|
* framework's own config. Maps the three data-source base URLs, the optional
|
|
5
|
-
* Regulations.gov API key,
|
|
5
|
+
* Regulations.gov API key, the eCFR mirror settings, and whether an over-ceiling
|
|
6
|
+
* page size or text window is clamped or rejected.
|
|
6
7
|
*
|
|
7
8
|
* `REGULATIONS_GOV_API_KEY` is optional: the keyless core (Federal Register +
|
|
8
9
|
* eCFR tools) is a complete deployment without it. The two Regulations.gov tools
|
|
@@ -20,6 +21,7 @@ declare const ServerConfigSchema: z.ZodObject<{
|
|
|
20
21
|
ecfrMirrorPath: z.ZodDefault<z.ZodString>;
|
|
21
22
|
ecfrMirrorRefreshCron: z.ZodOptional<z.ZodString>;
|
|
22
23
|
ecfrMirrorTitles: z.ZodOptional<z.ZodString>;
|
|
24
|
+
clampLimits: z.ZodDefault<z.ZodCodec<z.ZodString, z.ZodBoolean>>;
|
|
23
25
|
}, z.core.$strip>;
|
|
24
26
|
export type ServerConfig = z.infer<typeof ServerConfigSchema>;
|
|
25
27
|
/**
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;;;;;;iBAuCtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAY9C"}
|