@cyanheads/federal-regulations-mcp-server 0.5.4 → 0.6.0
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 +18 -8
- package/CLAUDE.md +18 -8
- package/Dockerfile +2 -0
- package/README.md +20 -120
- package/changelog/0.6.x/0.6.0.md +30 -0
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +63 -63
- package/package.json +6 -5
- package/server.json +3 -3
- package/skills/federal-regulations-guide/SKILL.md +65 -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.0
|
|
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.
|
|
@@ -248,7 +248,7 @@ scripts/
|
|
|
248
248
|
|
|
249
249
|
No prompts in v1 — `createApp({ prompts: [] })`.
|
|
250
250
|
|
|
251
|
-
**`scripts/` is typechecked
|
|
251
|
+
**`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
252
|
|
|
253
253
|
---
|
|
254
254
|
|
|
@@ -265,9 +265,18 @@ No prompts in v1 — `createApp({ prompts: [] })`.
|
|
|
265
265
|
|
|
266
266
|
## Skills
|
|
267
267
|
|
|
268
|
-
|
|
268
|
+
Two skill trees live at the project root, written for different readers:
|
|
269
269
|
|
|
270
|
-
|
|
270
|
+
| Tree | For | Written by |
|
|
271
|
+
|:-----|:----|:-----------|
|
|
272
|
+
| `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) |
|
|
273
|
+
| `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 |
|
|
274
|
+
|
|
275
|
+
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.
|
|
276
|
+
|
|
277
|
+
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.
|
|
278
|
+
|
|
279
|
+
**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
280
|
|
|
272
281
|
Available skills:
|
|
273
282
|
|
|
@@ -279,6 +288,7 @@ Available skills:
|
|
|
279
288
|
| `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
|
|
280
289
|
| `add-resource` | Scaffold a new resource definition |
|
|
281
290
|
| `add-prompt` | Scaffold a new prompt definition |
|
|
291
|
+
| `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
292
|
| `add-service` | Scaffold a new service integration |
|
|
283
293
|
| `add-test` | Scaffold test file for a tool, resource, or service |
|
|
284
294
|
| `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
|
|
@@ -326,7 +336,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
326
336
|
| `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
337
|
| `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
338
|
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
329
|
-
| `bun run lint:packaging` | Packaging surface checks —
|
|
339
|
+
| `bun run lint:packaging` | Packaging surface checks — env-var parity, `.mcpbignore` coverage, plugin manifests, published `skills/` tree (run by devcheck) |
|
|
330
340
|
| `bun run list-skills` | Print the skill registry |
|
|
331
341
|
| `bun run tree` | Generate directory structure doc |
|
|
332
342
|
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
@@ -347,7 +357,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
347
357
|
|
|
348
358
|
## Bundling
|
|
349
359
|
|
|
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
|
|
360
|
+
`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
361
|
|
|
352
362
|
**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
363
|
|
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.0
|
|
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.
|
|
@@ -248,7 +248,7 @@ scripts/
|
|
|
248
248
|
|
|
249
249
|
No prompts in v1 — `createApp({ prompts: [] })`.
|
|
250
250
|
|
|
251
|
-
**`scripts/` is typechecked
|
|
251
|
+
**`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
252
|
|
|
253
253
|
---
|
|
254
254
|
|
|
@@ -265,9 +265,18 @@ No prompts in v1 — `createApp({ prompts: [] })`.
|
|
|
265
265
|
|
|
266
266
|
## Skills
|
|
267
267
|
|
|
268
|
-
|
|
268
|
+
Two skill trees live at the project root, written for different readers:
|
|
269
269
|
|
|
270
|
-
|
|
270
|
+
| Tree | For | Written by |
|
|
271
|
+
|:-----|:----|:-----------|
|
|
272
|
+
| `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) |
|
|
273
|
+
| `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 |
|
|
274
|
+
|
|
275
|
+
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.
|
|
276
|
+
|
|
277
|
+
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.
|
|
278
|
+
|
|
279
|
+
**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
280
|
|
|
272
281
|
Available skills:
|
|
273
282
|
|
|
@@ -279,6 +288,7 @@ Available skills:
|
|
|
279
288
|
| `add-app-tool` | Scaffold an MCP App tool + paired UI resource |
|
|
280
289
|
| `add-resource` | Scaffold a new resource definition |
|
|
281
290
|
| `add-prompt` | Scaffold a new prompt definition |
|
|
291
|
+
| `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
292
|
| `add-service` | Scaffold a new service integration |
|
|
283
293
|
| `add-test` | Scaffold test file for a tool, resource, or service |
|
|
284
294
|
| `field-test` | Exercise tools/resources/prompts with real inputs, verify behavior, report issues |
|
|
@@ -326,7 +336,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
326
336
|
| `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
337
|
| `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
338
|
| `bun run lint:mcp` | Run the MCP definition linter standalone (rule catalog: `api-linter` skill) |
|
|
329
|
-
| `bun run lint:packaging` | Packaging surface checks —
|
|
339
|
+
| `bun run lint:packaging` | Packaging surface checks — env-var parity, `.mcpbignore` coverage, plugin manifests, published `skills/` tree (run by devcheck) |
|
|
330
340
|
| `bun run list-skills` | Print the skill registry |
|
|
331
341
|
| `bun run tree` | Generate directory structure doc |
|
|
332
342
|
| `bun run format` | Auto-fix formatting (safe fixes only) |
|
|
@@ -347,7 +357,7 @@ When you complete a skill's checklist, check the boxes and add a completion time
|
|
|
347
357
|
|
|
348
358
|
## Bundling
|
|
349
359
|
|
|
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
|
|
360
|
+
`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
361
|
|
|
352
362
|
**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
363
|
|
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
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 •
|
|
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
|
|
|
@@ -49,8 +49,9 @@ 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
|
|
|
@@ -141,140 +142,32 @@ Agent-friendly output:
|
|
|
141
142
|
|
|
142
143
|
## Getting started
|
|
143
144
|
|
|
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:
|
|
145
|
+
Connect to the hosted instance:
|
|
149
146
|
|
|
150
147
|
```sh
|
|
151
148
|
claude mcp add --transport http federal-regulations-mcp-server https://federal-regulations.caseyjhand.com/mcp
|
|
152
149
|
```
|
|
153
150
|
|
|
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
|
|
151
|
+
Or run it locally:
|
|
182
152
|
|
|
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
|
-
}
|
|
153
|
+
```sh
|
|
154
|
+
claude mcp add federal-regulations-mcp-server -- npx -y @cyanheads/federal-regulations-mcp-server
|
|
200
155
|
```
|
|
201
156
|
|
|
202
|
-
|
|
157
|
+
For other clients, add this to your MCP configuration file:
|
|
203
158
|
|
|
204
159
|
```json
|
|
205
160
|
{
|
|
206
161
|
"mcpServers": {
|
|
207
162
|
"federal-regulations-mcp-server": {
|
|
208
|
-
"type": "stdio",
|
|
209
163
|
"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
|
-
]
|
|
164
|
+
"args": ["-y", "@cyanheads/federal-regulations-mcp-server"]
|
|
235
165
|
}
|
|
236
166
|
}
|
|
237
167
|
}
|
|
238
168
|
```
|
|
239
169
|
|
|
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
|
-
```
|
|
170
|
+
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
171
|
|
|
279
172
|
## Configuration
|
|
280
173
|
|
|
@@ -300,6 +193,14 @@ See [`.env.example`](./.env.example) for the full list of optional overrides.
|
|
|
300
193
|
|
|
301
194
|
### Local development
|
|
302
195
|
|
|
196
|
+
Requires Bun v1.4.0 or higher (or Node.js v24+).
|
|
197
|
+
|
|
198
|
+
```sh
|
|
199
|
+
git clone https://github.com/cyanheads/federal-regulations-mcp-server.git
|
|
200
|
+
cd federal-regulations-mcp-server && bun install
|
|
201
|
+
cp .env.example .env
|
|
202
|
+
```
|
|
203
|
+
|
|
303
204
|
- **Build and run:**
|
|
304
205
|
|
|
305
206
|
```sh
|
|
@@ -330,8 +231,7 @@ See [`.env.example`](./.env.example) for the full list of optional overrides.
|
|
|
330
231
|
### Docker
|
|
331
232
|
|
|
332
233
|
```sh
|
|
333
|
-
docker
|
|
334
|
-
docker run --rm -e REGULATIONS_GOV_API_KEY=your-key -p 3010:3010 federal-regulations-mcp-server
|
|
234
|
+
docker run --rm -e REGULATIONS_GOV_API_KEY=your-key -p 3010:3010 ghcr.io/cyanheads/federal-regulations-mcp-server:latest
|
|
335
235
|
```
|
|
336
236
|
|
|
337
237
|
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.
|
package/dist/index.js
CHANGED
|
@@ -30,6 +30,7 @@ await createApp({
|
|
|
30
30
|
sessionMode: 'stateless',
|
|
31
31
|
tools: allToolDefinitions,
|
|
32
32
|
resources: allResourceDefinitions,
|
|
33
|
+
skills: 'skills',
|
|
33
34
|
prompts: [],
|
|
34
35
|
instructions: "US federal regulatory law over three official sources. The Federal Register (regulations_search_rules, regulations_get_document, regulations_list_open_comments) and eCFR (regulations_browse_cfr, regulations_get_cfr_section) tools are keyless. The Regulations.gov tools (regulations_get_docket, regulations_find_comments) need REGULATIONS_GOV_API_KEY (free at https://api.data.gov/signup/) and return an actionable auth_required error without it; comment counts and Regulations.gov IDs on the Federal Register tools need no key. Trace a rule end to end: search_rules → get_document (yields docket ID + CFR parts) → find_comments → get_cfr_section, and back from a section's source-note cite with search_rules citation + citation_date.",
|
|
35
36
|
setup(core) {
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AACjG,OAAO,EAAE,0BAA0B,EAAE,MAAM,yDAAyD,CAAC;AACrG,OAAO,EAAE,yBAAyB,EAAE,MAAM,uDAAuD,CAAC;AAElG,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,gCAAgC;IACtC,KAAK,EAAE,gCAAgC;IACvC,+EAA+E;IAC/E,wEAAwE;IACxE,yEAAyE;IACzE,2EAA2E;IAC3E,wEAAwE;IACxE,WAAW,EAAE,WAAW;IACxB,KAAK,EAAE,kBAAkB;IACzB,SAAS,EAAE,sBAAsB;IACjC,OAAO,EAAE,EAAE;IACX,YAAY,EACV,+tBAA+tB;IACjuB,KAAK,CAAC,IAAI;QACR,0BAA0B,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACtD,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3C,yBAAyB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACrD,uEAAuE;QACvE,KAAK,qBAAqB,CACxB,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAC5B,eAAe,EAAE,CAAC,qBAAqB,CACxC,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,QAAQ;QACZ,MAAM,iBAAiB,EAAE,CAAC;QAC1B,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;CACF,CAAC,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AACnE,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AACjG,OAAO,EAAE,0BAA0B,EAAE,MAAM,yDAAyD,CAAC;AACrG,OAAO,EAAE,yBAAyB,EAAE,MAAM,uDAAuD,CAAC;AAElG,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,gCAAgC;IACtC,KAAK,EAAE,gCAAgC;IACvC,+EAA+E;IAC/E,wEAAwE;IACxE,yEAAyE;IACzE,2EAA2E;IAC3E,wEAAwE;IACxE,WAAW,EAAE,WAAW;IACxB,KAAK,EAAE,kBAAkB;IACzB,SAAS,EAAE,sBAAsB;IACjC,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,EAAE;IACX,YAAY,EACV,+tBAA+tB;IACjuB,KAAK,CAAC,IAAI;QACR,0BAA0B,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACtD,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3C,yBAAyB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACrD,uEAAuE;QACvE,KAAK,qBAAqB,CACxB,IAAI,CAAC,MAAM,CAAC,gBAAgB,EAC5B,eAAe,EAAE,CAAC,qBAAqB,CACxC,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,QAAQ;QACZ,MAAM,iBAAiB,EAAE,CAAC;QAC1B,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;CACF,CAAC,CAAC"}
|
|
@@ -89,69 +89,6 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
|
|
|
89
89
|
readonly truncated: import("zod").ZodOptional<import("zod").ZodBoolean>;
|
|
90
90
|
readonly shown: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
91
91
|
readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
|
|
92
|
-
}> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
|
|
93
|
-
document_number: import("zod").ZodString;
|
|
94
|
-
include_full_text: import("zod").ZodOptional<import("zod").ZodBoolean>;
|
|
95
|
-
offset: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
96
|
-
max_chars: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
97
|
-
}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
|
|
98
|
-
documentNumber: import("zod").ZodString;
|
|
99
|
-
title: import("zod").ZodString;
|
|
100
|
-
type: import("zod").ZodString;
|
|
101
|
-
abstract: import("zod").ZodNullable<import("zod").ZodString>;
|
|
102
|
-
action: import("zod").ZodNullable<import("zod").ZodString>;
|
|
103
|
-
dates: import("zod").ZodNullable<import("zod").ZodString>;
|
|
104
|
-
publicationDate: import("zod").ZodString;
|
|
105
|
-
citation: import("zod").ZodNullable<import("zod").ZodString>;
|
|
106
|
-
startPage: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
107
|
-
endPage: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
108
|
-
effectiveOn: import("zod").ZodNullable<import("zod").ZodString>;
|
|
109
|
-
commentsCloseOn: import("zod").ZodNullable<import("zod").ZodString>;
|
|
110
|
-
commentPeriodOpen: import("zod").ZodNullable<import("zod").ZodBoolean>;
|
|
111
|
-
agencies: import("zod").ZodArray<import("zod").ZodObject<{
|
|
112
|
-
name: import("zod").ZodString;
|
|
113
|
-
slug: import("zod").ZodNullable<import("zod").ZodString>;
|
|
114
|
-
}, import("zod/v4/core").$strip>>;
|
|
115
|
-
regulationIdNumbers: import("zod").ZodArray<import("zod").ZodString>;
|
|
116
|
-
cfrReferences: import("zod").ZodArray<import("zod").ZodObject<{
|
|
117
|
-
title: import("zod").ZodNumber;
|
|
118
|
-
part: import("zod").ZodString;
|
|
119
|
-
}, import("zod/v4/core").$strip>>;
|
|
120
|
-
docketIds: import("zod").ZodArray<import("zod").ZodString>;
|
|
121
|
-
docketId: import("zod").ZodNullable<import("zod").ZodString>;
|
|
122
|
-
regulationsGovDocumentId: import("zod").ZodNullable<import("zod").ZodString>;
|
|
123
|
-
commentCount: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
124
|
-
commentUrl: import("zod").ZodNullable<import("zod").ZodString>;
|
|
125
|
-
supportingDocuments: import("zod").ZodArray<import("zod").ZodObject<{
|
|
126
|
-
title: import("zod").ZodString;
|
|
127
|
-
documentId: import("zod").ZodString;
|
|
128
|
-
}, import("zod/v4/core").$strip>>;
|
|
129
|
-
bodyHtmlUrl: import("zod").ZodString;
|
|
130
|
-
rawTextUrl: import("zod").ZodString;
|
|
131
|
-
htmlUrl: import("zod").ZodString;
|
|
132
|
-
fullText: import("zod").ZodOptional<import("zod").ZodString>;
|
|
133
|
-
fullTextOffset: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
134
|
-
fullTextLength: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
135
|
-
fullTextNextOffset: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
136
|
-
}, import("zod/v4/core").$strip>, readonly [{
|
|
137
|
-
readonly reason: "full_text_disabled";
|
|
138
|
-
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
|
|
139
|
-
readonly when: "offset or max_chars was passed together with include_full_text: false.";
|
|
140
|
-
readonly recovery: "Drop include_full_text: false to read the body window, or drop offset and max_chars to skip the body.";
|
|
141
|
-
}, {
|
|
142
|
-
readonly reason: "not_found";
|
|
143
|
-
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
|
|
144
|
-
readonly when: "No Federal Register document exists with that number.";
|
|
145
|
-
readonly recovery: "Verify the number via regulations_search_rules; FR numbers look like \"2024-07773\", or \"98-1572\" and \"E9-25990\" before 2010.";
|
|
146
|
-
readonly thrownBy: "service";
|
|
147
|
-
}, {
|
|
148
|
-
readonly reason: "upstream_unavailable";
|
|
149
|
-
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
|
|
150
|
-
readonly when: "Federal Register returned a 5xx, timed out, served an HTML error page, or failed to serve the body URL it published (include_full_text only).";
|
|
151
|
-
readonly recovery: "Retry after a brief wait; the Federal Register API may be momentarily down.";
|
|
152
|
-
readonly thrownBy: "service";
|
|
153
|
-
}], {
|
|
154
|
-
readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
|
|
155
92
|
}> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
|
|
156
93
|
query: import("zod").ZodOptional<import("zod").ZodString>;
|
|
157
94
|
type: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodEnum<{
|
|
@@ -246,6 +183,69 @@ export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolD
|
|
|
246
183
|
readonly shown: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
247
184
|
readonly cap: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
248
185
|
readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
|
|
186
|
+
}> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
|
|
187
|
+
document_number: import("zod").ZodString;
|
|
188
|
+
include_full_text: import("zod").ZodOptional<import("zod").ZodBoolean>;
|
|
189
|
+
offset: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
190
|
+
max_chars: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
191
|
+
}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
|
|
192
|
+
documentNumber: import("zod").ZodString;
|
|
193
|
+
title: import("zod").ZodString;
|
|
194
|
+
type: import("zod").ZodString;
|
|
195
|
+
abstract: import("zod").ZodNullable<import("zod").ZodString>;
|
|
196
|
+
action: import("zod").ZodNullable<import("zod").ZodString>;
|
|
197
|
+
dates: import("zod").ZodNullable<import("zod").ZodString>;
|
|
198
|
+
publicationDate: import("zod").ZodString;
|
|
199
|
+
citation: import("zod").ZodNullable<import("zod").ZodString>;
|
|
200
|
+
startPage: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
201
|
+
endPage: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
202
|
+
effectiveOn: import("zod").ZodNullable<import("zod").ZodString>;
|
|
203
|
+
commentsCloseOn: import("zod").ZodNullable<import("zod").ZodString>;
|
|
204
|
+
commentPeriodOpen: import("zod").ZodNullable<import("zod").ZodBoolean>;
|
|
205
|
+
agencies: import("zod").ZodArray<import("zod").ZodObject<{
|
|
206
|
+
name: import("zod").ZodString;
|
|
207
|
+
slug: import("zod").ZodNullable<import("zod").ZodString>;
|
|
208
|
+
}, import("zod/v4/core").$strip>>;
|
|
209
|
+
regulationIdNumbers: import("zod").ZodArray<import("zod").ZodString>;
|
|
210
|
+
cfrReferences: import("zod").ZodArray<import("zod").ZodObject<{
|
|
211
|
+
title: import("zod").ZodNumber;
|
|
212
|
+
part: import("zod").ZodString;
|
|
213
|
+
}, import("zod/v4/core").$strip>>;
|
|
214
|
+
docketIds: import("zod").ZodArray<import("zod").ZodString>;
|
|
215
|
+
docketId: import("zod").ZodNullable<import("zod").ZodString>;
|
|
216
|
+
regulationsGovDocumentId: import("zod").ZodNullable<import("zod").ZodString>;
|
|
217
|
+
commentCount: import("zod").ZodNullable<import("zod").ZodNumber>;
|
|
218
|
+
commentUrl: import("zod").ZodNullable<import("zod").ZodString>;
|
|
219
|
+
supportingDocuments: import("zod").ZodArray<import("zod").ZodObject<{
|
|
220
|
+
title: import("zod").ZodString;
|
|
221
|
+
documentId: import("zod").ZodString;
|
|
222
|
+
}, import("zod/v4/core").$strip>>;
|
|
223
|
+
bodyHtmlUrl: import("zod").ZodString;
|
|
224
|
+
rawTextUrl: import("zod").ZodString;
|
|
225
|
+
htmlUrl: import("zod").ZodString;
|
|
226
|
+
fullText: import("zod").ZodOptional<import("zod").ZodString>;
|
|
227
|
+
fullTextOffset: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
228
|
+
fullTextLength: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
229
|
+
fullTextNextOffset: import("zod").ZodOptional<import("zod").ZodNumber>;
|
|
230
|
+
}, import("zod/v4/core").$strip>, readonly [{
|
|
231
|
+
readonly reason: "full_text_disabled";
|
|
232
|
+
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ValidationError;
|
|
233
|
+
readonly when: "offset or max_chars was passed together with include_full_text: false.";
|
|
234
|
+
readonly recovery: "Drop include_full_text: false to read the body window, or drop offset and max_chars to skip the body.";
|
|
235
|
+
}, {
|
|
236
|
+
readonly reason: "not_found";
|
|
237
|
+
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
|
|
238
|
+
readonly when: "No Federal Register document exists with that number.";
|
|
239
|
+
readonly recovery: "Verify the number via regulations_search_rules; FR numbers look like \"2024-07773\", or \"98-1572\" and \"E9-25990\" before 2010.";
|
|
240
|
+
readonly thrownBy: "service";
|
|
241
|
+
}, {
|
|
242
|
+
readonly reason: "upstream_unavailable";
|
|
243
|
+
readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
|
|
244
|
+
readonly when: "Federal Register returned a 5xx, timed out, served an HTML error page, or failed to serve the body URL it published (include_full_text only).";
|
|
245
|
+
readonly recovery: "Retry after a brief wait; the Federal Register API may be momentarily down.";
|
|
246
|
+
readonly thrownBy: "service";
|
|
247
|
+
}], {
|
|
248
|
+
readonly notice: import("zod").ZodOptional<import("zod").ZodString>;
|
|
249
249
|
}> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
|
|
250
250
|
title: import("zod").ZodNumber;
|
|
251
251
|
part: import("zod").ZodOptional<import("zod").ZodString>;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cyanheads/federal-regulations-mcp-server",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.0",
|
|
4
4
|
"mcpName": "io.github.cyanheads/federal-regulations-mcp-server",
|
|
5
5
|
"description": "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.",
|
|
6
6
|
"type": "module",
|
|
@@ -10,6 +10,7 @@
|
|
|
10
10
|
"federal-regulations-mcp-server": "dist/index.js"
|
|
11
11
|
},
|
|
12
12
|
"files": [
|
|
13
|
+
"skills/",
|
|
13
14
|
"changelog/",
|
|
14
15
|
"dist/",
|
|
15
16
|
"!dist/*.mcpb",
|
|
@@ -93,7 +94,7 @@
|
|
|
93
94
|
"access": "public"
|
|
94
95
|
},
|
|
95
96
|
"dependencies": {
|
|
96
|
-
"@cyanheads/mcp-ts-core": "0.13.
|
|
97
|
+
"@cyanheads/mcp-ts-core": "0.13.18",
|
|
97
98
|
"entities": "^8.1.0",
|
|
98
99
|
"node-cron": "^4.6.0",
|
|
99
100
|
"pino-pretty": "^13.2.0",
|
|
@@ -108,15 +109,15 @@
|
|
|
108
109
|
"postcss": "^8.5.23"
|
|
109
110
|
},
|
|
110
111
|
"devDependencies": {
|
|
111
|
-
"@biomejs/biome": "2.6.
|
|
112
|
+
"@biomejs/biome": "2.6.3",
|
|
112
113
|
"@socketsecurity/bun-security-scanner": "^1.1.3",
|
|
113
114
|
"@types/markdown-it": "^14.2.0",
|
|
114
115
|
"@types/node": "26.6.5",
|
|
115
116
|
"better-sqlite3": "^13.0.3",
|
|
116
117
|
"depcheck": "^1.4.7",
|
|
117
|
-
"ignore": "^7.0.
|
|
118
|
+
"ignore": "^7.0.14",
|
|
118
119
|
"markdown-it": "15.0.3",
|
|
119
|
-
"tsc-alias": "^1.9.
|
|
120
|
+
"tsc-alias": "^1.9.9",
|
|
120
121
|
"typescript": "^7.0.2",
|
|
121
122
|
"vitest": "^5.0.5"
|
|
122
123
|
}
|
package/server.json
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
"url": "https://github.com/cyanheads/federal-regulations-mcp-server",
|
|
7
7
|
"source": "github"
|
|
8
8
|
},
|
|
9
|
-
"version": "0.
|
|
9
|
+
"version": "0.6.0",
|
|
10
10
|
"remotes": [
|
|
11
11
|
{
|
|
12
12
|
"type": "streamable-http",
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"registryBaseUrl": "https://registry.npmjs.org",
|
|
20
20
|
"identifier": "@cyanheads/federal-regulations-mcp-server",
|
|
21
21
|
"runtimeHint": "npx",
|
|
22
|
-
"version": "0.
|
|
22
|
+
"version": "0.6.0",
|
|
23
23
|
"environmentVariables": [
|
|
24
24
|
{
|
|
25
25
|
"name": "REGULATIONS_GOV_API_KEY",
|
|
@@ -45,7 +45,7 @@
|
|
|
45
45
|
"registryBaseUrl": "https://registry.npmjs.org",
|
|
46
46
|
"identifier": "@cyanheads/federal-regulations-mcp-server",
|
|
47
47
|
"runtimeHint": "npx",
|
|
48
|
-
"version": "0.
|
|
48
|
+
"version": "0.6.0",
|
|
49
49
|
"environmentVariables": [
|
|
50
50
|
{
|
|
51
51
|
"name": "MCP_TRANSPORT_TYPE",
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: federal-regulations-guide
|
|
3
|
+
description: Research rulemaking history, codified CFR text, and public comments with regulations_* tools. Use when tracing a rule across sources, finding the publication behind a CFR source note, checking comment deadlines, or assessing public-comment evidence.
|
|
4
|
+
license: Apache-2.0
|
|
5
|
+
metadata:
|
|
6
|
+
author: "cyanheads"
|
|
7
|
+
version: "1.0"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## Scope
|
|
11
|
+
|
|
12
|
+
Use the Federal Register for published proposals, final rules, notices, and presidential documents; eCFR for codified regulatory text at a current or historical date; and Regulations.gov for docket records and public comments. A proposal or final-rule publication alone does not establish what the CFR says at the date being researched.
|
|
13
|
+
|
|
14
|
+
Federal Register and eCFR research is keyless. Docket and comment retrieval needs REGULATIONS_GOV_API_KEY. Without it, continue with published documents, their embedded comment metadata, and CFR text; identify the comment evidence you could not inspect.
|
|
15
|
+
|
|
16
|
+
The server reads records. It neither submits comments nor downloads and parses attachment files. Statutes and court decisions require other sources.
|
|
17
|
+
|
|
18
|
+
## Identifiers
|
|
19
|
+
|
|
20
|
+
| Handle | Obtain it from | Use it for |
|
|
21
|
+
|:-------|:---------------|:-----------|
|
|
22
|
+
| FR document number | documentNumber in regulations_search_rules or regulations_list_open_comments; frDocNum on a regulations_get_docket document | Open the publication with regulations_get_document, or locate its comments with regulations_find_comments |
|
|
23
|
+
| Printed docket number | docketIds on Federal Register results or document detail | Find related Federal Register publications with regulations_search_rules; this is not necessarily a Regulations.gov docket ID |
|
|
24
|
+
| RIN | regulationIdNumbers on Federal Register results or detail | Follow related rulemaking publications with regulations_search_rules |
|
|
25
|
+
| Regulations.gov docket ID | regulationsGovDocketId on discovery results; docketId on regulations_get_document | Read the docket or list docket-wide comments |
|
|
26
|
+
| Regulations.gov document ID | regulationsGovDocumentId on Federal Register results or detail; documentId in a docket | List comments on that document |
|
|
27
|
+
| Document object ID | objectId on a document in regulations_get_docket | List comments on that document; do not substitute a docket's or comment's object ID |
|
|
28
|
+
| Comment ID | commentId in regulations_find_comments list results | Read that comment's body, status, and attachment URLs |
|
|
29
|
+
| CFR location | cfrReferences supplies title and part; regulations_browse_cfr supplies sections and complete appendix identifiers | Read codified text with regulations_get_cfr_section |
|
|
30
|
+
|
|
31
|
+
## Gates
|
|
32
|
+
|
|
33
|
+
1. **Choose the comment scope before retrieving evidence.** Document comments concern one publication; docket-wide comments can span several documents. Treat a docket named like `<AGENCY>_FRDOC_0001` as a warning to prefer the document-specific handle for that publication's comments. Null Regulations.gov handles mean that link is unavailable, not that nobody commented.
|
|
34
|
+
|
|
35
|
+
2. **Read comments before characterizing their arguments.** A list supplies neither bodies nor attachment details. Open individual comment records. When attachmentOnly is true, retrieve and read the attachment separately before summarizing its substance; a stub body is not the submission. Preserve withdrawn or restricted status and report duplicateComments separately from the number of records inspected; do not infer a total submission count from it.
|
|
36
|
+
|
|
37
|
+
3. **Establish coverage before asserting absence or completeness.** Inspect scope, filters, pagination, and truncation notices. An empty comment list establishes only that the requested scope and filters returned none. Broaden from a document to its rulemaking docket when appropriate. For CFR search, read sourceScope and countBasis: a section_versions count is not a count of distinct sections. A missing or partial result is not evidence that no regulation or public reaction exists.
|
|
38
|
+
|
|
39
|
+
4. **Finish the relevant text before quoting a conclusion from it.** Federal Register bodies and CFR reads return text windows. Follow the returned next offset when the answer depends on text beyond the window. A whole-part read does not inline appendix bodies. Single-section reads omit enclosing part, subpart, and subject-group Authority and Source notes; read the whole part when those notes matter.
|
|
40
|
+
|
|
41
|
+
5. **Keep dates attached to conclusions.** Use the date returned with CFR text. Historical reads start in 2017, and current text can trail today's date. Do not substitute today's date for the title's available snapshot or infer earlier text outside coverage. A paragraph cite reads its whole section; inspect the requested paragraph within that text.
|
|
42
|
+
|
|
43
|
+
6. **Resolve appendix names before reading them.** Copy the complete appendix identifier from regulations_browse_cfr or a whole-part read, including wording such as “Appendix A-1 to Part 50.” Include the returned part to keep the lookup scoped to the discovered location.
|
|
44
|
+
|
|
45
|
+
7. **Check related publications before advising on a comment deadline.** Treat commentsCloseOn as metadata for that publication, and check related publications before relying on it as the current deadline. Search the complete RIN or printed docket number for related publications and read relevant extensions. The closing day is inclusive in US Eastern time; null comment-period status means unknown. Include notices when the task concerns all opportunities for public comment, since the default open-comment listing covers proposed and final rules.
|
|
46
|
+
|
|
47
|
+
## Workflows
|
|
48
|
+
|
|
49
|
+
### Trace a rulemaking into codified text
|
|
50
|
+
|
|
51
|
+
Discover the publication with regulations_search_rules and open it with regulations_get_document. Follow its complete RIN or printed docket number to locate related proposals, final rules, corrections, or extensions. Verify each candidate's identity and substance rather than assuming similar titles establish a relationship. Use the affected CFR title and part to browse the relevant sections, then read the CFR snapshot needed for the question. Keep the published rule and codified text separately cited.
|
|
52
|
+
|
|
53
|
+
### Work backward from a CFR requirement
|
|
54
|
+
|
|
55
|
+
Search codified text with regulations_browse_cfr or start from a known cite. Read the section and, when needed, its enclosing Authority and Source notes. Take a Federal Register page citation together with the date printed beside it to regulations_search_rules. A cited page may fall inside a publication, and several publications can share a page; open the candidates before attributing the amendment. This server's page-citation lookup starts in 1994. Check the returned coverage notice before interpreting an unresolved older citation as evidence the publication is absent.
|
|
56
|
+
|
|
57
|
+
### Assess public comments
|
|
58
|
+
|
|
59
|
+
For one known publication, regulations_find_comments can resolve its FR number directly. Use regulations_get_docket when the task needs supporting materials, several rule documents, or the wider docket context. Select the relevant document handles or the docket-wide scope, then open comment details and relevant attachments. State which scope, filters, and records support the assessment; do not treat an initial page as representative of the entire corpus.
|
|
60
|
+
|
|
61
|
+
### Retrieve a large result set
|
|
62
|
+
|
|
63
|
+
Follow continuation metadata. When Federal Register navigation is capped, divide publication dates into smaller windows. For comments, divide posted dates into smaller windows; for docket documents, narrow document types. Deduplicate records where windows overlap. If a slice still exceeds the reachable window, report the remaining gap rather than claiming complete retrieval.
|
|
64
|
+
|
|
65
|
+
Start with ordinary search terms and inspect sourceScope. Do not assume the same Boolean or quoted-phrase syntax works across all three sources.
|