@cyanheads/federal-regulations-mcp-server 0.6.0 → 0.6.2

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 (116) hide show
  1. package/AGENTS.md +7 -5
  2. package/CLAUDE.md +7 -5
  3. package/README.md +33 -22
  4. package/changelog/0.6.x/0.6.1.md +29 -0
  5. package/changelog/0.6.x/0.6.2.md +37 -0
  6. package/changelog/template.md +10 -3
  7. package/dist/config/server-config.d.ts +6 -3
  8. package/dist/config/server-config.d.ts.map +1 -1
  9. package/dist/config/server-config.js +31 -4
  10. package/dist/config/server-config.js.map +1 -1
  11. package/dist/index.js +1 -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 +7 -4
  15. package/dist/mcp-server/resources/definitions/cfr-section.resource.js.map +1 -1
  16. package/dist/mcp-server/resources/definitions/document.resource.d.ts.map +1 -1
  17. package/dist/mcp-server/resources/definitions/document.resource.js +2 -1
  18. package/dist/mcp-server/resources/definitions/document.resource.js.map +1 -1
  19. package/dist/mcp-server/resources/definitions/index.d.ts +12 -12
  20. package/dist/mcp-server/tools/definitions/agency-notice.d.ts +6 -0
  21. package/dist/mcp-server/tools/definitions/agency-notice.d.ts.map +1 -0
  22. package/dist/mcp-server/tools/definitions/agency-notice.js +17 -0
  23. package/dist/mcp-server/tools/definitions/agency-notice.js.map +1 -0
  24. package/dist/mcp-server/tools/definitions/browse-cfr.tool.d.ts +41 -8
  25. package/dist/mcp-server/tools/definitions/browse-cfr.tool.d.ts.map +1 -1
  26. package/dist/mcp-server/tools/definitions/browse-cfr.tool.js +189 -40
  27. package/dist/mcp-server/tools/definitions/browse-cfr.tool.js.map +1 -1
  28. package/dist/mcp-server/tools/definitions/find-comments.tool.d.ts +8 -3
  29. package/dist/mcp-server/tools/definitions/find-comments.tool.d.ts.map +1 -1
  30. package/dist/mcp-server/tools/definitions/find-comments.tool.js +78 -43
  31. package/dist/mcp-server/tools/definitions/find-comments.tool.js.map +1 -1
  32. package/dist/mcp-server/tools/definitions/format-utils.d.ts +17 -0
  33. package/dist/mcp-server/tools/definitions/format-utils.d.ts.map +1 -1
  34. package/dist/mcp-server/tools/definitions/format-utils.js +36 -1
  35. package/dist/mcp-server/tools/definitions/format-utils.js.map +1 -1
  36. package/dist/mcp-server/tools/definitions/get-cfr-section.tool.d.ts +1 -1
  37. package/dist/mcp-server/tools/definitions/get-cfr-section.tool.d.ts.map +1 -1
  38. package/dist/mcp-server/tools/definitions/get-cfr-section.tool.js +19 -15
  39. package/dist/mcp-server/tools/definitions/get-cfr-section.tool.js.map +1 -1
  40. package/dist/mcp-server/tools/definitions/get-docket.tool.d.ts +67 -16
  41. package/dist/mcp-server/tools/definitions/get-docket.tool.d.ts.map +1 -1
  42. package/dist/mcp-server/tools/definitions/get-docket.tool.js +224 -56
  43. package/dist/mcp-server/tools/definitions/get-docket.tool.js.map +1 -1
  44. package/dist/mcp-server/tools/definitions/get-document.tool.d.ts +12 -1
  45. package/dist/mcp-server/tools/definitions/get-document.tool.d.ts.map +1 -1
  46. package/dist/mcp-server/tools/definitions/get-document.tool.js +44 -20
  47. package/dist/mcp-server/tools/definitions/get-document.tool.js.map +1 -1
  48. package/dist/mcp-server/tools/definitions/index.d.ts +217 -97
  49. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  50. package/dist/mcp-server/tools/definitions/list-open-comments.tool.d.ts +2 -2
  51. package/dist/mcp-server/tools/definitions/list-open-comments.tool.d.ts.map +1 -1
  52. package/dist/mcp-server/tools/definitions/list-open-comments.tool.js +19 -17
  53. package/dist/mcp-server/tools/definitions/list-open-comments.tool.js.map +1 -1
  54. package/dist/mcp-server/tools/definitions/presidential-schema.d.ts +17 -0
  55. package/dist/mcp-server/tools/definitions/presidential-schema.d.ts.map +1 -0
  56. package/dist/mcp-server/tools/definitions/presidential-schema.js +31 -0
  57. package/dist/mcp-server/tools/definitions/presidential-schema.js.map +1 -0
  58. package/dist/mcp-server/tools/definitions/search-rules.tool.d.ts +36 -4
  59. package/dist/mcp-server/tools/definitions/search-rules.tool.d.ts.map +1 -1
  60. package/dist/mcp-server/tools/definitions/search-rules.tool.js +160 -32
  61. package/dist/mcp-server/tools/definitions/search-rules.tool.js.map +1 -1
  62. package/dist/mcp-server/tools/definitions/size-limit.d.ts +50 -0
  63. package/dist/mcp-server/tools/definitions/size-limit.d.ts.map +1 -0
  64. package/dist/mcp-server/tools/definitions/size-limit.js +93 -0
  65. package/dist/mcp-server/tools/definitions/size-limit.js.map +1 -0
  66. package/dist/services/ecfr/ecfr-service.d.ts +50 -6
  67. package/dist/services/ecfr/ecfr-service.d.ts.map +1 -1
  68. package/dist/services/ecfr/ecfr-service.js +128 -12
  69. package/dist/services/ecfr/ecfr-service.js.map +1 -1
  70. package/dist/services/ecfr/read-section.d.ts +12 -3
  71. package/dist/services/ecfr/read-section.d.ts.map +1 -1
  72. package/dist/services/ecfr/read-section.js +12 -5
  73. package/dist/services/ecfr/read-section.js.map +1 -1
  74. package/dist/services/ecfr/types.d.ts +68 -0
  75. package/dist/services/ecfr/types.d.ts.map +1 -1
  76. package/dist/services/ecfr/xml.d.ts.map +1 -1
  77. package/dist/services/ecfr/xml.js +2 -2
  78. package/dist/services/ecfr/xml.js.map +1 -1
  79. package/dist/services/ecfr-mirror/refresh-job.d.ts.map +1 -1
  80. package/dist/services/ecfr-mirror/refresh-job.js +6 -0
  81. package/dist/services/ecfr-mirror/refresh-job.js.map +1 -1
  82. package/dist/services/federal-register/agency-resolver.d.ts +20 -0
  83. package/dist/services/federal-register/agency-resolver.d.ts.map +1 -0
  84. package/dist/services/federal-register/agency-resolver.js +120 -0
  85. package/dist/services/federal-register/agency-resolver.js.map +1 -0
  86. package/dist/services/federal-register/federal-register-service.d.ts +4 -1
  87. package/dist/services/federal-register/federal-register-service.d.ts.map +1 -1
  88. package/dist/services/federal-register/federal-register-service.js +126 -32
  89. package/dist/services/federal-register/federal-register-service.js.map +1 -1
  90. package/dist/services/federal-register/gpo-text.d.ts +9 -0
  91. package/dist/services/federal-register/gpo-text.d.ts.map +1 -0
  92. package/dist/services/federal-register/gpo-text.js +92 -0
  93. package/dist/services/federal-register/gpo-text.js.map +1 -0
  94. package/dist/services/federal-register/types.d.ts +63 -5
  95. package/dist/services/federal-register/types.d.ts.map +1 -1
  96. package/dist/services/federal-register/types.js +10 -1
  97. package/dist/services/federal-register/types.js.map +1 -1
  98. package/dist/services/regulations-gov/regulations-gov-service.d.ts +21 -2
  99. package/dist/services/regulations-gov/regulations-gov-service.d.ts.map +1 -1
  100. package/dist/services/regulations-gov/regulations-gov-service.js +99 -22
  101. package/dist/services/regulations-gov/regulations-gov-service.js.map +1 -1
  102. package/dist/services/regulations-gov/types.d.ts +64 -16
  103. package/dist/services/regulations-gov/types.d.ts.map +1 -1
  104. package/dist/services/request-budget.d.ts +2 -2
  105. package/dist/services/request-budget.js +2 -2
  106. package/dist/services/script-notation.d.ts +4 -0
  107. package/dist/services/script-notation.d.ts.map +1 -0
  108. package/dist/services/script-notation.js +7 -0
  109. package/dist/services/script-notation.js.map +1 -0
  110. package/dist/services/upstream-failure.d.ts +5 -0
  111. package/dist/services/upstream-failure.d.ts.map +1 -1
  112. package/dist/services/upstream-failure.js +1 -0
  113. package/dist/services/upstream-failure.js.map +1 -1
  114. package/package.json +10 -10
  115. package/server.json +31 -3
  116. package/skills/federal-regulations-guide/SKILL.md +13 -7
@@ -3,18 +3,6 @@
3
3
  * @module mcp-server/resources/definitions/index
4
4
  */
5
5
  export declare const allResourceDefinitions: (import("@cyanheads/mcp-ts-core").ResourceDefinition<import("zod").ZodObject<{
6
- documentNumber: import("zod").ZodString;
7
- }, import("zod/v4/core").$strip>, undefined, readonly [{
8
- readonly reason: "not_found";
9
- readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
10
- readonly when: "No Federal Register document exists with that number.";
11
- readonly recovery: "Verify the number via regulations_search_rules; FR numbers look like \"2024-07773\", or \"98-1572\" and \"E9-25990\" before 2010.";
12
- }, {
13
- readonly reason: "upstream_unavailable";
14
- readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
15
- readonly when: "Federal Register returned a 5xx, timed out, or served an HTML error page.";
16
- readonly recovery: "Retry after a brief wait; the Federal Register API may be momentarily down.";
17
- }]> | import("@cyanheads/mcp-ts-core").ResourceDefinition<import("zod").ZodObject<{
18
6
  title: import("zod").ZodString;
19
7
  part: import("zod").ZodString;
20
8
  section: import("zod").ZodString;
@@ -34,5 +22,17 @@ export declare const allResourceDefinitions: (import("@cyanheads/mcp-ts-core").R
34
22
  readonly when: "eCFR returned a 5xx, timed out, or served an HTML error page (live path, mirror not ready or missing the section).";
35
23
  readonly recovery: "Retry after a brief wait; the eCFR API may be momentarily unavailable.";
36
24
  readonly thrownBy: "service";
25
+ }]> | import("@cyanheads/mcp-ts-core").ResourceDefinition<import("zod").ZodObject<{
26
+ documentNumber: import("zod").ZodString;
27
+ }, import("zod/v4/core").$strip>, undefined, readonly [{
28
+ readonly reason: "not_found";
29
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
30
+ readonly when: "No Federal Register document exists with that number.";
31
+ readonly recovery: "Verify the number via regulations_search_rules; FR numbers look like \"2024-07773\", or \"98-1572\" and \"E9-25990\" before 2010.";
32
+ }, {
33
+ readonly reason: "upstream_unavailable";
34
+ readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.ServiceUnavailable;
35
+ readonly when: "Federal Register returned a 5xx, timed out, or served an HTML error page.";
36
+ readonly recovery: "Retry after a brief wait; the Federal Register API may be momentarily down.";
37
37
  }]>)[];
38
38
  //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,6 @@
1
+ /** @fileoverview Report successful Federal Register agency filter rewrites on both tools. */
2
+ import type { Context } from '@cyanheads/mcp-ts-core';
3
+ import type { AgencyRewrite } from '../../../services/federal-register/agency-resolver.js';
4
+ /** Log each rewrite and return the notice to compose with the tool's other guidance. */
5
+ export declare function agencyNotice(rewrites: readonly AgencyRewrite[] | undefined, tool: 'regulations_search_rules' | 'regulations_list_open_comments', ctx: Context): string | undefined;
6
+ //# sourceMappingURL=agency-notice.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agency-notice.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/agency-notice.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAE7F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gDAAgD,CAAC;AAIpF,wFAAwF;AACxF,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,EAC9C,IAAI,EAAE,0BAA0B,GAAG,gCAAgC,EACnE,GAAG,EAAE,OAAO,GACX,MAAM,GAAG,SAAS,CAcpB"}
@@ -0,0 +1,17 @@
1
+ /** @fileoverview Report successful Federal Register agency filter rewrites on both tools. */
2
+ import { ATTR_MCP_TOOL_NAME, createCounter } from '@cyanheads/mcp-ts-core/utils';
3
+ let resolutions;
4
+ /** Log each rewrite and return the notice to compose with the tool's other guidance. */
5
+ export function agencyNotice(rewrites, tool, ctx) {
6
+ if (!rewrites?.length)
7
+ return undefined;
8
+ resolutions ??= createCounter('regulations.agency.resolutions', 'Federal Register agency filter rewrites', '{rewrites}');
9
+ const notices = [];
10
+ for (const { original, slug } of rewrites) {
11
+ ctx.log.info('Resolved Federal Register agency filter', { tool, original, slug });
12
+ resolutions.add(1, { [ATTR_MCP_TOOL_NAME]: tool });
13
+ notices.push(`agencies "${original}" read as ${slug}.`);
14
+ }
15
+ return notices.join(' ');
16
+ }
17
+ //# sourceMappingURL=agency-notice.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agency-notice.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/agency-notice.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAG7F,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAGjF,IAAI,WAAyD,CAAC;AAE9D,wFAAwF;AACxF,MAAM,UAAU,YAAY,CAC1B,QAA8C,EAC9C,IAAmE,EACnE,GAAY;IAEZ,IAAI,CAAC,QAAQ,EAAE,MAAM;QAAE,OAAO,SAAS,CAAC;IACxC,WAAW,KAAK,aAAa,CAC3B,gCAAgC,EAChC,yCAAyC,EACzC,YAAY,CACb,CAAC;IACF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1C,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,yCAAyC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QAClF,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QACnD,OAAO,CAAC,IAAI,CAAC,aAAa,QAAQ,aAAa,IAAI,GAAG,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC"}
@@ -8,17 +8,23 @@
8
8
  * cold deploy all route to the live eCFR search API. Keyless. Feeds
9
9
  * regulations_get_cfr_section.
10
10
  *
11
- * `title` and `part` scope both modes; a part with no title is refused rather
11
+ * `title` and `part` scope every mode; a part with no title is refused rather
12
12
  * than dropped, since part numbers repeat across titles and eCFR rejects the
13
13
  * filter outright. A live search hit's path names the part it sits in, which a
14
14
  * mirror hit cannot do — the index stores no level names.
15
15
  *
16
- * `page` / `per_page` page two lists: search results, and a part's flattened
17
- * section listing in structure mode. Live search results are one row per
18
- * section — eCFR's index answers one hit per section version, and the service
19
- * collapses the repeats — so `countBasis` says whether `totalCount` counts
20
- * sections or versions. Every notice a response carries is composed into one
21
- * string, since `notice` is last-wins.
16
+ * Versions mode lists the dates a part's or section's text changed, from the
17
+ * versioner's versions endpoint, in eCFR's order (document order, oldest first
18
+ * within each identifier); each row's `date` reads that version through
19
+ * regulations_get_cfr_section. Its `section` resolves through the read path's
20
+ * own candidates, so the cite forms that tool accepts list the same history.
21
+ *
22
+ * `page` / `per_page` page three lists: search results, a part's flattened
23
+ * section listing in structure mode, and versions. Live search results are one
24
+ * row per section — eCFR's index answers one hit per section version, and the
25
+ * service collapses the repeats — so `countBasis` says whether `totalCount`
26
+ * counts sections or versions. Every notice a response carries is composed into
27
+ * one string, since `notice` is last-wins.
22
28
  * @module mcp-server/tools/definitions/browse-cfr.tool
23
29
  */
24
30
  import { z } from '@cyanheads/mcp-ts-core';
@@ -27,17 +33,21 @@ export declare const browseCfrTool: import("@cyanheads/mcp-ts-core").ToolDefinit
27
33
  mode: z.ZodEnum<{
28
34
  search: "search";
29
35
  structure: "structure";
36
+ versions: "versions";
30
37
  }>;
31
38
  title: z.ZodOptional<z.ZodNumber>;
32
39
  part: z.ZodOptional<z.ZodString>;
33
40
  query: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>;
34
41
  date: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>;
42
+ section: z.ZodOptional<z.ZodString>;
43
+ changed_since: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"">, z.ZodString]>>;
35
44
  page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
36
- per_page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
45
+ per_page: z.ZodDefault<z.ZodLazy<z.ZodNumber>>;
37
46
  }, z.core.$strip>, z.ZodObject<{
38
47
  mode: z.ZodEnum<{
39
48
  search: "search";
40
49
  structure: "structure";
50
+ versions: "versions";
41
51
  }>;
42
52
  date: z.ZodOptional<z.ZodString>;
43
53
  nodes: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -66,6 +76,19 @@ export declare const browseCfrTool: import("@cyanheads/mcp-ts-core").ToolDefinit
66
76
  excerpt: z.ZodString;
67
77
  cfrCite: z.ZodString;
68
78
  }, z.core.$strip>>>;
79
+ versions: z.ZodOptional<z.ZodArray<z.ZodObject<{
80
+ type: z.ZodString;
81
+ identifier: z.ZodString;
82
+ heading: z.ZodString;
83
+ part: z.ZodString;
84
+ subpart: z.ZodNullable<z.ZodString>;
85
+ cfrCite: z.ZodString;
86
+ date: z.ZodString;
87
+ issueDate: z.ZodString;
88
+ substantive: z.ZodBoolean;
89
+ removed: z.ZodBoolean;
90
+ }, z.core.$strip>>>;
91
+ latestAmendmentDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
69
92
  }, z.core.$strip>, readonly [{
70
93
  readonly reason: "query_required";
71
94
  readonly code: JsonRpcErrorCode.ValidationError;
@@ -82,6 +105,16 @@ export declare const browseCfrTool: import("@cyanheads/mcp-ts-core").ToolDefinit
82
105
  readonly code: JsonRpcErrorCode.ValidationError;
83
106
  readonly when: "A part was given with no title. Part identifiers repeat across titles, and eCFR rejects a part filter that names no title.";
84
107
  readonly recovery: "Add the title the part belongs to (e.g. title 40 with part 58), or drop part to search or browse the whole title set.";
108
+ }, {
109
+ readonly reason: "versions_scope_required";
110
+ readonly code: JsonRpcErrorCode.ValidationError;
111
+ readonly when: "Versions mode with no title; with a title but neither part nor changed_since; or with a section but no part.";
112
+ readonly recovery: "Pass title with part (and optionally section) for a part's or section's history, or title with changed_since for what changed across the title.";
113
+ }, {
114
+ readonly reason: "conflicting_title";
115
+ readonly code: JsonRpcErrorCode.ValidationError;
116
+ readonly when: "Versions mode with section written as a full cite (\"21 CFR 141.61\") naming a different title than title.";
117
+ readonly recovery: "Set title to the title the cite names, or pass the section without its title prefix (\"141.61\").";
85
118
  }, {
86
119
  readonly reason: "date_out_of_range";
87
120
  readonly code: JsonRpcErrorCode.ValidationError;
@@ -1 +1 @@
1
- {"version":3,"file":"browse-cfr.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/browse-cfr.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAsB,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAyJjE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiYxB,CAAC"}
1
+ {"version":3,"file":"browse-cfr.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/browse-cfr.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAsB,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAgMjE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0iBxB,CAAC"}
@@ -8,26 +8,34 @@
8
8
  * cold deploy all route to the live eCFR search API. Keyless. Feeds
9
9
  * regulations_get_cfr_section.
10
10
  *
11
- * `title` and `part` scope both modes; a part with no title is refused rather
11
+ * `title` and `part` scope every mode; a part with no title is refused rather
12
12
  * than dropped, since part numbers repeat across titles and eCFR rejects the
13
13
  * filter outright. A live search hit's path names the part it sits in, which a
14
14
  * mirror hit cannot do — the index stores no level names.
15
15
  *
16
- * `page` / `per_page` page two lists: search results, and a part's flattened
17
- * section listing in structure mode. Live search results are one row per
18
- * section — eCFR's index answers one hit per section version, and the service
19
- * collapses the repeats — so `countBasis` says whether `totalCount` counts
20
- * sections or versions. Every notice a response carries is composed into one
21
- * string, since `notice` is last-wins.
16
+ * Versions mode lists the dates a part's or section's text changed, from the
17
+ * versioner's versions endpoint, in eCFR's order (document order, oldest first
18
+ * within each identifier); each row's `date` reads that version through
19
+ * regulations_get_cfr_section. Its `section` resolves through the read path's
20
+ * own candidates, so the cite forms that tool accepts list the same history.
21
+ *
22
+ * `page` / `per_page` page three lists: search results, a part's flattened
23
+ * section listing in structure mode, and versions. Live search results are one
24
+ * row per section — eCFR's index answers one hit per section version, and the
25
+ * service collapses the repeats — so `countBasis` says whether `totalCount`
26
+ * counts sections or versions. Every notice a response carries is composed into
27
+ * one string, since `notice` is last-wins.
22
28
  * @module mcp-server/tools/definitions/browse-cfr.tool
23
29
  */
24
30
  import { tool, z } from '@cyanheads/mcp-ts-core';
25
31
  import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
26
32
  import { escapeMarkdownInline, markdown } from '@cyanheads/mcp-ts-core/utils';
27
- import { normalizePart } from '../../../services/ecfr/cite.js';
28
- import { ECFR_SEARCH_WINDOW, getEcfrService, outsideCoverageMessage, today, } from '../../../services/ecfr/ecfr-service.js';
33
+ import { normalizePart, sectionCite } from '../../../services/ecfr/cite.js';
34
+ import { ECFR_EARLIEST_DATE, ECFR_SEARCH_WINDOW, getEcfrService, outsideCoverageMessage, today, } from '../../../services/ecfr/ecfr-service.js';
35
+ import { citedTitle, describeRewrite, sectionCandidates, stripCitePrefix, } from '../../../services/ecfr/read-section.js';
29
36
  import { mirrorReady, mirrorScope, mirrorSearch, } from '../../../services/ecfr-mirror/ecfr-mirror.js';
30
37
  import { isoDate } from './date-input.js';
38
+ import { clampSize, joinNotices, perPageInput } from './size-limit.js';
31
39
  /** Restriction clause naming the caller's own title (and part) filter, if any. */
32
40
  function filterClause(title, part) {
33
41
  if (title === undefined)
@@ -71,11 +79,11 @@ async function mirrorAnswers(scope, title, ctx) {
71
79
  function describeLiveScope(date, title, part) {
72
80
  return `Live eCFR search — all CFR titles${filterClause(title, part)}, text in effect on ${date}.`;
73
81
  }
74
- /** Largest `per_page` the tool accepts — a truncation notice only suggests raising it below this. */
75
- const MAX_PER_PAGE = 50;
82
+ /** per_page bounds — a truncation notice only suggests raising it below the max. */
83
+ const PER_PAGE = { name: 'per_page', min: 1, max: 50, default: 20 };
76
84
  /** The "or raise per_page" clause, offered only while a larger page exists. */
77
85
  function raisePerPage(perPage) {
78
- return perPage < MAX_PER_PAGE ? `, or raise per_page (max ${MAX_PER_PAGE})` : '';
86
+ return perPage < PER_PAGE.max ? `, or raise per_page (max ${PER_PAGE.max})` : '';
79
87
  }
80
88
  const structureNode = z
81
89
  .object({
@@ -128,51 +136,76 @@ const searchHit = z
128
136
  .describe('Assembled cite → regulations_get_cfr_section. A section hit cites the section ("40 CFR 51.190"); an appendix hit cites the appendix in eCFR\'s own form ("Appendix C to Part 58, Title 40"), not the part around it, since the part\'s sections do not contain the matched text.'),
129
137
  })
130
138
  .describe('One matching CFR section or appendix.');
139
+ const versionRow = z
140
+ .object({
141
+ type: z.string().describe('"section" or "appendix". Treat an unknown type as passthrough.'),
142
+ identifier: z
143
+ .string()
144
+ .describe('Section number ("141.61"); on an appendix row, the identifier regulations_get_cfr_section takes as `appendix`, verbatim.'),
145
+ heading: z.string().describe('The section or appendix name, plain text.'),
146
+ part: z.string().describe('The part it sits in.'),
147
+ subpart: z.string().nullable().describe('Subpart identifier ("G"), or null when in none.'),
148
+ cfrCite: z
149
+ .string()
150
+ .describe('Cite → regulations_get_cfr_section, as structure mode cites the same node.'),
151
+ date: z
152
+ .string()
153
+ .describe(`Day this version took effect: pass it as regulations_get_cfr_section \`date\` to read it. A row dated before ${ECFR_EARLIEST_DATE} is the text in force when eCFR coverage begins, read at ${ECFR_EARLIEST_DATE}. A removed row's date reads nothing; the previous row's date reads the last text.`),
154
+ issueDate: z
155
+ .string()
156
+ .describe('The eCFR issue that published this version, which can postdate `date`; changed_since filters on it.'),
157
+ substantive: z
158
+ .boolean()
159
+ .describe('False when eCFR flags the version as an editorial re-issue.'),
160
+ removed: z.boolean().describe('True on the row that removed the section or appendix.'),
161
+ })
162
+ .describe('One version of a section or appendix.');
131
163
  export const browseCfrTool = tool('regulations_browse_cfr', {
132
164
  title: 'regulations_browse_cfr',
133
- description: 'Explore the codified Code of Federal Regulations via eCFR in two modes. "structure" lists all 50 titles; with a title, that title\'s top-level divisions (its chapters, or subtitles); and with a title and part, every section and appendix in the part, flattened and paged, each naming the subpart and subject group it sits under — the way to enumerate a part\'s sections without reading its text. "search" runs a full-text query across the codified CFR and returns matching sections with their hierarchy path and a snippet, one result per section, paged. Both modes accept title and part to narrow the scope. Both feed regulations_get_cfr_section. Every search result reports which corpus answered it — the synced local mirror or the live eCFR index — and what that corpus covers, in `source` and `sourceScope`.',
165
+ description: 'Explore the codified Code of Federal Regulations via eCFR in three modes. "structure" lists all 50 titles; with a title, that title\'s top-level divisions (its chapters, or subtitles); and with a title and part, every section and appendix in the part, flattened and paged, each naming the subpart and subject group it sits under — the way to enumerate a part\'s sections without reading its text. "search" runs a full-text query across the codified CFR and returns matching sections with their hierarchy path and a snippet, one result per section, paged. "versions" lists the dates a part\'s or one section\'s text changed, oldest first per section, paged, with the latest amendment date; with changed_since, what changed across a title. Every mode accepts title and part to narrow the scope, and all three feed regulations_get_cfr_section — a version row\'s `date` reads that version. Every search result reports which corpus answered it — the synced local mirror or the live eCFR index — and what that corpus covers, in `source` and `sourceScope`.',
134
166
  annotations: { readOnlyHint: true, openWorldHint: true },
135
167
  input: z.object({
136
168
  mode: z
137
- .enum(['structure', 'search'])
138
- .describe('"structure": list titles, a title\'s top-level divisions, or a part\'s sections and appendices, to find a cite. "search": full-text search the codified CFR for sections matching a phrase.'),
169
+ .enum(['structure', 'search', 'versions'])
170
+ .describe('"structure": list titles, a title\'s top-level divisions, or a part\'s sections and appendices, to find a cite. "search": full-text search the codified CFR for sections matching a phrase. "versions": list the dates a part\'s or section\'s text changed (title plus part or changed_since).'),
139
171
  title: z
140
172
  .number()
141
173
  .int()
142
174
  .min(1)
143
175
  .max(50)
144
176
  .optional()
145
- .describe("CFR title number (1–50). Structure mode: omit to list all 50 titles; provide it alone to list the title's top-level divisions (chapters, or subtitles) — not the parts beneath them — or with part to list that part. Search mode: optional filter restricting matches to that title — e.g. 40 for environmental rules, 21 for food and drugs."),
177
+ .describe("CFR title number (1–50). Structure mode: omit to list all 50 titles; provide it alone to list the title's top-level divisions (chapters, or subtitles) — not the parts beneath them — or with part to list that part. Search mode: optional filter restricting matches to that title — e.g. 40 for environmental rules, 21 for food and drugs. Versions mode: required, with part or changed_since."),
146
178
  part: z
147
179
  .string()
148
180
  .optional()
149
- .describe('CFR part within the title, in both modes — structure mode lists every section and appendix in the part, flattened and paged by page/per_page; search mode restricts matches to text inside that part. Requires title; a part on its own is rejected. Parts can be alphanumeric ("1203a", "16A") and are matched exactly once a leading "Part" or "Pt." is dropped, so pass the identifier as eCFR writes it — "58" ("Part 58" also reads as 58), not "058".'),
181
+ .describe('CFR part within the title, in every mode — structure mode lists every section and appendix in the part, flattened and paged by page/per_page; search mode restricts matches to text inside that part; versions mode lists the part\'s versions, appendices included. Requires title; a part on its own is rejected. Parts can be alphanumeric ("1203a", "16A") and are matched exactly once a leading "Part" or "Pt." is dropped, so pass the identifier as eCFR writes it — "58" ("Part 58" also reads as 58), not "058".'),
150
182
  query: z
151
183
  .union([z.literal(''), z.string().min(2).describe('Search phrase, at least 2 characters.')])
152
184
  .optional()
153
- .describe('Full-text search phrase (search mode, required in that mode). Ignored in structure mode.'),
185
+ .describe('Full-text search phrase (search mode, required in that mode). Ignored in structure and versions modes.'),
154
186
  date: z
155
187
  .union([z.literal(''), isoDate()])
156
188
  .optional()
157
- .describe("Point-in-time date, ISO 8601 (YYYY-MM-DD). Defaults to current. Structure mode uses it for the historical hierarchy, and rejects a date past the title's up-to-date date. Search mode matches only the section text in effect on that day, so a past date searches the CFR as it read then; eCFR indexes 2017-01-03 onward and rejects a date past its current index date."),
189
+ .describe("Point-in-time date, ISO 8601 (YYYY-MM-DD). Defaults to current. Structure mode uses it for the historical hierarchy, and rejects a date past the title's up-to-date date. Search mode matches only the section text in effect on that day, so a past date searches the CFR as it read then; eCFR indexes 2017-01-03 onward and rejects a date past its current index date. Ignored in versions mode, where each row carries its own date."),
190
+ section: z
191
+ .string()
192
+ .optional()
193
+ .describe('Versions mode: list one section\'s versions rather than its part\'s ("141.61"). Requires part. "61", "§ 141.61", "141.61(c)", and "40 CFR 141.61" resolve to the section, with a notice. Ignored in other modes.'),
194
+ changed_since: z
195
+ .union([z.literal(''), isoDate()])
196
+ .optional()
197
+ .describe('Versions mode: keep only versions published by an eCFR issue dated on or after this day (YYYY-MM-DD). With title alone, lists what changed across the title. Ignored in other modes.'),
158
198
  page: z
159
199
  .number()
160
200
  .int()
161
201
  .min(1)
162
202
  .optional()
163
203
  .default(1)
164
- .describe(`1-based page of search results, or of a part's listing in structure mode (default 1); ignored by a structure listing above a part, which comes back whole. A truncation notice names the next page. Live eCFR search pages through its first ${ECFR_SEARCH_WINDOW.toLocaleString('en-US')} hits only, so a page starting past them is refused — narrow the query instead of paging deeper.`),
165
- per_page: z
166
- .number()
167
- .int()
168
- .min(1)
169
- .max(MAX_PER_PAGE)
170
- .optional()
171
- .default(20)
172
- .describe(`Rows per page — search results, or nodes of a part's listing in structure mode (1–${MAX_PER_PAGE}, default 20).`),
204
+ .describe(`1-based page of search results, of a part's listing in structure mode, or of versions (default 1); ignored by a structure listing above a part, which comes back whole. A truncation notice names the next page. Live eCFR search pages through its first ${ECFR_SEARCH_WINDOW.toLocaleString('en-US')} hits only, so a page starting past them is refused — narrow the query instead of paging deeper.`),
205
+ per_page: perPageInput(PER_PAGE, (bounds) => `Rows per page — search results, nodes of a part's listing in structure mode, or versions (${bounds}).`),
173
206
  }),
174
207
  output: z.object({
175
- mode: z.enum(['structure', 'search']).describe('Which mode produced this result.'),
208
+ mode: z.enum(['structure', 'search', 'versions']).describe('Which mode produced this result.'),
176
209
  date: z
177
210
  .string()
178
211
  .optional()
@@ -193,12 +226,21 @@ export const browseCfrTool = tool('regulations_browse_cfr', {
193
226
  .array(searchHit)
194
227
  .optional()
195
228
  .describe('Matching CFR sections and appendices, this page, one row per section however many of its versions matched (search mode).'),
229
+ versions: z
230
+ .array(versionRow)
231
+ .optional()
232
+ .describe('Versions mode: this page of versions in eCFR order — document order by identifier, oldest first within each.'),
233
+ latestAmendmentDate: z
234
+ .string()
235
+ .nullable()
236
+ .optional()
237
+ .describe('Versions mode: the newest `date` across every listed version, not just this page; null when none matched.'),
196
238
  }),
197
239
  enrichment: {
198
240
  totalCount: z
199
241
  .number()
200
242
  .optional()
201
- .describe("Total matches before pagination — search results (see countBasis for what they count), or the nodes in a part's listing."),
243
+ .describe("Total matches before pagination — search results (see countBasis for what they count), the nodes in a part's listing, or versions."),
202
244
  countBasis: z
203
245
  .enum(['sections', 'section_versions'])
204
246
  .optional()
@@ -206,13 +248,13 @@ export const browseCfrTool = tool('regulations_browse_cfr', {
206
248
  page: z
207
249
  .number()
208
250
  .optional()
209
- .describe("The page served — of search results, or of a part's listing."),
251
+ .describe("The page served — of search results, a part's listing, or versions."),
210
252
  truncated: z.boolean().optional().describe('True when another page follows this one.'),
211
253
  shown: z.number().optional().describe('Rows returned on this page.'),
212
254
  notice: z
213
255
  .string()
214
256
  .optional()
215
- .describe('Guidance: the next page to request, a page past the end, an empty result, or what the count means.'),
257
+ .describe('Guidance: per_page above its ceiling, the next page to request, a page past the end, an empty result, what the count means, or how a section was read.'),
216
258
  },
217
259
  enrichmentTrailer: {
218
260
  notice: { render: (value) => (value === undefined ? '' : `> ${escapeMarkdownInline(value)}`) },
@@ -237,6 +279,18 @@ export const browseCfrTool = tool('regulations_browse_cfr', {
237
279
  when: 'A part was given with no title. Part identifiers repeat across titles, and eCFR rejects a part filter that names no title.',
238
280
  recovery: 'Add the title the part belongs to (e.g. title 40 with part 58), or drop part to search or browse the whole title set.',
239
281
  },
282
+ {
283
+ reason: 'versions_scope_required',
284
+ code: JsonRpcErrorCode.ValidationError,
285
+ when: 'Versions mode with no title; with a title but neither part nor changed_since; or with a section but no part.',
286
+ recovery: "Pass title with part (and optionally section) for a part's or section's history, or title with changed_since for what changed across the title.",
287
+ },
288
+ {
289
+ reason: 'conflicting_title',
290
+ code: JsonRpcErrorCode.ValidationError,
291
+ when: 'Versions mode with section written as a full cite ("21 CFR 141.61") naming a different title than title.',
292
+ recovery: 'Set title to the title the cite names, or pass the section without its title prefix ("141.61").',
293
+ },
240
294
  {
241
295
  reason: 'date_out_of_range',
242
296
  code: JsonRpcErrorCode.ValidationError,
@@ -268,6 +322,83 @@ export const browseCfrTool = tool('regulations_browse_cfr', {
268
322
  if (part && input.title === undefined) {
269
323
  throw ctx.fail('title_required_for_part');
270
324
  }
325
+ if (input.mode === 'versions') {
326
+ const { title, page } = input;
327
+ const asked = input.section?.trim() || undefined;
328
+ const changedSince = input.changed_since || undefined;
329
+ if (title === undefined) {
330
+ throw ctx.fail('versions_scope_required', 'Versions mode needs a title.');
331
+ }
332
+ // The versioner takes a section without its part, but a dotless number
333
+ // ("25") names a section only inside one part.
334
+ if (asked && !part) {
335
+ throw ctx.fail('versions_scope_required', `Section "${asked}" needs the part it sits in.`);
336
+ }
337
+ // A title on its own is its entire history in document order — 60,251
338
+ // versions across 61 upstream pages for title 40 — so it is listed only
339
+ // narrowed to what changed since a date.
340
+ if (!part && !changedSince) {
341
+ throw ctx.fail('versions_scope_required', `Title ${title} alone lists every version of every section in it; name a part, or pass changed_since.`);
342
+ }
343
+ const cited = asked ? citedTitle(asked) : undefined;
344
+ if (cited !== undefined && cited !== title) {
345
+ throw ctx.fail('conflicting_title', `Section "${asked}" cites title ${cited}, but title is ${title}.`);
346
+ }
347
+ // A section resolves through the read tool's own candidates, one request
348
+ // each, until a form has versions. A marker the versioner cannot parse
349
+ // ("§") is stripped before the first; an empty set moves on to the next.
350
+ const scopeLabel = part ? `part ${part} of title ${title}` : `title ${title}`;
351
+ let forms = [{}];
352
+ let where = scopeLabel;
353
+ if (asked && part) {
354
+ const { prefix, value } = stripCitePrefix(asked, title, part);
355
+ forms = sectionCandidates(value, part).map((candidate) => ({
356
+ section: candidate.section,
357
+ cite: sectionCite(title, part, candidate.section),
358
+ ...(candidate.section !== asked && {
359
+ rewrite: describeRewrite(asked, prefix, candidate, part),
360
+ }),
361
+ }));
362
+ const others = forms.slice(1).map((form) => form.section);
363
+ where = `section "${value}" in ${scopeLabel}${others.length > 0 ? ` (also tried ${others.join(', ')})` : ''}`;
364
+ }
365
+ const size = clampSize(input.per_page, PER_PAGE, 'regulations_browse_cfr', ctx);
366
+ const perPage = size.value;
367
+ const start = (page - 1) * perPage;
368
+ const read = (section) => service.listVersions(title, { part, section, changedSince }, start, perPage, ctx);
369
+ let tried = 0;
370
+ let listing = await read(forms[0]?.section);
371
+ while (listing.totalCount === 0 && tried + 1 < forms.length) {
372
+ tried++;
373
+ listing = await read(forms[tried]?.section);
374
+ }
375
+ const resolved = listing.totalCount > 0 ? forms[tried] : undefined;
376
+ const { versions, totalCount, latestAmendmentDate } = listing;
377
+ const output = { mode: 'versions', versions, latestAmendmentDate };
378
+ ctx.enrich({ page });
379
+ ctx.enrich.total(totalCount);
380
+ if (!resolved) {
381
+ ctx.enrich.notice(joinNotices(size.notice, changedSince
382
+ ? `No version of ${where} was issued on or after ${changedSince}. Omit changed_since to list its whole history; if that is empty too, verify the cite with mode "structure".`
383
+ : `eCFR lists no versions of ${where}: no such ${asked ? 'section' : 'part'} exists there. Verify the cite with mode "structure", which lists a part's sections.`));
384
+ return output;
385
+ }
386
+ const since = changedSince ? ` issued on or after ${changedSince}` : '';
387
+ const label = resolved.cite ?? scopeLabel;
388
+ const lastPage = Math.ceil(totalCount / perPage);
389
+ const notes = [size.notice, resolved.rewrite].filter((note) => Boolean(note));
390
+ if (versions.length === 0) {
391
+ notes.push(`Page ${page} is past the end of ${label}'s versions: its ${totalCount} versions${since} end on page ${lastPage} at per_page ${perPage}. Request page ${lastPage} or earlier.`);
392
+ }
393
+ else if (start + versions.length < totalCount) {
394
+ notes.push(`${label.charAt(0).toUpperCase()}${label.slice(1)} holds ${totalCount} versions${since}; this is page ${page} of ${lastPage}. Request page ${page + 1} for the next ${perPage}${raisePerPage(perPage)}.`);
395
+ ctx.enrich.truncated({ shown: versions.length, cap: perPage, guidance: notes.join(' ') });
396
+ return output;
397
+ }
398
+ if (notes.length > 0)
399
+ ctx.enrich.notice(notes.join(' '));
400
+ return output;
401
+ }
271
402
  // Only a part's listing and search results are paged; any other structure
272
403
  // listing comes back whole, so a later page of it has nothing different to say.
273
404
  const unpagedNotice = () => {
@@ -300,23 +431,25 @@ export const browseCfrTool = tool('regulations_browse_cfr', {
300
431
  }
301
432
  // A part's listing runs to thousands of nodes (40 CFR 63 holds 3,120), so
302
433
  // it is paged like search results rather than returned whole.
303
- const { page, per_page: perPage } = input;
434
+ const { page } = input;
435
+ const size = clampSize(input.per_page, PER_PAGE, 'regulations_browse_cfr', ctx);
436
+ const perPage = size.value;
304
437
  const start = (page - 1) * perPage;
305
438
  const shown = nodes.slice(start, start + perPage);
306
439
  const lastPage = Math.ceil(nodes.length / perPage);
307
440
  ctx.enrich({ page });
308
441
  ctx.enrich.total(nodes.length);
309
442
  if (nodes.length === 0) {
310
- ctx.enrich.notice(`Part ${part} of title ${input.title} lists no sections or appendices as of ${date}; it may be reserved.`);
443
+ ctx.enrich.notice(joinNotices(size.notice, `Part ${part} of title ${input.title} lists no sections or appendices as of ${date}; it may be reserved.`));
311
444
  }
312
445
  else if (shown.length === 0) {
313
- ctx.enrich.notice(`Page ${page} is past the end of part ${part}'s listing: its ${nodes.length} sections and appendices end on page ${lastPage} at per_page ${perPage}. Request page ${lastPage} or earlier.`);
446
+ ctx.enrich.notice(joinNotices(size.notice, `Page ${page} is past the end of part ${part}'s listing: its ${nodes.length} sections and appendices end on page ${lastPage} at per_page ${perPage}. Request page ${lastPage} or earlier.`));
314
447
  }
315
448
  else if (start + shown.length < nodes.length) {
316
449
  ctx.enrich.truncated({
317
450
  shown: shown.length,
318
451
  cap: perPage,
319
- guidance: `Part ${part} holds ${nodes.length} sections and appendices; this is page ${page} of ${lastPage}. Request page ${page + 1} for the next ${perPage}${raisePerPage(perPage)}.`,
452
+ guidance: joinNotices(size.notice, `Part ${part} holds ${nodes.length} sections and appendices; this is page ${page} of ${lastPage}. Request page ${page + 1} for the next ${perPage}${raisePerPage(perPage)}.`),
320
453
  });
321
454
  }
322
455
  return { mode: 'structure', date, nodes: shown };
@@ -333,7 +466,9 @@ export const browseCfrTool = tool('regulations_browse_cfr', {
333
466
  // so those go to live eCFR, as section reads already do on a mirror miss.
334
467
  const scope = !input.date && (await mirrorReady()) ? await mirrorScope() : null;
335
468
  const answering = scope && (await mirrorAnswers(scope, input.title, ctx)) ? scope : null;
336
- const { page, per_page: perPage } = input;
469
+ const { page } = input;
470
+ const size = clampSize(input.per_page, PER_PAGE, 'regulations_browse_cfr', ctx);
471
+ const perPage = size.value;
337
472
  let provenance;
338
473
  let response;
339
474
  if (answering) {
@@ -359,17 +494,17 @@ export const browseCfrTool = tool('regulations_browse_cfr', {
359
494
  ctx.enrich({ page, countBasis: response.countBasis });
360
495
  ctx.enrich.total(response.totalCount);
361
496
  if (response.totalCount === 0) {
362
- ctx.enrich.notice(`No CFR sections matched "${query}". Corpus searched: ${provenance.sourceScope} Broaden the phrase, ${part ? 'drop the part filter, ' : ''}drop the title filter, or try another title before concluding no such rule exists.`);
497
+ ctx.enrich.notice(joinNotices(size.notice, `No CFR sections matched "${query}". Corpus searched: ${provenance.sourceScope} Broaden the phrase, ${part ? 'drop the part filter, ' : ''}drop the title filter, or try another title before concluding no such rule exists.`));
363
498
  return { mode: 'search', ...provenance, results: [] };
364
499
  }
365
500
  if (response.results.length === 0) {
366
501
  // Only a count of sections reaches here — a version count means the list
367
502
  // was not read to its end, which only happens while the page is still full.
368
503
  const lastPage = Math.ceil(response.totalCount / perPage);
369
- ctx.enrich.notice(`Page ${page} is past the last page of results: ${response.totalCount} matches end on page ${lastPage} at per_page ${perPage}. Request page ${lastPage} or earlier.`);
504
+ ctx.enrich.notice(joinNotices(size.notice, `Page ${page} is past the last page of results: ${response.totalCount} matches end on page ${lastPage} at per_page ${perPage}. Request page ${lastPage} or earlier.`));
370
505
  return { mode: 'search', ...provenance, results: [] };
371
506
  }
372
- const notes = [];
507
+ const notes = size.notice ? [size.notice] : [];
373
508
  if (response.hasMore) {
374
509
  notes.push(`This is page ${page}; request page ${page + 1} for the next ${perPage}${raisePerPage(perPage)}.`);
375
510
  }
@@ -421,6 +556,20 @@ export const browseCfrTool = tool('regulations_browse_cfr', {
421
556
  lines.push(`- **${escapeMarkdownInline(n.type)}** ${escapeMarkdownInline(n.identifier)}: ${escapeMarkdownInline(n.label)}${desc}${reserved}${cite}${appendix}`);
422
557
  }
423
558
  }
559
+ if (result.versions) {
560
+ lines.push(`**CFR versions** (mode: ${result.mode}, latest amendment: ${result.latestAmendmentDate ?? 'none'})`);
561
+ lines.push('');
562
+ for (const v of result.versions) {
563
+ const flags = [];
564
+ if (v.date < ECFR_EARLIEST_DATE) {
565
+ flags.push(`in force when eCFR coverage begins; read it at ${ECFR_EARLIEST_DATE}`);
566
+ }
567
+ if (v.removed)
568
+ flags.push("removed — reading at this date finds nothing; the previous row's date reads the last text");
569
+ const subpart = v.subpart ? `, subpart ${escapeMarkdownInline(v.subpart)}` : '';
570
+ lines.push(`- **${escapeMarkdownInline(v.date)}** ${markdown().inlineCode(v.cfrCite).build()} — ${escapeMarkdownInline(v.heading)} (${escapeMarkdownInline(v.type)} ${markdown().inlineCode(v.identifier).build()}, part ${escapeMarkdownInline(v.part)}${subpart}, issued ${escapeMarkdownInline(v.issueDate)}, ${v.substantive ? 'substantive' : 'not substantive (editorial re-issue)'})${flags.map((f) => ` _(${f})_`).join('')}`);
571
+ }
572
+ }
424
573
  if (result.results || result.source) {
425
574
  // The date is not repeated here — the scope line below already names the
426
575
  // day the corpus was read at.