@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.
Files changed (92) hide show
  1. package/AGENTS.md +21 -9
  2. package/CLAUDE.md +21 -9
  3. package/Dockerfile +2 -0
  4. package/README.md +46 -139
  5. package/changelog/0.6.x/0.6.0.md +30 -0
  6. package/changelog/0.6.x/0.6.1.md +29 -0
  7. package/dist/config/server-config.d.ts +3 -1
  8. package/dist/config/server-config.d.ts.map +1 -1
  9. package/dist/config/server-config.js +7 -1
  10. package/dist/config/server-config.js.map +1 -1
  11. package/dist/index.js +2 -1
  12. package/dist/index.js.map +1 -1
  13. package/dist/mcp-server/resources/definitions/cfr-section.resource.d.ts.map +1 -1
  14. package/dist/mcp-server/resources/definitions/cfr-section.resource.js +6 -4
  15. package/dist/mcp-server/resources/definitions/cfr-section.resource.js.map +1 -1
  16. package/dist/mcp-server/resources/definitions/document.resource.js +1 -1
  17. package/dist/mcp-server/resources/definitions/document.resource.js.map +1 -1
  18. package/dist/mcp-server/tools/definitions/browse-cfr.tool.d.ts +41 -8
  19. package/dist/mcp-server/tools/definitions/browse-cfr.tool.d.ts.map +1 -1
  20. package/dist/mcp-server/tools/definitions/browse-cfr.tool.js +189 -40
  21. package/dist/mcp-server/tools/definitions/browse-cfr.tool.js.map +1 -1
  22. package/dist/mcp-server/tools/definitions/find-comments.tool.d.ts +6 -3
  23. package/dist/mcp-server/tools/definitions/find-comments.tool.d.ts.map +1 -1
  24. package/dist/mcp-server/tools/definitions/find-comments.tool.js +64 -39
  25. package/dist/mcp-server/tools/definitions/find-comments.tool.js.map +1 -1
  26. package/dist/mcp-server/tools/definitions/format-utils.d.ts +17 -0
  27. package/dist/mcp-server/tools/definitions/format-utils.d.ts.map +1 -1
  28. package/dist/mcp-server/tools/definitions/format-utils.js +36 -1
  29. package/dist/mcp-server/tools/definitions/format-utils.js.map +1 -1
  30. package/dist/mcp-server/tools/definitions/get-cfr-section.tool.d.ts +1 -1
  31. package/dist/mcp-server/tools/definitions/get-cfr-section.tool.d.ts.map +1 -1
  32. package/dist/mcp-server/tools/definitions/get-cfr-section.tool.js +19 -15
  33. package/dist/mcp-server/tools/definitions/get-cfr-section.tool.js.map +1 -1
  34. package/dist/mcp-server/tools/definitions/get-docket.tool.d.ts +67 -16
  35. package/dist/mcp-server/tools/definitions/get-docket.tool.d.ts.map +1 -1
  36. package/dist/mcp-server/tools/definitions/get-docket.tool.js +224 -56
  37. package/dist/mcp-server/tools/definitions/get-docket.tool.js.map +1 -1
  38. package/dist/mcp-server/tools/definitions/get-document.tool.d.ts +11 -1
  39. package/dist/mcp-server/tools/definitions/get-document.tool.d.ts.map +1 -1
  40. package/dist/mcp-server/tools/definitions/get-document.tool.js +20 -13
  41. package/dist/mcp-server/tools/definitions/get-document.tool.js.map +1 -1
  42. package/dist/mcp-server/tools/definitions/index.d.ts +287 -170
  43. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  44. package/dist/mcp-server/tools/definitions/list-open-comments.tool.d.ts +1 -1
  45. package/dist/mcp-server/tools/definitions/list-open-comments.tool.d.ts.map +1 -1
  46. package/dist/mcp-server/tools/definitions/list-open-comments.tool.js +12 -14
  47. package/dist/mcp-server/tools/definitions/list-open-comments.tool.js.map +1 -1
  48. package/dist/mcp-server/tools/definitions/presidential-schema.d.ts +17 -0
  49. package/dist/mcp-server/tools/definitions/presidential-schema.d.ts.map +1 -0
  50. package/dist/mcp-server/tools/definitions/presidential-schema.js +31 -0
  51. package/dist/mcp-server/tools/definitions/presidential-schema.js.map +1 -0
  52. package/dist/mcp-server/tools/definitions/search-rules.tool.d.ts +35 -3
  53. package/dist/mcp-server/tools/definitions/search-rules.tool.d.ts.map +1 -1
  54. package/dist/mcp-server/tools/definitions/search-rules.tool.js +144 -28
  55. package/dist/mcp-server/tools/definitions/search-rules.tool.js.map +1 -1
  56. package/dist/mcp-server/tools/definitions/size-limit.d.ts +50 -0
  57. package/dist/mcp-server/tools/definitions/size-limit.d.ts.map +1 -0
  58. package/dist/mcp-server/tools/definitions/size-limit.js +93 -0
  59. package/dist/mcp-server/tools/definitions/size-limit.js.map +1 -0
  60. package/dist/services/ecfr/ecfr-service.d.ts +50 -6
  61. package/dist/services/ecfr/ecfr-service.d.ts.map +1 -1
  62. package/dist/services/ecfr/ecfr-service.js +128 -12
  63. package/dist/services/ecfr/ecfr-service.js.map +1 -1
  64. package/dist/services/ecfr/read-section.d.ts +12 -3
  65. package/dist/services/ecfr/read-section.d.ts.map +1 -1
  66. package/dist/services/ecfr/read-section.js +12 -5
  67. package/dist/services/ecfr/read-section.js.map +1 -1
  68. package/dist/services/ecfr/types.d.ts +68 -0
  69. package/dist/services/ecfr/types.d.ts.map +1 -1
  70. package/dist/services/federal-register/federal-register-service.d.ts +2 -1
  71. package/dist/services/federal-register/federal-register-service.d.ts.map +1 -1
  72. package/dist/services/federal-register/federal-register-service.js +82 -12
  73. package/dist/services/federal-register/federal-register-service.js.map +1 -1
  74. package/dist/services/federal-register/types.d.ts +52 -2
  75. package/dist/services/federal-register/types.d.ts.map +1 -1
  76. package/dist/services/federal-register/types.js +10 -1
  77. package/dist/services/federal-register/types.js.map +1 -1
  78. package/dist/services/regulations-gov/regulations-gov-service.d.ts +21 -2
  79. package/dist/services/regulations-gov/regulations-gov-service.d.ts.map +1 -1
  80. package/dist/services/regulations-gov/regulations-gov-service.js +86 -13
  81. package/dist/services/regulations-gov/regulations-gov-service.js.map +1 -1
  82. package/dist/services/regulations-gov/types.d.ts +58 -15
  83. package/dist/services/regulations-gov/types.d.ts.map +1 -1
  84. package/dist/services/request-budget.d.ts +2 -2
  85. package/dist/services/request-budget.js +2 -2
  86. package/dist/services/upstream-failure.d.ts +5 -0
  87. package/dist/services/upstream-failure.d.ts.map +1 -1
  88. package/dist/services/upstream-failure.js +1 -0
  89. package/dist/services/upstream-failure.js.map +1 -1
  90. package/package.json +7 -6
  91. package/server.json +17 -3
  92. 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.4
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `0.13.16`
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.3.1
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, and one scaffolded script diverges because of it.** `tsconfig.json` includes `scripts/**/*` and `tests/**/*`, so `tsc --noEmit` reads every hand-written file — the mirror lifecycle scripts ship in `package.json` `files[]` and into the Docker runtime stage, so they are production code. `scripts/lint-mcp.ts` therefore drops the scaffold's `catch` branch importing `../src/linter/validate.js`: that path resolves only inside the framework's own repo, where the script also lives, so in this project the branch is unreachable and its type annotation cannot resolve. The `maintenance` skill re-syncs framework scripts by overwrite; re-drop the branch after a sync rather than narrowing the typecheck to hide it.
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
- Skills are modular instructions in `framework-skills/` at the project root. 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. The 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 these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
270
+ Two skill trees live at the project root, written for different readers:
269
271
 
270
- **Agent skill directory:** Copy 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.
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 — `server.json`/`manifest.json` env-var parity (run by devcheck) |
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 two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. 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.
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.4
5
- **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `0.13.16`
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.3.1
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, and one scaffolded script diverges because of it.** `tsconfig.json` includes `scripts/**/*` and `tests/**/*`, so `tsc --noEmit` reads every hand-written file — the mirror lifecycle scripts ship in `package.json` `files[]` and into the Docker runtime stage, so they are production code. `scripts/lint-mcp.ts` therefore drops the scaffold's `catch` branch importing `../src/linter/validate.js`: that path resolves only inside the framework's own repo, where the script also lives, so in this project the branch is unreachable and its type annotation cannot resolve. The `maintenance` skill re-syncs framework scripts by overwrite; re-drop the branch after a sync rather than narrowing the typecheck to hide it.
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
- Skills are modular instructions in `framework-skills/` at the project root. 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. The 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 these development skills to every agent that installs it. Keep `skills/` free for skills meant for those agents.
270
+ Two skill trees live at the project root, written for different readers:
269
271
 
270
- **Agent skill directory:** Copy 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.
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 — `server.json`/`manifest.json` env-var parity (run by devcheck) |
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 two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was packed on. 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.
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 notices), the eCFR (codified, point-in-time CFR full text, locally mirrored), and Regulations.gov (rulemaking dockets and public comments) via MCP. STDIO or Streamable HTTP.</b>
4
- <div>7 Tools • 2 Resources</div>
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
- [![Version](https://img.shields.io/badge/Version-0.5.4-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/federal-regulations-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/federal-regulations-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/federal-regulations-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4-blueviolet.svg?style=flat-square)](https://bun.sh/)
10
+ [![Version](https://img.shields.io/badge/Version-0.6.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/federal-regulations-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.4.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/federal-regulations-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/federal-regulations-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4-blueviolet.svg?style=flat-square)](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 RIN, 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, 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, or full-text-search the codified CFR |
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
- Both resources mirror a tool (`regulations_get_document`, `regulations_get_cfr_section`), so tool-only clients lose nothing.
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 `rin`, all combined; `per_page` 2–100 (default 20), `page` 1–50
60
- - `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. A cite missing its date, or combined with the 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
61
- - 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`, 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 fails with `date_range_inverted`, and `invalid_filter` names a rejected parameter
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, max 200,000) starting at `offset`, and passing either of those implies it
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`. `title`, `part` (needs `title`), and a point-in-time `date` scope both modes, and `per_page` 1–50 (default 20) pages search results and part listings
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, max 200,000, 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
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
- - `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; `document_types` filters to `Proposed Rule`, `Rule`, `Notice`, `Supporting & Related Material`, or `Other`; `per_page` 5–250 (default 25), `page` 1–40
91
- - 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)
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–250 (default 25) and `page` 1–40
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`, with `attachmentOnly: true` when the substance is in a PDF/DOCX file. 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
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–100 (default 20)
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
- ### Public Hosted Instance
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
- For Cline (`cline_mcp_settings.json`):
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
- Add the following to your MCP client configuration file. `REGULATIONS_GOV_API_KEY` enables the docket and comment tools; omit it to run the keyless Federal Register and eCFR tools alone.
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
- Or with npx (no Bun required):
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@latest"],
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
- For Streamable HTTP, set the transport and start the server:
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 build -t federal-regulations-mcp-server .
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, and the eCFR mirror settings.
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;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;;;;;iBAiCtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAW9C"}
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"}