@cyanheads/ris-austria-mcp-server 0.4.0 → 0.4.2

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.4.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/ris-austria-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/ris-austria-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/ris-austria-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.4.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/ris-austria-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/ris-austria-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/ris-austria-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -132,8 +132,8 @@ Read and export a single document.
 - `format`: `markdown` (default, boilerplate stripped), raw `html`, RIS `xml`, or `urls_only`
 - Every response carries a binding status: `authentic` (with amtssigniert PDF URL), `consolidated_informational`, `historical_record`, `decision`, `preparatory`, `administrative_directive`, or `translation`
 - Applications that publish only the signed PDF (district and municipal promulgations, court rules) or only scans (1848–1940 gazettes, ÖNB-hosted) return a `format_unavailable` notice with the usable URLs instead of failing
-- Markdown over 40,000 bytes returns a §/Artikel/Anlage section outline (`kind: outline`) instead of truncating. Re-call with `sections:[…]` to pull the sections you need
-- Outlining needs those headings. A rendition without them — most court decisions, gazette and announcement bodies, every raw `html`/`xml` — has nothing to outline and returns whole at any size
+- Markdown over 40,000 bytes returns an outline (`kind: outline`) instead of truncating. Re-call with `sections:[…]` to pull the entries you need
+- Outline entries are the document's §/Artikel/Anlage sections, or — for the court decisions, gazette bodies and announcements that carry no such headings — contiguous byte windows named `Part 1 of N` … `Part N of N`, cut at line breaks and covering the text with nothing dropped. Raw `html`/`xml` are never sliced and return whole at any size
 - Returns content, not fresh metadata. The upstream API has no document-by-number search, so document numbers come from a prior search or lookup result
 
 ---
@@ -207,22 +207,56 @@ A public instance is available at `https://ris-austria.caseyjhand.com/mcp` — n
 - [Bun v1.3](https://bun.sh/) or higher, or Node.js v24+ (needed for `npx`/`bunx`)
 - No API key — the RIS OGD API is keyless
 
-### Install from npm (recommended)
+### Self-hosted / local
 
-Add the server to your MCP client configuration:
+Add the server to your MCP client configuration with Bun:
 
 ```json
 {
   "mcpServers": {
     "ris-austria-mcp-server": {
+      "type": "stdio",
+      "command": "bunx",
+      "args": ["@cyanheads/ris-austria-mcp-server@latest"]
+    }
+  }
+}
+```
+
+Or with npx (no Bun required):
+
+```json
+{
+  "mcpServers": {
+    "ris-austria-mcp-server": {
+      "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@cyanheads/ris-austria-mcp-server"]
+      "args": ["-y", "@cyanheads/ris-austria-mcp-server@latest"]
+    }
+  }
+}
+```
+
+Or with Docker:
+
+```json
+{
+  "mcpServers": {
+    "ris-austria-mcp-server": {
+      "type": "stdio",
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "MCP_TRANSPORT_TYPE=stdio",
+        "ghcr.io/cyanheads/ris-austria-mcp-server:latest"
+      ]
     }
   }
 }
 ```
 
-`bunx @cyanheads/ris-austria-mcp-server` works the same way if you prefer Bun. Add any [configuration](#configuration) variables under an `"env"` key.
+Add any [configuration](#configuration) variables under an `"env"` key for bunx/npx, or as
+additional `-e NAME=value` arguments for Docker.
 
 ### Install from source
 
@@ -281,6 +315,7 @@ MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
 | `RIS_CONTACT` | Contact string appended to the User-Agent (RIS netiquette asks integrators to be identifiable). | none |
 | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
 | `MCP_HTTP_PORT` | HTTP server port. | `3010` |
+| `MCP_SESSION_MODE` | HTTP session handling: `stateful`, `stateless`, or `auto`. This server pins stateless serving explicitly. | `stateless` |
 | `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth`. | `none` |
 | `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, …). | `info` |
 | `STORAGE_PROVIDER_TYPE` | Storage backend. | `in-memory` |
@@ -312,13 +347,26 @@ See [`.env.example`](./.env.example) for the full list of optional overrides.
   bun run lint:mcp   # Validate MCP definitions against spec
   ```
 
+### Docker
+
+```sh
+docker build -t ris-austria-mcp-server .
+docker run --rm -p 3010:3010 ris-austria-mcp-server
+```
+
+The Dockerfile defaults to HTTP transport, stateless session mode, and logs to
+`/var/log/ris-austria-mcp-server`. OpenTelemetry peer dependencies are installed by default;
+build with `--build-arg OTEL_ENABLED=false` to omit them.
+
 ## Project structure
 
 | Directory | Purpose |
 |:---|:---|
 | `src/index.ts` | `createApp()` entry point — registers tools and resources. |
+| `src/config` | Optional RIS endpoint and contact configuration, parsed with Zod. |
 | `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). |
 | `src/mcp-server/resources` | Resource definitions (`*.resource.ts`). |
+| `src/services/ris` | RIS request building, HTTP access, normalization, and static reference data. |
 | `docs/design.md` | Settled v1 design — tool surface, service spec, live-confirmed RIS API reference. |
 | `tests/` | Unit and integration tests mirroring `src/`. |
 | `skills/` | Framework skills synced from `@cyanheads/mcp-ts-core`. |

package/changelog/0.4.x/0.4.1.md

@@ -0,0 +1,15 @@
+---
+summary: "ris_get_document now outlines heading-free markdown that overflows the byte budget into retrievable byte windows, instead of returning it whole at any size; also fixes a join bug in multi-section retrieval."
+breaking: false
+security: false
+---
+
+# 0.4.1 — 2026-07-31
+
+## Changed
+
+- **`ris_get_document` / `ris://document/…`** — markdown that overflows the 40,000-byte budget with no §/Artikel/Anlage headings (most court decisions, gazette and announcement bodies, `§ 0` promulgation records) no longer returns whole at any size. `windowDocument()` cuts it into near-even byte windows snapped to line boundaries, named `Part n of N` in document order; `addressableSections()` resolves both the outline and the `sections:[…]` selector to §/Artikel/Anlage sections where the markdown carries at least two, else to windows. `html` and `xml` remain untouched passthroughs regardless of size. ([#33](https://github.com/cyanheads/ris-austria-mcp-server/issues/33))
+
+## Fixed
+
+- **`selectDocumentSections` multi-entry join** — a `sections:[…]` call naming several entries joined their text with `\n\n`, bytes not present in the source, inflating the returned size past the sum of the advertised entries and, in a table-heavy document, splitting a table at the seam. Entries now join with nothing between them and reassemble byte-for-byte. Predates the windowing change above; affects any multi-section retrieval.

package/changelog/0.4.x/0.4.2.md

@@ -0,0 +1,26 @@
+---
+summary: "Adopts MCP SDK v2 with 2026-07-28 compatibility, strict root tool inputs, cache hints, and current error envelopes."
+breaking: false
+security: false
+---
+
+# 0.4.2 — 2026-08-24
+
+## Added
+
+- **MCP 2026-07-28 compatibility** — the server now supports the current protocol alongside 2025-era clients, with one-hour public caching for immutable catalogs and 24-hour public caching for RIS document resources.
+
+## Changed
+
+- **Tool contracts** — undeclared root input fields now reject instead of being stripped, and output schemas advertise the structured error envelope so validating clients can accept both success and failure results.
+- **Error recovery** — RIS client rejections now use `ValidationError`; request deadlines preserve `Timeout` recovery while correlated service requests inherit the handler context.
+- **HTTP sessions** — source runs, containers, and documented configuration now resolve explicitly to stateless mode. MCP 2026-07-28 requests remain sessionless in either mode.
+- **Maintenance surface** — Bun 1.4 container and package-manager pins, production peer omission, test typechecking, framework skills, community health files, and generated documentation are current.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.11.0 → ^0.12.3
+- `@biomejs/biome` 2.5.5 → 2.5.10
+- `@types/node` 26.1.1 → 26.2.0
+- `tsc-alias` ^1.9.1 → ^1.9.2
+- `vitest` ^4.1.10 → ^4.1.11

package/changelog/template.md

@@ -4,10 +4,11 @@
 # to author a new release. Set that file's H1 to `# <version> — YYYY-MM-DD`
 # with a concrete date.
 
-# Required. One-line GitHub Release-style headline. 350 character cap.
-# Default short and scannable. Don't pad, don't stitch unrelated changes with
-# semicolons — pick the headline. Quotes required: unquoted YAML treats `: `
-# inside the value as a key separator and fails GitHub's strict parser.
+# Required. One-line GitHub Release-style headline. 350 character cap — a
+# ceiling, not a target. Default short and scannable. Don't pad, don't stitch
+# unrelated changes with commas/semicolons into an inventory — pick the
+# headline, like a tag's theme line. Quotes required: unquoted YAML treats
+# `: ` inside the value as a key separator and fails GitHub's strict parser.
 summary: ""
 
 # Set `true` when consumers must change code to upgrade: API removals,
@@ -24,9 +25,10 @@ security: false
 
 # Optional free-form notes for maintenance agents processing this release.
 # Not rendered in CHANGELOG — consumed by agents running `maintenance` on
-# downstream servers. Use for adoption instructions that don't fit the
-# human-facing sections: new files to create, fields to populate, one-time
-# migration steps. Omit the field entirely when there's nothing to say.
+# downstream servers. ADOPTION STEPS ONLY — new files to create, fields to
+# populate, one-time migration steps. Never a second rendering of the body:
+# if a body bullet already says it, name the bullet's symbol instead of
+# re-explaining. Omit the field entirely when there's nothing to say.
 # agent-notes: |
 #   <instructions for downstream maintenance agents>
 ---
@@ -41,17 +43,54 @@ security: false
   each bullet with the symbol or concept name in **bold** so they can skip
   what's irrelevant and zoom in on what's not.
 
-  Tone: terse, fact-dense, not verbose. Default to one sentence per bullet —
-  name the symbol, state what changed, stop. Use a second sentence only when
-  it carries weight. If a bullet feels long, it is.
-
-  Cut: mechanism walkthroughs (those belong in JSDoc, CLAUDE.md/AGENTS.md, or the
-  relevant skill), ceremonial framings ("This release introduces…",
-  backwards-compat paragraphs), file-by-file test enumerations, internal
-  implementation notes. Prefer code/symbol names over English re-explanations.
+  Tone: terse, fact-dense, not verbose. Bullet shape: **symbol** + what
+  changed + at most one consumer-facing caveat. One sentence by default, two
+  when the second carries weight — a bullet past ~40 words or three sentences
+  is wrong. The depth lives one hop away: the linked issue carries the why,
+  the commit diff carries the how. The changelog names what changed and what
+  a consumer does about it; a reader who wants mechanism opens the link.
+
+  Model length on THIS guide, never on the previous entry — entries modeled
+  on entries compound.
+
+  Cut (each has shipped as a wall of text; these are the cruft):
+  - History/justification narration — how the bug worked, why the old
+    behavior was wrong. One short clause at most; the issue carries the story.
+  - Design-rationale defense — "chosen over Y because…", "guarding the
+    getter is not enough…". That is the author arguing with a reviewer;
+    reviewers read the PR, not the changelog.
+  - Defensive unchanged-clauses — "X is unchanged", "byte-identical to
+    <prev>". Keep one only where its absence would cause a real misread,
+    as a short parenthetical.
+  - Edge-case inventories — marker lists, not-flagged lists, escape tables.
+    Tests and the issue carry those.
+  - Mechanism walkthroughs (JSDoc, CLAUDE.md/AGENTS.md, or the relevant
+    skill own those), ceremonial framings ("This release introduces…"),
+    backwards-compat paragraphs, file-by-file test enumerations. Prefer
+    code/symbol names over English re-explanations.
+
+  Verified ≠ included: the every-claim-verified-from-the-diff rule bounds
+  the TRUTH of what you write, never the AMOUNT.
+
+  Example — same fact, right size:
+
+    TOO LONG: **`fetchWithTimeout`'s `timeoutMs` bounds the whole exchange**
+    (#341). `fetch` resolves once headers arrive and the deadline was
+    cleared as the helper returned, so a peer that answered promptly and
+    then stalled the stream held the request open indefinitely. A 2xx
+    carrying a body now comes back as a passthrough wrapper that disarms
+    the deadline when the body closes, errors, or is cancelled; …
+    [+90 more words of mechanism and edge cases]
+
+    RIGHT: **`fetchWithTimeout`'s `timeoutMs` now bounds the whole
+    exchange, not just the headers** (#341). A stalled body aborts with
+    the same `Timeout` error; the returned `Response` is a wrapper, so
+    identity assertions (`toBe(response)`) no longer hold.
 
   Narrative intro: skip by default. Add one short sentence only when the
-  release theme genuinely needs framing the bullets can't carry.
+  release theme genuinely needs framing the bullets can't carry. When many
+  bullets share one upgrade consequence, state it ONCE — intro line or
+  agent-notes — never per bullet.
 
   Sections: Keep a Changelog order — Added, Changed, Deprecated, Removed,
   Fixed, Security. Include only sections with entries; delete the rest

package/dist/index.js

@@ -18,6 +18,12 @@ import { initRisService } from './services/ris/ris-service.js';
 await createApp({
     name: 'ris-austria-mcp-server',
     title: 'ris-austria-mcp-server',
+    cacheHints: {
+        'tools/list': { ttlMs: 3_600_000, cacheScope: 'public' },
+        'resources/list': { ttlMs: 3_600_000, cacheScope: 'public' },
+        'resources/templates/list': { ttlMs: 3_600_000, cacheScope: 'public' },
+        'server/discover': { ttlMs: 3_600_000, cacheScope: 'public' },
+    },
     tools: [
         risSearchLegislation,
         risSearchCaseLaw,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6DAA6D,CAAC;AAClG,OAAO,EAAE,cAAc,EAAE,MAAM,yDAAyD,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAC7F,OAAO,EAAE,iBAAiB,EAAE,MAAM,4DAA4D,CAAC;AAC/F,OAAO,EAAE,sBAAsB,EAAE,MAAM,iEAAiE,CAAC;AACzG,OAAO,EAAE,gBAAgB,EAAE,MAAM,4DAA4D,CAAC;AAC9F,OAAO,EAAE,eAAe,EAAE,MAAM,0DAA0D,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,+DAA+D,CAAC;AACrG,OAAO,EAAE,eAAe,EAAE,MAAM,0DAA0D,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,wBAAwB;IAC9B,KAAK,EAAE,wBAAwB;IAC/B,KAAK,EAAE;QACL,oBAAoB;QACpB,gBAAgB;QAChB,gBAAgB;QAChB,eAAe;QACf,sBAAsB;QACtB,iBAAiB;QACjB,cAAc;QACd,eAAe;QACf,gBAAgB;KACjB;IACD,SAAS,EAAE,CAAC,mBAAmB,CAAC;IAChC,KAAK,CAAC,IAAI;QACR,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6DAA6D,CAAC;AAClG,OAAO,EAAE,cAAc,EAAE,MAAM,yDAAyD,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAC7F,OAAO,EAAE,iBAAiB,EAAE,MAAM,4DAA4D,CAAC;AAC/F,OAAO,EAAE,sBAAsB,EAAE,MAAM,iEAAiE,CAAC;AACzG,OAAO,EAAE,gBAAgB,EAAE,MAAM,4DAA4D,CAAC;AAC9F,OAAO,EAAE,eAAe,EAAE,MAAM,0DAA0D,CAAC;AAC3F,OAAO,EAAE,gBAAgB,EAAE,MAAM,2DAA2D,CAAC;AAC7F,OAAO,EAAE,oBAAoB,EAAE,MAAM,+DAA+D,CAAC;AACrG,OAAO,EAAE,eAAe,EAAE,MAAM,0DAA0D,CAAC;AAC3F,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,wBAAwB;IAC9B,KAAK,EAAE,wBAAwB;IAC/B,UAAU,EAAE;QACV,YAAY,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QACxD,gBAAgB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QAC5D,0BAA0B,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;QACtE,iBAAiB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE;KAC9D;IACD,KAAK,EAAE;QACL,oBAAoB;QACpB,gBAAgB;QAChB,gBAAgB;QAChB,eAAe;QACf,sBAAsB;QACtB,iBAAiB;QACjB,cAAc;QACd,eAAe;QACf,gBAAgB;KACjB;IACD,SAAS,EAAE,CAAC,mBAAmB,CAAC;IAChC,KAAK,CAAC,IAAI;QACR,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;CACF,CAAC,CAAC"}

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

@@ -3,9 +3,10 @@
  * of ris_get_document. Reads the same content path (HTML rendition converted to markdown) for
  * an (application, documentNumber) pair. Applications with no text rendition (authentic-PDF-only,
  * PDF-only, or metadata-only) return a short note pointing at the usable artifact instead of
- * text. Oversized text degrades to the same §/Artikel/Anlage section outline the tool emits,
- * plus a note pointing at ris_get_document (which carries the sections selector this bare-string
- * resource cannot). Backed by the shared renderDocument helper from the tool definition.
+ * text. Oversized text degrades to the same outline the tool emits — §/Artikel/Anlage sections,
+ * or `Part n of N` byte windows where the rendition carries no such headings — plus a note
+ * pointing at ris_get_document (which carries the sections selector this bare-string resource
+ * cannot). Backed by the shared renderDocument helper from the tool definition.
  * @module mcp-server/resources/definitions/ris-document
  */
 import { z } from '@cyanheads/mcp-ts-core';

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

@@ -1 +1 @@
-{"version":3,"file":"ris-document.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/ris-document.resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAY3E,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;GA2F9B,CAAC"}
+{"version":3,"file":"ris-document.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/ris-document.resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAa3E,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;GA8F9B,CAAC"}

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

@@ -3,14 +3,15 @@
  * of ris_get_document. Reads the same content path (HTML rendition converted to markdown) for
  * an (application, documentNumber) pair. Applications with no text rendition (authentic-PDF-only,
  * PDF-only, or metadata-only) return a short note pointing at the usable artifact instead of
- * text. Oversized text degrades to the same §/Artikel/Anlage section outline the tool emits,
- * plus a note pointing at ris_get_document (which carries the sections selector this bare-string
- * resource cannot). Backed by the shared renderDocument helper from the tool definition.
+ * text. Oversized text degrades to the same outline the tool emits — §/Artikel/Anlage sections,
+ * or `Part n of N` byte windows where the rendition carries no such headings — plus a note
+ * pointing at ris_get_document (which carries the sections selector this bare-string resource
+ * cannot). Backed by the shared renderDocument helper from the tool definition.
  * @module mcp-server/resources/definitions/ris-document
  */
 import { resource, z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
-import { exampleSectionNames, outlineDocument, renderDocument, renderOutlineSections, } from '../../../mcp-server/tools/definitions/ris-get-document.tool.js';
+import { addressableSections, exampleSectionNames, outlineDocument, renderDocument, renderOutlineSections, } from '../../../mcp-server/tools/definitions/ris-get-document.tool.js';
 import { RIS_APPLICATIONS } from '../../../services/ris/reference/index.js';
 const APPLICATION_CODES = RIS_APPLICATIONS.map((app) => app.code);
 export const risDocumentResource = resource('ris://document/{application}/{documentNumber}', {
@@ -18,6 +19,7 @@ export const risDocumentResource = resource('ris://document/{application}/{docum
     title: 'RIS Document (Markdown)',
     description: 'Markdown text of one RIS document — the injectable twin of ris_get_document (markdown format). Addressed by application code and technical document number, both copied verbatim from a ris_search_* or ris_lookup_citation result. Applications that publish no text rendition (district/municipal promulgations, court rules, party-transparency decisions, council minutes, and the 1848–1940 imperial gazettes) return a short note pointing at the authentic PDF or scan instead.',
     mimeType: 'text/markdown',
+    cacheHint: { ttlMs: 86_400_000, cacheScope: 'public' },
     params: z.object({
         application: z
             .enum(APPLICATION_CODES)
@@ -79,9 +81,13 @@ export const risDocumentResource = resource('ris://document/{application}/{docum
             return rendition.unavailableNotice;
         if (rendition.text === undefined)
             return '';
-        // Oversized markdown degrades to a section outline plus a notice pointing at the
+        // Oversized markdown degrades to an outline plus a notice pointing at the
         // ris_get_document tool — this bare-string surface carries no section selector.
-        const decision = outlineDocument(rendition.text, (sections) => `Document too large to inline${rendition.byteSize !== undefined ? ` (${rendition.byteSize} bytes)` : ''}. Use the ris_get_document tool with sections:[…] to retrieve specific sections — e.g. ${exampleSectionNames(sections)}. This resource carries no section selector.`);
+        const addressable = addressableSections(rendition.text, 'markdown');
+        const size = rendition.byteSize !== undefined ? ` (${rendition.byteSize} bytes)` : '';
+        const decision = outlineDocument(rendition.text, addressable, (sections) => addressable[0]?.kind === 'window'
+            ? `Document too large to inline${size}. It carries no §/Artikel/Anlage headings, so it is listed as ${sections.length} contiguous windows cut at line breaks — read them in the order they are named. Use the ris_get_document tool with sections:[…] to retrieve one — e.g. ${exampleSectionNames(addressable)}. This resource carries no selector.`
+            : `Document too large to inline${size}. Use the ris_get_document tool with sections:[…] to retrieve specific sections — e.g. ${exampleSectionNames(sections)}. This resource carries no section selector.`);
         return decision.kind === 'full'
             ? decision.text
             : `${renderOutlineSections(decision.sections)}\n\n${decision.notice}`;

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

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

package/dist/mcp-server/tools/definitions/_shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_shared.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_shared.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAsB3C;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,aAMwE,CAAC;AAEnG;;;;;GAKG;AACH,KAAK,mBAAmB,GAAG,eAAe,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;AAEnF,kEAAkE;AAClE,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,mBAAmB,CAAC,CAAC;IAC9C,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC,mBAAmB,CAAC,CAAC;CAC7D;AAoBD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAMlF;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,GAC1D,OAAO,CAWT"}
+{"version":3,"file":"_shared.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/_shared.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAsB3C;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,aAMwE,CAAC;AAEnG;;;;;GAKG;AACH,KAAK,mBAAmB,GAAG,eAAe,GAAG,gBAAgB,GAAG,kBAAkB,CAAC;AAEnF,kEAAkE;AAClE,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,mBAAmB,CAAC,CAAC;IAC9C,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC,mBAAmB,CAAC,CAAC;CAC7D;AAkBD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAMlF;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,GAC1D,OAAO,CAWT"}

package/dist/mcp-server/tools/definitions/_shared.js

@@ -41,7 +41,6 @@ export const isoDateString = z
  *
  * - `ValidationError` — a schema-valid but unsupported parameter combination the request
  *   builder rejected locally, before any upstream call.
- * - `InvalidParams` — RIS rejected a parameter value in its in-band error envelope.
  * - `ServiceUnavailable` — RIS unreachable, degraded, or serving an HTML error page.
  * - `Timeout` — the request deadline elapsed. Its own reason rather than a widened
  *   `upstream_error` guard: `ctx.fail` resolves the code from the contract entry, so folding
@@ -49,7 +48,6 @@ export const isoDateString = z
  */
 const REASON_BY_CODE = new Map([
     [JsonRpcErrorCode.ValidationError, 'invalid_query'],
-    [JsonRpcErrorCode.InvalidParams, 'invalid_query'],
     [JsonRpcErrorCode.ServiceUnavailable, 'upstream_error'],
     [JsonRpcErrorCode.Timeout, 'upstream_timeout'],
 ]);

package/dist/mcp-server/tools/definitions/_shared.js.map

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

package/dist/mcp-server/tools/definitions/ris-get-document.tool.d.ts

@@ -10,11 +10,11 @@
  * metadata-only) — a text-format request against a non-text application degrades to a
  * `format_unavailable` notice on a success result, never an error. Markdown conversion drops
  * the `.sr-only` screen-reader twin RIS ships beside every abbreviated citation, keeping the
- * visible form; `html` and `xml` pass through untouched. Oversized markdown carrying
- * §/Artikel/Anlage structure overflows to a retrievable section outline (never a silent
- * truncation, and never for a rendition with no such headings); a follow-up call
- * with `sections:[…]` returns just the chosen sections, and a selector matching nothing gets
- * the outline back with a notice rather than the whole document. The shared
+ * visible form; `html` and `xml` pass through untouched. Oversized markdown overflows to a
+ * retrievable outline rather than a silent truncation — its §/Artikel/Anlage sections, or
+ * `Part n of N` byte windows where it carries no such headings; a follow-up call with
+ * `sections:[…]` returns just the chosen entries, and a selector matching nothing gets the
+ * outline back with a notice rather than the whole document. The shared
  * {@link renderDocument} helper backs both this tool and the `ris://document/…` resource.
  * @module mcp-server/tools/definitions/ris-get-document
  */
@@ -24,20 +24,22 @@ import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { type OutlineResult, type SectionMeta } from '@cyanheads/mcp-ts-core/utils';
 import type { RisBindingStatus } from '../../../services/ris/reference/index.js';
 /** Requested output format. `markdown` and `html` both read the HTML rendition. */
-type DocumentFormat = 'markdown' | 'html' | 'xml' | 'urls_only';
+export type DocumentFormat = 'markdown' | 'html' | 'xml' | 'urls_only';
 /**
- * Serialized-length budget for inlining document text. Above it, markdown overflows to a
- * §/Artikel/Anlage section outline instead of returning whole — but only when the rendition
- * segments into at least two of those sections. A rendition carrying none of them has nothing
- * to outline and returns whole however large: court decisions, gazette and announcement
- * bodies, and consolidated `§ 0` promulgation records all do, measured live to 399,972 bytes
- * on a Bvwg decision.
+ * Serialized-length budget for inlining document text, and the size of one addressable
+ * window. Above it, markdown overflows to an outline instead of returning whole — its
+ * §/Artikel/Anlage sections where it carries at least two such headings, else the byte
+ * windows {@link windowDocument} cuts, so a rendition the segmenter cannot split is
+ * retrievable rather than returned whole at any size (court decisions, gazette and
+ * announcement bodies, and consolidated `§ 0` promulgation records all carry no headings,
+ * measured live to 399,972 bytes on a Bvwg decision).
  *
  * Sized against what one tool result can carry into a working context (≈10K tokens of legal
  * prose), not against what counts as a pathological document: across live samples the
  * documents callers routinely read land well under it — consolidated-law sections at 2–3 KB,
  * drafts and bills at 6–36 KB — while the multi-act bills and long translations that motivated
- * the outline (71 KB–199 KB) route through it.
+ * the outline (71 KB–199 KB) route through it. One number serves both roles because a window
+ * is by definition one result's worth, which is what the budget already means.
  *
  * Handed to `outlineOnOverflow`, which measures `JSON.stringify` length (≈ UTF-8 bytes for
  * the mostly-Latin legal text); the exact `byte_size` is reported separately.
@@ -91,16 +93,22 @@ type ParsedDocumentUrl = {
  */
 export declare function parseDocumentUrl(url: string, contentBaseUrl: string): ParsedDocumentUrl;
 /**
- * One addressable section of a rendered RIS document — a structural unit sliced from its
- * heading up to the next, plus the leading `Präambel` when the document opens with text
- * before its first heading.
+ * One addressable entry of a rendered RIS document. Two kinds, never mixed in one roster:
+ * a `section` is a structural unit sliced from its heading up to the next (plus the leading
+ * `Präambel` when the document opens with text before its first heading); a `window` is a
+ * contiguous byte slice of a document carrying no such headings.
  */
 export interface DocumentSection {
-    /** UTF-8 byte size of the section text. */
+    /** UTF-8 byte size of the entry's text. */
     readonly bytes: number;
-    /** Section identifier — a §/Artikel/Anlage marker, article-qualified so names stay unique. */
+    /** Which roster this entry belongs to — see {@link addressableSections}. */
+    readonly kind: 'section' | 'window';
+    /**
+     * Entry identifier — a §/Artikel/Anlage marker (article-qualified so names stay unique)
+     * for a section, `Part n of N` for a window.
+     */
     readonly name: string;
-    /** The section's text, from its heading up to the next heading. */
+    /** The entry's text: heading to next heading for a section, line to line for a window. */
     readonly text: string;
 }
 /**
@@ -112,40 +120,93 @@ export interface DocumentSection {
  * html/xml rendition) — the caller reads that as "nothing to outline".
  */
 export declare function segmentDocument(text: string): DocumentSection[];
+/**
+ * Cut rendered document text into near-even windows snapped to line boundaries, named
+ * `Part 1 of N` … `Part N of N` in document order. The retrieval path for a rendition
+ * {@link segmentDocument} cannot split; returns `[]` under the budget and for text that
+ * carries no line break to cut on, which the caller reads as "nothing to outline".
+ *
+ * Even windows rather than fill-the-budget windows: filling leaves a runt tail (a 40,440-byte
+ * decision splits 39,602 + 838, buying a round-trip for a scrap) while an even split of the
+ * same document is 20,196 + 20,244. Each window's target is the bytes still unassigned over
+ * the windows still to cut, so the remainder that snapping to the next line break carries
+ * forward is spread across the rest instead of piling onto the tail.
+ *
+ * Two rules keep the budget a ceiling rather than an aspiration. A window never takes a line
+ * that would carry it past the budget, so snapping to the next line break cannot overshoot;
+ * and when the tail still lands over — the target sitting just under the budget leaves the
+ * last window everything the earlier ones declined — the window count rises until every
+ * window fits. A line longer than the budget is the exception, and the reason the count stops
+ * rising rather than climbing to one window per line: splitting inside a line would put the
+ * cut where the caller cannot see it, so such a line sits alone in a window that goes over.
+ *
+ * Window bytes sum to the document's byte size exactly — the windows concatenate back to the
+ * input, so nothing is dropped or double-counted.
+ */
+export declare function windowDocument(text: string, budget: number): DocumentSection[];
+/**
+ * The one roster of what a caller can address in a rendition — §/Artikel/Anlage sections
+ * where the markdown carries at least two of them, else the byte windows an over-budget
+ * document is cut into. Both the outline and the `sections:[…]` selector resolve through
+ * here, so every entry the outline advertises is retrievable by name.
+ *
+ * Markdown only. `html` and `xml` are byte-identical passthroughs of the published artifact
+ * and a mid-document slice of either is not well-formed, so they stay whole at any size and
+ * a caller who needs one has `content_urls`.
+ *
+ * The two-entry floor matches `outlineOnOverflow`'s own short-circuit: an outline whose only
+ * possible `sections` argument returns the same bytes costs a round-trip and buys nothing.
+ */
+export declare function addressableSections(text: string, format: DocumentFormat): DocumentSection[];
 /** Outcome of resolving a `sections:[…]` selector against a rendered document. */
 export interface SectionSelection {
-    /** The document's whole section roster, largest first — what the caller can re-pick from. */
+    /**
+     * The document's whole entry roster — what the caller can re-pick from. Sections come
+     * largest first; windows keep document order (see {@link outlineDocument}).
+     */
     readonly available: SectionMeta[];
-    /** Concatenated text of the matched sections, in document order; `''` when none matched. */
+    /** Concatenated text of the matched entries, in document order; `''` when none matched. */
     readonly text: string;
-    /** Requested names that matched no section, in the order requested. */
+    /** Requested names that matched no entry, in the order requested. */
     readonly unmatched: string[];
+    /** Whether `available` lists byte windows rather than §/Artikel/Anlage sections. */
+    readonly windowed: boolean;
 }
 /**
  * Resolve a `sections:[…]` selector against rendered document text — the selective-retrieval
- * counterpart to the outline. The handler re-fetches the document (the upstream query is
- * deterministic, so it reproduces the same text) and slices it to the requested sections.
+ * counterpart to the outline, resolving through the same {@link addressableSections} roster
+ * so every advertised name retrieves. The handler re-fetches the document (the upstream query
+ * is deterministic, so it reproduces the same text) and slices it to the requested entries.
  * Reports the unmatched names and the full roster alongside the matched text so the handler
  * can disclose a mismatch instead of silently returning something the caller didn't ask for.
  */
-export declare function selectDocumentSections(text: string, want: readonly string[]): SectionSelection;
+export declare function selectDocumentSections(text: string, want: readonly string[], format: DocumentFormat): SectionSelection;
 /**
  * Apply the outline-on-overflow contract to rendered document text: whole under the byte
- * budget (or with fewer than two structural sections), else a section outline. Shares
- * {@link segmentDocument} as the section extractor so the tool and the resource segment
- * identically; the `notice` builder is caller-specific (each points at its own re-call).
+ * budget (or with fewer than two addressable entries), else an outline of `roster`. The
+ * caller passes the roster it already resolved through {@link addressableSections}, so the
+ * outline it advertises and the wording of its notice describe the same entries; the `notice`
+ * builder is caller-specific (each points at its own re-call).
+ *
+ * `outlineOnOverflow` sorts entries largest first and offers no opt-out. That reads as a menu
+ * for a section roster, where the names say what each entry is. A window roster is a reading
+ * sequence, and a caller that walks `sections` in array order — the obvious way to read one
+ * — would take the document out of order, so document order is restored for it here.
  */
-export declare function outlineDocument(text: string, notice: (sections: SectionMeta[]) => string): OutlineResult<{
+export declare function outlineDocument(text: string, roster: readonly DocumentSection[], notice: (sections: SectionMeta[]) => string): OutlineResult<{
     text: string;
 }>;
 /** Name the three largest sections, quoted, as examples for a re-call notice. */
 export declare function exampleSectionNames(sections: readonly SectionMeta[]): string;
 /**
- * Render an outline — the section roster the agent picks from — to markdown. Shared by the
- * tool's `format()` (as a content block) and the resource (as its body), so both client
- * surfaces list identical sections. Deliberately says nothing about *why* the outline was
- * returned: the tool emits one both on a byte overflow and on an unmatched `sections`
- * selector, and the accompanying notice is what separates the two.
+ * Render an outline — the roster the agent picks from — to markdown. Shared by the tool's
+ * `format()` (as a content block) and the resource (as its body), so both client surfaces
+ * list identical entries. A roster is all sections or all windows ({@link addressableSections}
+ * never mixes them), and the heading names which, since this surface carries only names and
+ * byte sizes: windows are a reading sequence listed in document order, sections a menu listed
+ * largest first. Deliberately says nothing about *why* the outline was returned: the tool
+ * emits one both on a byte overflow and on an unmatched `sections` selector, and the
+ * accompanying notice is what separates the two.
  */
 export declare function renderOutlineSections(sections: readonly SectionMeta[]): string;
 /**