@cyanheads/ris-austria-mcp-server 0.2.6 → 0.3.0

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Server:** ris-austria-mcp-server
-**Version:** 0.2.6
+**Version:** 0.3.0
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.0`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Server:** ris-austria-mcp-server
-**Version:** 0.2.6
+**Version:** 0.3.0
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.11.0`
 **Engines:** Bun ≥1.3.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/sdk` ^1.29.0

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.2.6-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.3.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/)
 
 </div>
 
@@ -96,7 +96,8 @@ Search federal law before it is enacted.
 - `stage: review_drafts` covers ministerial drafts in public review (Begutachtungsentwürfe). `in_review_on` answers what is in review on a given date
 - `stage: government_bills` covers bills adopted by the council of ministers (Regierungsvorlagen, 2004+), filtered by adoption date
 - `ministry` accepts the abbreviation ("BMF") and the server expands it to RIS's exact designation
-- Output includes review deadlines and council adoption dates
+- Output includes review deadlines, council adoption dates, and the RIS web view
+- `materials` lists the companion documents filed with the draft — Erläuterungen (the drafting reasoning the bill text omits), Textgegenüberstellung, Vorblatt/WFA, covering letter, annexes. Their filenames are opaque and per-record, so passing a `materials[].urls` entry to `ris_get_document` is the only way to read one
 
 ---
 
@@ -107,6 +108,7 @@ Sectoral official gazettes and executive documents: seven collections, five of t
 - `collection`: `social_insurance` (Avsv), `veterinary` (Avn), `court_rules` (KmGer), `trade_exam_rules` (PruefGewO), `health_structure_plans` (Spg, ÖSG/RSG), `ministerial_decrees` (Erlässe), `council_minutes` (Ministerratsprotokolle)
 - Collection-aware filters: issue numbers, issuers (insurance carriers, ministries), cited norm ("decrees citing the DSG"), in-force date for the consolidated collections, plan type and state for health plans, session number and legislature for council minutes
 - Binding labels per collection: `authentic`, `administrative_directive` (decrees bind the administration, not citizens), or `preparatory` (council minutes)
+- Every record carries the RIS web view — the only browsable surface for the PDF-only council minutes and for ministerial decrees
 
 ---
 
@@ -126,11 +128,12 @@ Resolve a citation to its canonical document.
 
 Read and export a single document.
 
-- Addresses documents by `document_number` plus `application` (from any search or lookup result), or by a passed-through `ris.bka.gv.at` document URL (host and path allowlisted)
+- Addresses documents by `document_number` plus `application` (from any search or lookup result), or by a passed-through `ris.bka.gv.at` document URL (host and path allowlisted) — including a draft's companion documents from `ris_search_drafts`'s `materials`, which nothing else can reach
 - `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
-- Oversized markdown returns a §/Artikel/Anlage section outline (`kind: outline`) instead of truncating. Re-call with `sections:[…]` to pull the sections you need
+- 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
 - 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
 
 ---

package/changelog/0.2.x/0.2.7.md

@@ -0,0 +1,17 @@
+---
+summary: "Search-tool rejections now name the caller's own parameter and value instead of internal service identifiers and RIS application codes, and an out-of-range page leads the recovery hint on all five search tools."
+breaking: false
+security: false
+---
+
+# 0.2.7 — 2026-07-31
+
+## Fixed
+
+- **Local rejections name the caller's own input** — `ris_search_case_law`, `ris_search_gazette`, and `ris_search_announcements` rewrite request-builder rejections at their existing `.catch()` into the tool's own vocabulary before they reach the wire. A rejection previously read the builder's internal service param name and RIS application code (e.g. `sortBy`, `Normenliste`) instead of the field and value the caller actually sent (`sort_by`, `court: 'normenliste'`). `unsupported()` in `request-builder.ts` now carries the rejection as separate `param`, `value`, and `alternatives` data instead of one fused `sortBy: <value>` identifier; `rewriteUnsupportedParam` (new, `_shared.ts`) reads that data and swaps in each tool's own message, or leaves the builder's message untouched when the tool has nothing more precise to say. ([#29](https://github.com/cyanheads/ris-austria-mcp-server/issues/29))
+- **Gazette rejections name the routing input** — `resolveFederalTier` now returns `routedBy` (the `number`, `part`, or date bound that selected a federal era tier), and `gazetteLabel` (new) names the resolved gazette by that selection so `type`/`part`/`issuer`/`number`/`sort_by` rejections state which tier or scope rejected the field, rather than an internal application code. Each corrective was checked against the live API to hold for every call it answers.
+- **Out-of-range `page` recovery** — all five search tools (`ris_search_legislation`, `ris_search_case_law`, `ris_search_gazette`, `ris_search_drafts`, `ris_search_announcements`) lead their `invalid_query` recovery hint with "For a page past the end, request a lower page, starting from 1" ahead of the existing per-tool guidance, and their `when` clause now names the out-of-range page as a cause. ([#30](https://github.com/cyanheads/ris-austria-mcp-server/issues/30))
+
+## Changed
+
+- `docs/design.md`'s `invalid_query` rows for all five search tools reconciled with the shipped `when`/`recovery` text.

package/changelog/0.3.x/0.3.0.md

@@ -0,0 +1,18 @@
+---
+summary: "ris_search_drafts surfaces a draft's companion documents and both it and ris_search_announcements gain the RIS web view; ris_get_document fetches a companion by URL and its outline budget is re-derived to 40,000 bytes."
+breaking: false
+security: false
+---
+
+# 0.3.0 — 2026-07-31
+
+## Added
+
+- **`ris_search_drafts` `materials`** — records now carry the companion documents filed with a draft (Erläuterungen, Textgegenüberstellung, Vorblatt/WFA, the Begleitschreiben covering letter, and Attachment annexes) as `{type, name, urls}`. Coverage is per-record; `type` is `Material`, `Letter`, or `Attachment` and is the reliable discriminator — `name` is free text RIS varies across records. Empty when the ministry filed none. ([#26](https://github.com/cyanheads/ris-austria-mcp-server/issues/26))
+- **`ris_get_document` companion-document fetch** — `document_url` now accepts a `Materialien_`/`Schreiben_`/`Anlagen_` filename (a `materials[].urls` entry) and fetches it inside the parent document's folder instead of rejecting it — previously the only route to these documents. `content_urls` for a companion carries its own XML/HTML/PDF; RTF is present on roughly 40% of them and there is no `.pdfsig`. `RisService.buildDocumentContentUrl` gains an optional `contentName` parameter, held to the same safe-character pattern as the document number. ([#26](https://github.com/cyanheads/ris-austria-mcp-server/issues/26))
+- **`ris_search_drafts` and `ris_search_announcements` `document_url`** — both records now carry the RIS web view (`Allgemein.DokumentUrl`), matching `ris_search_gazette` and `ris_track_changes`. It is the only browsable surface for the PDF-only `council_minutes` collection and for `ministerial_decrees`. ([#32](https://github.com/cyanheads/ris-austria-mcp-server/issues/32))
+
+## Changed
+
+- **`ris_get_document` outline budget** — `OUTLINE_BUDGET_BYTES` (now exported) lowered from 500,000 to 40,000 bytes, re-derived against 61 live renditions sampled across nine applications. The prior threshold was calibrated before the screen-reader-twin strip roughly halved rendered byte counts, so it had stopped firing on the multi-hundred-KB bills it was sized for. The budget bounds only markdown carrying at least two §/Artikel/Anlage headings — a rendition without them (most court decisions, many gazette and announcement bodies, all raw html/xml) returns whole at any size. ([#31](https://github.com/cyanheads/ris-austria-mcp-server/issues/31))
+- **Partial-section-match notice** — no longer tells the caller to re-call `ris_get_document` without `sections:[…]` for an outline, since that re-call only returns one for documents over the budget. It now names candidate section names to copy verbatim for the re-call instead. ([#31](https://github.com/cyanheads/ris-austria-mcp-server/issues/31))

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

@@ -37,5 +37,28 @@ interface SearchFailureContext {
  * Returns the error for the caller to `throw`, keeping the throw visible at the call site.
  */
 export declare function failSearchError(error: unknown, ctx: SearchFailureContext): unknown;
+/** A request-builder unsupported-parameter rejection, as the builder recorded it. */
+export interface UnsupportedParam {
+    /** Values of the same parameter that *are* mapped for the target application. */
+    readonly alternatives: readonly string[];
+    /** The builder's own parameter name, e.g. `sortBy`. */
+    readonly param: string;
+    /** The rejected value, when the rejection was value-specific. */
+    readonly value?: string;
+}
+/**
+ * Replace the request builder's unsupported-parameter message with one written in the
+ * calling tool's own vocabulary, so the caller reads back a field it actually sent.
+ *
+ * The builder holds only the resolved RIS application, never the tool input that selected
+ * it, so it cannot name the caller's `court`/`scope`/`collection` itself. The handler still
+ * has that input in scope here, and `rewrite` returns the finished message — or `undefined`
+ * to leave a combination the tool has nothing better to say about untouched.
+ *
+ * `param` and `application` appearing together identify that rejection; the builder's other
+ * `validationError`s (state coverage, ministry expansion) already name what the caller sent
+ * and pass through unchanged, as does every error from the service.
+ */
+export declare function rewriteUnsupportedParam(error: unknown, rewrite: (rejected: UnsupportedParam) => string | undefined): unknown;
 export {};
 //# sourceMappingURL=_shared.d.ts.map

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"}
+{"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"}

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

@@ -4,7 +4,7 @@
  * @module mcp-server/tools/definitions/_shared
  */
 import { z } from '@cyanheads/mcp-ts-core';
-import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
+import { JsonRpcErrorCode, McpError, validationError } from '@cyanheads/mcp-ts-core/errors';
 /** Months with 30 days — the only non-February lengths a day of 31 can overshoot. */
 const THIRTY_DAY_MONTHS = new Set([4, 6, 9, 11]);
 /**
@@ -69,4 +69,31 @@ export function failSearchError(error, ctx) {
         ? error
         : ctx.fail(reason, error.message, { ...ctx.recoveryFor(reason) });
 }
+/**
+ * Replace the request builder's unsupported-parameter message with one written in the
+ * calling tool's own vocabulary, so the caller reads back a field it actually sent.
+ *
+ * The builder holds only the resolved RIS application, never the tool input that selected
+ * it, so it cannot name the caller's `court`/`scope`/`collection` itself. The handler still
+ * has that input in scope here, and `rewrite` returns the finished message — or `undefined`
+ * to leave a combination the tool has nothing better to say about untouched.
+ *
+ * `param` and `application` appearing together identify that rejection; the builder's other
+ * `validationError`s (state coverage, ministry expansion) already name what the caller sent
+ * and pass through unchanged, as does every error from the service.
+ */
+export function rewriteUnsupportedParam(error, rewrite) {
+    if (!(error instanceof McpError))
+        return error;
+    const { data } = error;
+    if (typeof data?.param !== 'string' || typeof data.application !== 'string')
+        return error;
+    const { alternatives, param, value } = data;
+    const message = rewrite({
+        alternatives: Array.isArray(alternatives) ? alternatives : [],
+        param,
+        ...(typeof value === 'string' && { value }),
+    });
+    return message === undefined ? error : validationError(message, data);
+}
 //# sourceMappingURL=_shared.js.map

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":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAE3E,qFAAqF;AACrF,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAEjD;;;;GAIG;AACH,SAAS,kBAAkB,CAAC,KAAa;IACvC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IACvC,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;QAChB,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,GAAG,KAAK,CAAC,IAAI,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC;QAC1E,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC;KAC3B,MAAM,EAAE;KACR,KAAK,CACJ,oDAAoD,EACpD,mDAAmD,CACpD;KACA,MAAM,CAAC,kBAAkB,EAAE,mEAAmE,CAAC,CAAC;AAgBnG;;;;;;;;;;GAUG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,CAAwC;IACpE,CAAC,gBAAgB,CAAC,eAAe,EAAE,eAAe,CAAC;IACnD,CAAC,gBAAgB,CAAC,aAAa,EAAE,eAAe,CAAC;IACjD,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,gBAAgB,CAAC;IACvD,CAAC,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,CAAC;CAC/C,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc,EAAE,GAAyB;IACvE,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/C,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC9C,OAAO,MAAM,KAAK,SAAS;QACzB,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AACtE,CAAC"}
+{"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

@@ -2,13 +2,16 @@
  * @fileoverview ris_get_document — read one RIS document's full text (markdown/html/xml)
  * or its rendition URLs, with explicit binding status and the amtssigniert Authentisch PDF
  * surfaced wherever it exists. Two addressing modes route to the same fetch path:
- * `document_number` + `application`, or a `document_url` from a result's content_urls.
+ * `document_number` + `application`, or a `document_url` from a result's content_urls — the
+ * latter also carrying the one route to a draft's companion documents (`Materialien_`,
+ * `Schreiben_`, `Anlagen_`), whose per-record opaque filenames no document number reaches.
  * Format availability varies by application (full text · authentic-PDF-only · PDF-only ·
  * 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 overflows to a
- * retrievable §/Artikel/Anlage section outline (never a silent truncation); a follow-up call
+ * 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
  * {@link renderDocument} helper backs both this tool and the `ris://document/…` resource.
@@ -21,6 +24,24 @@ import { type OutlineResult, type SectionMeta } from '@cyanheads/mcp-ts-core/uti
 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';
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Handed to `outlineOnOverflow`, which measures `JSON.stringify` length (≈ UTF-8 bytes for
+ * the mostly-Latin legal text); the exact `byte_size` is reported separately.
+ */
+export declare const OUTLINE_BUDGET_BYTES = 40000;
 /** Constructed rendition URLs for a document, keyed by DataType. */
 interface RenditionContentUrls {
     html?: string;
@@ -28,7 +49,11 @@ interface RenditionContentUrls {
     rtf?: string;
     xml?: string;
 }
-/** A resolved document rendition — the shared unit behind the tool and the resource. */
+/**
+ * A resolved document rendition — the shared unit behind the tool and the resource. A
+ * companion document resolves to the same shape, addressed by `contentName` inside the
+ * parent document's folder.
+ */
 export interface DocumentRendition {
     /** Application code the document belongs to (echoed). */
     readonly application: string;
@@ -52,6 +77,8 @@ export interface DocumentRendition {
 /** Result of parsing a caller-supplied document_url into an application + document number. */
 type ParsedDocumentUrl = {
     readonly application: string;
+    /** Companion-document filename stem; absent for a main-document rendition. */
+    readonly contentName?: string;
     readonly documentNumber: string;
 } | {
     readonly error: string;
@@ -125,8 +152,12 @@ export declare function renderOutlineSections(sections: readonly SectionMeta[]):
  * and convert one RIS document. Throws framework errors (`validationError` for an unknown
  * application or unsafe document number; `notFound`/`serviceUnavailable`/`timeout` from the
  * content fetch) — callers map these onto their own typed contract.
+ *
+ * `contentName` addresses a companion document inside the same folder instead of the main
+ * rendition; the requested `format` still selects the rendition, exactly as it does for a
+ * main document.
  */
-export declare function renderDocument(applicationCode: string, documentNumber: string, format: DocumentFormat, ctx: Context): Promise<DocumentRendition>;
+export declare function renderDocument(applicationCode: string, documentNumber: string, format: DocumentFormat, ctx: Context, contentName?: string): Promise<DocumentRendition>;
 export declare const risGetDocument: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
     document_number: z.ZodOptional<z.ZodString>;
     application: z.ZodOptional<z.ZodEnum<{

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

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

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

@@ -2,13 +2,16 @@
  * @fileoverview ris_get_document — read one RIS document's full text (markdown/html/xml)
  * or its rendition URLs, with explicit binding status and the amtssigniert Authentisch PDF
  * surfaced wherever it exists. Two addressing modes route to the same fetch path:
- * `document_number` + `application`, or a `document_url` from a result's content_urls.
+ * `document_number` + `application`, or a `document_url` from a result's content_urls — the
+ * latter also carrying the one route to a draft's companion documents (`Materialien_`,
+ * `Schreiben_`, `Anlagen_`), whose per-record opaque filenames no document number reaches.
  * Format availability varies by application (full text · authentic-PDF-only · PDF-only ·
  * 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 overflows to a
- * retrievable §/Artikel/Anlage section outline (never a silent truncation); a follow-up call
+ * 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
  * {@link renderDocument} helper backs both this tool and the `ris://document/…` resource.
@@ -33,25 +36,43 @@ const BINDING_STATUSES = [
 ];
 /**
  * Serialized-length budget for inlining document text. Above it, markdown overflows to a
- * §/Artikel/Anlage section outline instead of returning whole — generous, so it fires only
- * on the pathological documents (multi-hundred-KB consolidations and government bills).
+ * §/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.
+ *
+ * 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.
+ *
  * Handed to `outlineOnOverflow`, which measures `JSON.stringify` length (≈ UTF-8 bytes for
  * the mostly-Latin legal text); the exact `byte_size` is reported separately.
  */
-const OUTLINE_BUDGET_BYTES = 500_000;
+export const OUTLINE_BUDGET_BYTES = 40_000;
 const APPLICATION_CODES = RIS_APPLICATIONS.map((app) => app.code);
 const APPLICATION_BY_CODE = new Map(RIS_APPLICATIONS.map((app) => [app.code, app]));
 /** Content-path segment → application, for reverse-mapping a passed document_url. */
 const APPLICATION_BY_SEGMENT = new Map(RIS_APPLICATIONS.flatMap((app) => app.contentPathSegment !== null ? [[app.contentPathSegment, app]] : []));
 /**
- * Lowercase file extensions a main-document rendition URL may end in — the constructible
+ * Lowercase file extensions a rendition URL may end in — the constructible
  * `RisContentFormat` set plus the derived `.pdfsig` authentic variant (see
- * {@link authenticPdfFrom}). A `document_url`'s trailing filename must be
- * `{documentNumber}.{ext}` for one of these; any other filename (a `Materialien_`/`Anlagen_…`
- * content attachment, an unknown extension) addresses non-main content this tool would
- * otherwise silently swap for the main document.
+ * {@link authenticPdfFrom}). A `document_url`'s trailing filename must carry one of these;
+ * an unknown extension addresses something this tool cannot render.
  */
 const RENDITION_EXTENSIONS = new Set([...RIS_CONTENT_FORMATS, 'pdfsig']);
+/**
+ * Filename stem of a companion document — the `Erläuterungen`, `Textgegenüberstellung`,
+ * `Vorblatt und WFA`, cover letter, and annex texts a `Begut` draft or `RegV` bill ships
+ * beside its main text, surfaced on a `ris_search_drafts` record's `materials`. RIS names
+ * them `{Materialien|Schreiben|Anlagen}_{NNNN}_{UUID}` (underscore-separated UUID), a shape
+ * every one of 2,436 companion URLs sampled live across 200 draft records matches exactly.
+ * The stem is opaque and per-record — the URL is the only handle, so nothing about a
+ * companion is reconstructible from a document number.
+ */
+const COMPANION_STEM = /^(?:Materialien|Schreiben|Anlagen)_\d{4}_[0-9A-F]{8}(?:_[0-9A-F]{4}){3}_[0-9A-F]{12}$/iu;
 /**
  * Drop RIS's screen-reader twin, pass every other span through untouched. RIS renditions
  * carry each abbreviated legal reference twice — the visible citation in
@@ -137,10 +158,11 @@ export function parseDocumentUrl(url, contentBaseUrl) {
         return { error: `"${rawDocumentNumber}" is not a decodable path segment (malformed % escape)` };
     }
     // A folder URL (…/{segment}/{documentNumber}[/]) carries no trailing filename and resolves
-    // fine. A trailing filename is a main-document rendition only when it is exactly
-    // {documentNumber}.{ext} for a known rendition extension; a content attachment
-    // (Materialien_/Anlagen_… memoranda and annexes) or any deeper nesting names non-main
-    // content the fetch would silently swap for the main document — reject it here instead.
+    // fine. A trailing filename addresses one of exactly two things: the main-document
+    // rendition, named {documentNumber}.{ext}, or a companion document, named with one of the
+    // three {@link COMPANION_STEM} prefixes. Anything else — an unknown stem, an unknown
+    // extension, deeper nesting — is content this tool would otherwise fetch blind or silently
+    // swap for the main document, so it is rejected here.
     if (filename !== undefined) {
         const decodedFilename = decodePathSegment(filename);
         if (decodedFilename === undefined) {
@@ -149,11 +171,18 @@ export function parseDocumentUrl(url, contentBaseUrl) {
         const dot = decodedFilename.lastIndexOf('.');
         const stem = dot === -1 ? decodedFilename : decodedFilename.slice(0, dot);
         const extension = dot === -1 ? '' : decodedFilename.slice(dot + 1).toLowerCase();
-        if (rest.length > 0 || stem !== documentNumber || !RENDITION_EXTENSIONS.has(extension)) {
+        const isMainDocument = stem === documentNumber;
+        const addressable = rest.length === 0 &&
+            RENDITION_EXTENSIONS.has(extension) &&
+            (isMainDocument || COMPANION_STEM.test(stem));
+        if (!addressable) {
             return {
-                error: `"${decodedFilename}" points at a content attachment or non-rendition file, not a main-document rendition — pass a main-document URL as returned in content_urls`,
+                error: `"${decodedFilename}" is neither a main-document rendition (${documentNumber}.{ext}) nor a companion document (Materialien_/Schreiben_/Anlagen_…) — pass a URL exactly as returned in a result's content_urls or materials`,
             };
         }
+        if (!isMainDocument) {
+            return { application: app.code, contentName: stem, documentNumber };
+        }
     }
     return { application: app.code, documentNumber };
 }
@@ -164,10 +193,19 @@ function authenticPdfFrom(pdfUrl) {
 /**
  * Construct the rendition URLs for a document from its application's format availability.
  * `buildDocumentContentUrl` throws `ValidationError` for an unsafe document number.
+ *
+ * A companion document (`contentName`) is published as XML, HTML and PDF; RTF only
+ * sometimes (present on 291 of 715 companion references sampled live) and the signed
+ * `.pdfsig` never — RIS 404s the renditions it does not list, so only the three it always
+ * carries are constructed.
  */
-function buildRenditionUrls(service, app, documentNumber) {
+function buildRenditionUrls(service, app, documentNumber, contentName) {
     if (app.formats === 'none')
         return { contentUrls: {} }; // BgblAlt — no content URLs to build
+    if (contentName !== undefined) {
+        const url = (format) => service.buildDocumentContentUrl(app.code, documentNumber, format, contentName);
+        return { contentUrls: { xml: url('xml'), html: url('html'), pdf: url('pdf') } };
+    }
     const pdf = service.buildDocumentContentUrl(app.code, documentNumber, 'pdf');
     const authenticPdfUrl = app.binding === 'authentic' ? authenticPdfFrom(pdf) : undefined;
     if (app.formats === 'authentic_pdf_only') {
@@ -310,8 +348,12 @@ export function renderOutlineSections(sections) {
  * and convert one RIS document. Throws framework errors (`validationError` for an unknown
  * application or unsafe document number; `notFound`/`serviceUnavailable`/`timeout` from the
  * content fetch) — callers map these onto their own typed contract.
+ *
+ * `contentName` addresses a companion document inside the same folder instead of the main
+ * rendition; the requested `format` still selects the rendition, exactly as it does for a
+ * main document.
  */
-export async function renderDocument(applicationCode, documentNumber, format, ctx) {
+export async function renderDocument(applicationCode, documentNumber, format, ctx, contentName) {
     const app = APPLICATION_BY_CODE.get(applicationCode);
     if (!app) {
         throw validationError(`Unknown RIS application "${applicationCode}".`, {
@@ -320,7 +362,7 @@ export async function renderDocument(applicationCode, documentNumber, format, ct
         });
     }
     const service = getRisService();
-    const urls = buildRenditionUrls(service, app, documentNumber);
+    const urls = buildRenditionUrls(service, app, documentNumber, contentName);
     const base = {
         application: app.code,
         bindingStatus: app.binding,
@@ -338,7 +380,7 @@ export async function renderDocument(applicationCode, documentNumber, format, ct
     if (format === 'urls_only')
         return base;
     const fetchFormat = format === 'xml' ? 'xml' : 'html';
-    const url = service.buildDocumentContentUrl(app.code, documentNumber, fetchFormat);
+    const url = service.buildDocumentContentUrl(app.code, documentNumber, fetchFormat, contentName);
     const fetched = await service.fetchDocumentContent(url, ctx);
     const rendered = format === 'markdown' ? MARKDOWN_CONVERTER.translate(fetched.text) : fetched.text;
     const encoded = new TextEncoder().encode(rendered);
@@ -356,10 +398,10 @@ const ContentUrlsSchema = z
     pdf: z.string().optional().describe('PDF rendition URL.'),
     rtf: z.string().optional().describe('RTF rendition URL.'),
 })
-    .describe('Constructed rendition URLs. Empty for authentic-PDF-only (Bvb/GrA/KmGer) and metadata-only (BgblAlt) applications — see authentic_pdf_url and the notice.');
+    .describe('Constructed rendition URLs. Empty for authentic-PDF-only (Bvb/GrA/KmGer) and metadata-only (BgblAlt) applications — see authentic_pdf_url and the notice. For a companion document (a draft’s Erläuterungen, Textgegenüberstellung, WFA, cover letter, or annex) these are the companion’s own XML/HTML/PDF, not the parent document’s.');
 export const risGetDocument = tool('ris_get_document', {
     title: 'Get RIS Document',
-    description: 'Fetch one RIS document’s full text or its rendition URLs, with explicit binding status and the amtssigniert authentic PDF surfaced wherever it exists. Address the document exactly one of two ways: document_number plus application (both copied verbatim from a ris_search_* or ris_lookup_citation result), or a document_url from a result’s content_urls. format: markdown (default — the HTML rendition converted to markdown), html (raw HTML rendition), xml (the RIS Nutzdaten XML), or urls_only (no fetch — every rendition URL, including the Authentisch PDF). Format availability varies by application and the tool degrades explicitly, never silently: consolidated law, gazettes, case law, drafts, and most sectoral collections carry full text; district and municipal promulgations and court rules (Bvb, GrA, KmGer) publish only the signed authentic PDF; party-transparency decisions and council minutes (Upts, Mrp) are PDF-only; the 1848–1940 imperial gazettes (BgblAlt) are metadata-only — for these a text-format request returns a format_unavailable notice with the usable URL, not an error. Every result carries binding_status; only authentic (amtssigniert) publications are legally binding. This tool returns content, not fresh metadata — the metadata rides the search/lookup step that produced the document number. When the markdown text overflows the byte budget the tool returns a §/Artikel/Anlage section outline (kind: outline) instead of truncating; re-call with sections:[…] naming outline entries to retrieve just those, and a name matching no section returns the outline again with a notice rather than the whole document. Markdown drops the screen-reader expansions RIS ships alongside each abbreviated citation, keeping the visible citation form; raw html/xml renditions are returned exactly as published and, carrying no markdown headings, always return in full.',
+    description: 'Fetch one RIS document’s full text or its rendition URLs, with explicit binding status and the amtssigniert authentic PDF surfaced wherever it exists. Address the document exactly one of two ways: document_number plus application (both copied verbatim from a ris_search_* or ris_lookup_citation result), or a document_url from a result’s content_urls — or, for a draft’s companion documents (Erläuterungen, Textgegenüberstellung, WFA, cover letter, annexes), from a ris_search_drafts record’s materials[].urls, which is the only route to them. format: markdown (default — the HTML rendition converted to markdown), html (raw HTML rendition), xml (the RIS Nutzdaten XML), or urls_only (no fetch — every rendition URL, including the Authentisch PDF). Format availability varies by application and the tool degrades explicitly, never silently: consolidated law, gazettes, case law, drafts, and most sectoral collections carry full text; district and municipal promulgations and court rules (Bvb, GrA, KmGer) publish only the signed authentic PDF; party-transparency decisions and council minutes (Upts, Mrp) are PDF-only; the 1848–1940 imperial gazettes (BgblAlt) are metadata-only — for these a text-format request returns a format_unavailable notice with the usable URL, not an error. Every result carries binding_status; only authentic (amtssigniert) publications are legally binding. This tool returns content, not fresh metadata — the metadata rides the search/lookup step that produced the document number. When the markdown text overflows the 40,000-byte budget and carries at least two §/Artikel/Anlage headings the tool returns a section outline (kind: outline) instead of truncating; re-call with sections:[…] naming outline entries to retrieve just those, and a name matching no section returns the outline again with a notice rather than the whole document. Outlining needs those headings: a rendition without them — most court decisions, many gazette and announcement bodies, and every raw html/xml rendition — has nothing to outline and returns whole at any size. Markdown drops the screen-reader expansions RIS ships alongside each abbreviated citation, keeping the visible citation form; raw html/xml renditions are returned exactly as published.',
     annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     input: z.object({
         document_number: z
@@ -373,7 +415,7 @@ export const risGetDocument = tool('ris_get_document', {
         document_url: z
             .string()
             .optional()
-            .describe('A https://www.ris.bka.gv.at/Dokumente/… main-document rendition URL as returned in a result’s content_urls — the alternative to document_number + application. Must address a main-document rendition ({documentNumber}.{ext}); content-attachment URLs (Materialien_/Anlagen_… memoranda and annexes) are not fetchable this way.'),
+            .describe('A https://www.ris.bka.gv.at/Dokumente/… rendition URL as returned in a result’s content_urls — the alternative to document_number + application. Also the only way to read a draft’s companion documents: pass a URL from a ris_search_drafts record’s materials[].urls (Materialien_/Schreiben_/Anlagen_… — the Erläuterungen, Textgegenüberstellung, WFA, cover letter, or annex), whose filenames are opaque and per-record and so cannot be reached through document_number. Any other filename is rejected.'),
         format: z
             .enum(['markdown', 'html', 'xml', 'urls_only'])
             .default('markdown')
@@ -381,7 +423,7 @@ export const risGetDocument = tool('ris_get_document', {
         sections: z
             .array(z.string())
             .optional()
-            .describe('Section names to retrieve, each copied verbatim from a prior outline response (kind: outline). Omit for the full document — which returns a §/Artikel/Anlage outline instead when the markdown overflows the byte budget. A name that matches no section is never silently ignored: a total miss returns the outline (kind: outline) with a notice, a partial miss returns the matched sections with a notice naming the rest. Applies to markdown only — html, xml, and urls_only carry no headings to select from and return in full.'),
+            .describe('Section names to retrieve, each copied verbatim from a prior outline response (kind: outline). Omit for the full document — which returns a §/Artikel/Anlage outline instead when the markdown overflows the 40,000-byte budget and carries at least two such headings. A name that matches no section is never silently ignored: a total miss returns the outline (kind: outline) with a notice, a partial miss returns the matched sections with a notice naming other sections to pick from. Applies to markdown only — html, xml, and urls_only carry no headings to select from and return in full.'),
     }),
     output: z.object({
         text: z
@@ -465,6 +507,7 @@ export const risGetDocument = tool('ris_get_document', {
         const failAddressing = (message) => ctx.fail('invalid_addressing', message, { ...ctx.recoveryFor('invalid_addressing') });
         let resolvedApplication;
         let resolvedDocumentNumber;
+        let resolvedContentName;
         if (documentUrl !== undefined) {
             if (documentNumber !== undefined || application !== undefined) {
                 throw failAddressing('Provide document_url OR document_number + application, not both addressing modes.');
@@ -477,6 +520,7 @@ export const risGetDocument = tool('ris_get_document', {
             }
             resolvedApplication = parsed.application;
             resolvedDocumentNumber = parsed.documentNumber;
+            resolvedContentName = parsed.contentName;
         }
         else {
             if (documentNumber === undefined || application === undefined) {
@@ -486,7 +530,7 @@ export const risGetDocument = tool('ris_get_document', {
             resolvedDocumentNumber = documentNumber;
         }
         // Map framework errors from resolution/fetch onto this tool's declared contract.
-        const rendition = await renderDocument(resolvedApplication, resolvedDocumentNumber, format, ctx).catch((err) => {
+        const rendition = await renderDocument(resolvedApplication, resolvedDocumentNumber, format, ctx, resolvedContentName).catch((err) => {
             if (err instanceof McpError) {
                 if (err.code === JsonRpcErrorCode.ValidationError) {
                     throw ctx.fail('invalid_addressing', err.message, {
@@ -538,7 +582,10 @@ export const risGetDocument = tool('ris_get_document', {
             const selection = selectDocumentSections(rendition.text, requestedSections);
             if (selection.text !== '') {
                 if (selection.unmatched.length > 0) {
-                    ctx.enrich.notice(`Returned only the matched sections — ${quoteNames(selection.unmatched)} named no section of this document and ${selection.unmatched.length === 1 ? 'was' : 'were'} skipped. Re-call ris_get_document without sections:[…] for the outline of all ${selection.available.length} §/Artikel/Anlage sections.`);
+                    // Names candidates from the roster rather than promising an outline on a re-call
+                    // without sections:[…] — that re-call only outlines a document over the byte
+                    // budget, and returns the whole text for every document under it.
+                    ctx.enrich.notice(`Returned only the matched sections — ${quoteNames(selection.unmatched)} named no section of this document and ${selection.unmatched.length === 1 ? 'was' : 'were'} skipped. This document has ${selection.available.length} §/Artikel/Anlage sections; copy a name verbatim and re-call ris_get_document with the same addressing — e.g. ${exampleSectionNames(selection.available)}.`);
                 }
                 return {
                     ...base,