typespec-http-mcp 0.1.0 → 0.2.0

package/README.md

@@ -18,10 +18,13 @@ options:
 Install it as a **devDependency**: nothing it emits imports it.
 
 ```sh
-pnpm add -D typespec-http-mcp
+pnpm add -D typespec-http-mcp @typespec/compiler @typespec/http @typespec/openapi
 pnpm add @modelcontextprotocol/server zod
 ```
 
+Install the three `@typespec` packages at one version, 1.15 or later: left to a package manager,
+`@typespec/openapi` is installed at its newest, which needs the newest compiler.
+
 ## What it emits, and what you write
 
 The generated file is **never edited, only called**. You own the `McpServer`, the transport and the

package/dist/src/bodies.d.ts

@@ -1,4 +1,4 @@
-import type { EmittedResponse, EmittedRoute, RouteSchemaNames } from "typespec-http-zod";
+import { type EmittedResponse, type EmittedRoute, isJsonMediaType, type ResultMember as LibraryResultMember, type RouteSchemaNames } from "typespec-http-zod";
 /**
  * **What each declared response body IS, decided once, for the renderer, the refusals and the runtime.**
  *
@@ -11,42 +11,24 @@ import type { EmittedResponse, EmittedRoute, RouteSchemaNames } from "typespec-h
  * Pure: it reads the library's types and nothing else, so the renderer can use it without reaching
  * the compiler.
  */
-/** A media type whose body is a JSON value. The library's own rule, and the runtime's. */
-export declare function isJsonMediaType(type: string): boolean;
-/** A media range such as `image/*`, rather than a type a response can be sent as. */
-export declare function isMediaRange(mediaType: string): boolean;
 /**
- * A media type MCP has a content block for: `image/*` and `audio/*`, which carry base64 data and
- * the media type itself. A wildcard within one is a type the handler names when it answers.
- */
-export declare function hasContentBlock(type: string): boolean;
-/**
- * One thing a handler may return: a declared status, and where that status offers several media
- * types, one of them.
+ * One member of a tool's result: the library's member, with the identifier this route's schema for
+ * that body is declared under.
  *
- * **Derived by the sibling server emitter's rules, member for member**, because one handler object
- * serves both surfaces and `test/agreement/` holds the two result types identical. A status offering
- * several media types is several members, because the body differs by media type.
+ * **The rules are the library's (`resultMembersOf`), read rather than restated.** This package, the
+ * sibling server emitter and the contract types each held their own copy, and three copies of rules
+ * that must agree are three that will not.
  */
-export interface ResultMember {
-    readonly response: EmittedResponse;
-    /** The identifier the library declared this status's body under. */
+export interface ResultMember extends LibraryResultMember<EmittedResponse> {
     readonly schemaName: string | undefined;
-    /** The media type served, or `undefined` where the response has no body. */
-    readonly mediaType: string | undefined;
-    /** Whether the handler names the media type, because the status offers more than one. */
-    readonly choosesMediaType: boolean;
 }
-/** What a handler supplies for a member's body, which decides the body's type. */
-export type BodyServing = "none" | "stream" | "binary" | "json" | "text" | "unvalidated";
-export declare function bodyServingOf(member: ResultMember): BodyServing;
 export declare function membersOf(route: EmittedRoute, names: RouteSchemaNames): ResultMember[];
+export { isJsonMediaType };
 /**
- * How the runtime answers a status's body under a media type that is not JSON, where that is not the
- * unvalidated text a handler supplies.
+ * How the runtime answers a body where its media type does not say.
  *
  * - `"text"`: a string body, parsed against its schema and answered as a text block;
- * - `"binary"`: raw bytes, answered as an `image` or `audio` block.
+ * - `"binary"`: raw bytes, answered as an `image` or `audio` block, or as an embedded resource.
  *
  * A body served as JSON needs no entry, because the served media type says so; nor does unvalidated
  * text, which is what a non-JSON body with no entry is.
@@ -54,14 +36,14 @@ export declare function membersOf(route: EmittedRoute, names: RouteSchemaNames):
 export type BodyKind = "text" | "binary";
 /**
  * The body kinds an operation's runtime needs, keyed by the arm's status key as `schemas.gen.ts`
- * writes it (`"200"`, `"4XX"`, `"default"`), and only where one applies.
+ * writes it (`"200"`, `"4XX"`, `"default"`) and the media type as declared, and only where one
+ * applies.
  *
- * **Per status, not per media type, and that loses nothing.** The library decides `binary` and
- * `textual` per response: `binary` only where EVERY media type is non-JSON, `textual` from the body's
- * type. So every non-JSON media type a status offers has the same kind, and JSON is read off the
- * served type itself.
+ * **Read off the library's members, one per status and media type.** A status may offer one model as
+ * XML, the text a handler writes, and as `application/octet-stream`, its bytes; a kind per status
+ * could not say both. A file declared `application/json` is bytes, so it has an entry too.
  */
-export declare function bodyKindsOf(route: EmittedRoute): readonly (readonly [string, BodyKind])[];
+export declare function bodyKindsOf(route: EmittedRoute, names: RouteSchemaNames): readonly (readonly [string, string, BodyKind])[];
 /** Each status whose body under some media type is answered unvalidated, with those media types. */
 export declare function unvalidatedResponsesOf(route: EmittedRoute, names: RouteSchemaNames): readonly {
     readonly status: EmittedResponse["status"];

package/dist/src/bodies.js

@@ -1,93 +1,28 @@
-/**
- * **What each declared response body IS, decided once, for the renderer, the refusals and the runtime.**
- *
- * A handler's result type, the warning about a body nothing validates, the refusal of a body no tool
- * result can carry, and the body kinds the runtime is told about all read the same four facts the
- * library publishes per response: its media types, and whether its body is `binary`, `streamed` or
- * `textual`. Deciding them in one place is what keeps the result type a handler compiles against and
- * the rule the runtime serves it by from disagreeing.
- *
- * Pure: it reads the library's types and nothing else, so the renderer can use it without reaching
- * the compiler.
- */
-/** A media type whose body is a JSON value. The library's own rule, and the runtime's. */
-export function isJsonMediaType(type) {
-    return /^application\/(json|.*\+json)$/.test(type);
-}
-/** A media range such as `image/*`, rather than a type a response can be sent as. */
-export function isMediaRange(mediaType) {
-    return mediaType.endsWith("/*");
-}
-/**
- * A media type MCP has a content block for: `image/*` and `audio/*`, which carry base64 data and
- * the media type itself. A wildcard within one is a type the handler names when it answers.
- */
-export function hasContentBlock(type) {
-    return /^(image|audio)\/[^/]+$/.test(type);
-}
-export function bodyServingOf(member) {
-    const { response, mediaType } = member;
-    if (response.schema === undefined || mediaType === undefined)
-        return "none";
-    if (response.streamed)
-        return "stream";
-    if (response.binary)
-        return "binary";
-    if (isJsonMediaType(mediaType))
-        return "json";
-    /**
-     * **A string body under a non-JSON media type IS the text**, so it is validated and answered as is.
-     * Any other body under one -- a model as `application/xml` -- has no serialisation this emitter can
-     * derive, so the handler supplies the text and it is answered unvalidated.
-     */
-    return response.textual ? "text" : "unvalidated";
-}
+import { isJsonMediaType, resultMembersOf, } from "typespec-http-zod";
 export function membersOf(route, names) {
-    return route.responses.flatMap((response, index) => {
-        const schemaName = names.arms[index]?.schema;
-        if (response.contentTypes.length === 0) {
-            return [{ response, schemaName, mediaType: undefined, choosesMediaType: false }];
-        }
-        /**
-         * The handler names the media type where the status offers several, and where the document names
-         * only a wildcard range, which is not a type a response can be sent as.
-         */
-        const choosesMediaType = response.contentTypes.length > 1 || response.contentTypes.some(isMediaRange);
-        return response.contentTypes.map((mediaType) => ({
-            response,
-            schemaName,
-            mediaType,
-            choosesMediaType,
-        }));
-    });
+    return resultMembersOf(route.responses, (response) => response.schema !== undefined).map((member) => ({ ...member, schemaName: names.arms[member.index]?.schema }));
 }
+export { isJsonMediaType };
 /**
  * The body kinds an operation's runtime needs, keyed by the arm's status key as `schemas.gen.ts`
- * writes it (`"200"`, `"4XX"`, `"default"`), and only where one applies.
+ * writes it (`"200"`, `"4XX"`, `"default"`) and the media type as declared, and only where one
+ * applies.
  *
- * **Per status, not per media type, and that loses nothing.** The library decides `binary` and
- * `textual` per response: `binary` only where EVERY media type is non-JSON, `textual` from the body's
- * type. So every non-JSON media type a status offers has the same kind, and JSON is read off the
- * served type itself.
+ * **Read off the library's members, one per status and media type.** A status may offer one model as
+ * XML, the text a handler writes, and as `application/octet-stream`, its bytes; a kind per status
+ * could not say both. A file declared `application/json` is bytes, so it has an entry too.
  */
-export function bodyKindsOf(route) {
-    return route.responses.flatMap((response) => {
-        if (response.schema === undefined || response.streamed)
-            return [];
-        const offersNonJson = response.contentTypes.some((type) => !isJsonMediaType(type));
-        if (!offersNonJson)
-            return [];
-        if (response.binary)
-            return [[String(response.status), "binary"]];
-        return response.textual ? [[String(response.status), "text"]] : [];
-    });
+export function bodyKindsOf(route, names) {
+    return membersOf(route, names).flatMap((member) => member.mediaType !== undefined && (member.serving === "text" || member.serving === "binary")
+        ? [[String(member.response.status), member.mediaType, member.serving]]
+        : []);
 }
 /** Each status whose body under some media type is answered unvalidated, with those media types. */
 export function unvalidatedResponsesOf(route, names) {
     const members = membersOf(route, names);
     return route.responses.flatMap((response) => {
         const types = members
-            .filter((member) => member.response === response && bodyServingOf(member) === "unvalidated")
+            .filter((member) => member.response === response && member.unvalidated)
             .flatMap((member) => (member.mediaType === undefined ? [] : [member.mediaType]));
         return types.length === 0 ? [] : [{ status: response.status, types }];
     });

package/dist/src/emitter.js

@@ -8,7 +8,7 @@ import { nameTools } from "./names.js";
 import { collisionsFor } from "./coexistence.js";
 import { refusalFor, warningsFor } from "./refusals.js";
 import { renderTools } from "./tools.js";
-import { httpOperationFor, selectTools } from "./select.js";
+import { selectTools } from "./select.js";
 /**
  * Where emitted output imports its runtime from. Declared where the import is rendered, and
  * re-exported here beside the code that writes the file.
@@ -67,17 +67,15 @@ function resolveToolOptions(options, serviceName) {
     };
 }
 /**
- * Where a diagnostic about an operation should point.
+ * Where a diagnostic about an operation should point: the operation the library collected the route
+ * from, by its id.
  *
- * **Keyed on verb and path, never on operation name.** Matching by name never succeeds for an
- * operation declared inside an `interface`, which is most of them -- a defect this estate has
- * already paid for once, where a whole class of refusal silently pointed at nothing.
+ * **Never by name, and never by verb and path.** A name never matches an operation declared inside
+ * an `interface`, whose id carries the interface; verb and path are shared by every member of a
+ * `@sharedRoute`, so each member's diagnostic pointed at one of them.
  */
 function targetFor(emitted, operationId) {
-    const route = emitted.routes.find((candidate) => candidate.operationId === operationId);
-    if (route === undefined)
-        return NoTarget;
-    return httpOperationFor(emitted.service, route)?.operation ?? NoTarget;
+    return emitted.operations.get(operationId)?.operation ?? NoTarget;
 }
 /**
  * Run the library, then add the MCP surface beside what it wrote.
@@ -109,7 +107,7 @@ export async function $onEmit(context) {
         const resolved = resolveToolOptions(options, serviceName);
         if (!resolved.emitTools)
             continue;
-        const selection = selectTools(context.program, emitted.service, emitted.routes, {
+        const selection = selectTools(context.program, emitted.routes, emitted.operations, {
             toolTags: resolved.toolTags,
             excludeTags: resolved.excludeTags,
         });
@@ -153,7 +151,7 @@ export async function $onEmit(context) {
             if (toolName === undefined)
                 continue;
             const names = emitted.schemaNames.get(route.operationId);
-            const operation = httpOperationFor(emitted.service, route);
+            const operation = emitted.operations.get(route.operationId);
             if (names === undefined || operation === undefined)
                 continue;
             /** A refusal removes the operation from the surface, so it is counted, never skipped. */

package/dist/src/lib.d.ts

@@ -84,9 +84,6 @@ type Diagnostics = {
     "non-object-body": {
         readonly default: CallableMessage<["operationId", "types"]>;
     };
-    "binary-tool-output": {
-        readonly default: CallableMessage<["operationId", "types"]>;
-    };
     "streamed-tool-output": {
         readonly default: CallableMessage<["operationId", "types"]>;
     };

package/dist/src/lib.js

@@ -134,22 +134,6 @@ const diagnostics = {
             default: paramMessage `'${"operationId"}' takes a binary or multipart request body (${"types"}), which an MCP tool argument cannot carry: tool arguments are JSON. Exclude it with 'exclude-tags', or declare a JSON-bodied operation for the tool surface.`,
         },
     },
-    /**
-     * A response body an MCP tool result cannot carry, because it is raw bytes with no content block.
-     *
-     * A tool result is content blocks. MCP has an `image` and an `audio` block, each carrying base64
-     * data and its media type, and those are what an `image/*` or `audio/*` body becomes. Any other
-     * binary body -- `application/octet-stream`, a PDF -- could only be an embedded resource, and a
-     * resource needs a URI the document never states. **Refused rather than approximated**: base64 in
-     * a text block would publish an encoding no reader of the document could predict, and would put a
-     * whole download through a model's context window.
-     */
-    "binary-tool-output": {
-        severity: "warning",
-        messages: {
-            default: paramMessage `'${"operationId"}' answers with a binary body (${"types"}) that no MCP content block carries: a tool result is text, JSON, an 'image/*' block or an 'audio/*' block. Exclude it with 'exclude-tags', or declare an image or audio media type, or a JSON body, for the tool surface.`,
-        },
-    },
     /**
      * A streamed response, which a tool result cannot be.
      *
@@ -174,7 +158,7 @@ const diagnostics = {
     "unvalidated-response-media-type": {
         severity: "warning",
         messages: {
-            default: paramMessage `'${"operationId"}' answers ${"status"} as ${"types"}, which this emitter cannot serialise from the schema. The handler returns that body as text and the tool answers it without validating it. Declare a JSON media type, or a string body, to have it checked.`,
+            default: paramMessage `'${"operationId"}' answers ${"status"} as ${"types"}, which this emitter cannot serialise from the schema. The handler returns that body as text, or as bytes under a media type that is not text, and the tool answers it without validating it. Declare a JSON media type, or a string body, to have it checked.`,
         },
     },
     /**

package/dist/src/refusals.d.ts

@@ -13,9 +13,6 @@ export type Refusal = {
 } | {
     readonly kind: "streamed-tool-output";
     readonly types: string;
-} | {
-    readonly kind: "binary-tool-output";
-    readonly types: string;
 };
 /**
  * Why this operation cannot be a tool, or `undefined` where it can.

package/dist/src/refusals.js

@@ -1,5 +1,5 @@
 import { getDiscriminator } from "@typespec/compiler";
-import { hasContentBlock, unvalidatedResponsesOf } from "./bodies.js";
+import { unvalidatedResponsesOf } from "./bodies.js";
 /**
  * What this emitter cannot express as a tool, and what it can express but should warn about.
  *
@@ -74,8 +74,13 @@ export function refusalFor(program, route, operation) {
      * A raw body is bytes or a stream; a multipart body is parts, one of which is usually a file.
      * Neither is a JSON value, and encoding one into a string argument would put an upload through a
      * model's context window under a contract the document never stated.
+     *
+     * **A raw body that is TEXT under no JSON type is not this:** a model declared only as XML is
+     * handed to a server as the text that arrived, and what MCP cannot carry about it is the media
+     * type, which the next check names. Text under a JSON type - a `bytes` body a signature covers -
+     * stays here, as it always has.
      */
-    if (route.rawBodyProperty !== undefined) {
+    if (route.rawBodyProperty !== undefined && (route.rawBodyBinary || types.some(isJson))) {
         return {
             kind: "binary-tool-input",
             types: types.length === 0 ? "a raw body" : types.join(", "),
@@ -114,22 +119,6 @@ export function refusalFor(program, route, operation) {
             types: streamed.flatMap((response) => response.contentTypes).join(", ") || "a stream",
         };
     }
-    /**
-     * **Raw bytes are a tool result only where MCP has a block for them.** An `image/*` or `audio/*`
-     * body is answered as an `image` or `audio` content block, which carries the data and its media
-     * type. Any other binary body -- `application/octet-stream`, a PDF -- could only be an embedded
-     * resource, and a resource needs a URI the document never states. Base64-ing the bytes into a text
-     * block would put a download through a model's context window under an encoding nothing published.
-     * Refused if ANY declared response offers such a type, because a handler may answer with any of
-     * them.
-     */
-    const unanswerable = route.responses
-        .filter((response) => response.binary)
-        .flatMap((response) => response.contentTypes)
-        .filter((type) => !hasContentBlock(type));
-    if (unanswerable.length > 0) {
-        return { kind: "binary-tool-output", types: [...new Set(unanswerable)].join(", ") };
-    }
     return undefined;
 }
 /**

package/dist/src/runtime.d.ts

@@ -6,7 +6,7 @@ import type { ZodError, ZodType } from "zod";
  * **Kept deliberately tiny, and deliberately free of every TypeSpec import.** The main entry point
  * is an emitter: it pulls in `@typespec/compiler` and exists at build time. This module is what an
  * *application* touches, and making it reach the compiler would put a build-time dependency into a
- * server's runtime graph for the sake of a few declarations. `test/packaging.test.ts` asserts the
+ * server's runtime graph for the sake of a few declarations. typespec-http-mcp's packaging suite asserts the
  * separation rather than trusting it.
  *
  * **Always emitted, never substituted.** `runtime-module` used to point the generated file at a
@@ -28,10 +28,10 @@ export type { CallToolResult, McpServer, ServerContext };
  *
  * **Declared here rather than imported from `typespec-http-zod`, deliberately.** Emitted output must
  * never import this emitter or the library it runs -- a consumer installs both as devDependencies,
- * so a runtime import of either is a broken install. `test/packaging.test.ts` asserts that. The
+ * so a runtime import of either is a broken install. typespec-http-mcp's packaging suite asserts that. The
  * emitted `schemas.gen.ts` declares the same shape locally, so it depends on no runtime at all.
  *
- * The cost is a second declaration of one shape, and `test/runtime/parity.test.ts` is what stops the
+ * The cost is a second declaration of one shape, and typespec-http-mcp's runtime parity suite is what stops the
  * two drifting: it grades this `armFor` against the library's own for every arm shape.
  *
  * **The arms arrive in OpenAPI's precedence order, so the FIRST match is the right one** -- an exact
@@ -75,22 +75,28 @@ export interface ToolResponses {
      */
     readonly outputSchema: ZodType | undefined;
     /**
-     * How a body is answered under a media type that is not JSON, keyed by the arm's status key
-     * (`"200"`, `"4XX"`, `"default"`), and present only where one applies.
+     * How a body is answered where its media type does not say, keyed by the arm's status key
+     * (`"200"`, `"4XX"`, `"default"`) and then by the media type as the arm declares it, and present
+     * only where one applies.
      *
      * **Carried because an arm cannot say it.** The arm names the media types and the schema, and
      * neither tells a string body apart from raw bytes or from a model the handler serialised: an
      * `image/png` body and an `application/xml` one both arrive as a schema and a non-JSON type. The
-     * emitter knows, from what the document declares the body to be.
+     * emitter knows, from what the document declares the body to be. **By media type as well as by
+     * status**, because one status may offer one model as XML, the text the handler writes, and as
+     * `application/octet-stream`, its bytes.
      *
      * - `"text"`: a string, parsed against the arm's schema and answered as a `text` block;
-     * - `"binary"`: raw bytes, answered as an `image` or `audio` block.
+     * - `"binary"`: raw bytes, answered as an `image` or `audio` block, or as an embedded resource
+     *   under any other type, a file declared `application/json` included.
      *
-     * A status with no entry answers a non-JSON body as the text the handler supplied, unvalidated. A
-     * body served as JSON needs no entry, because the served media type says so.
+     * A media type with no entry answers a JSON body as JSON, and any other body as the text the
+     * handler supplied, unvalidated.
      */
     readonly bodies?: {
-        readonly [status: string]: "text" | "binary";
+        readonly [status: string]: {
+            readonly [mediaType: string]: "text" | "binary";
+        };
     };
 }
 /**
@@ -109,6 +115,10 @@ export declare class ResponseContractError extends Error {
     readonly operationId: string;
     readonly status: number;
     readonly issues: ZodError["issues"];
+    /**
+     * Fields declared and assigned rather than written as parameter properties, which are not
+     * erasable syntax: a consumer building with `erasableSyntaxOnly` could not compile this file.
+     */
     constructor(operationId: string, status: number, issues: ZodError["issues"]);
 }
 /**
@@ -124,6 +134,25 @@ export declare class UndeclaredStatusError extends Error {
     readonly result: unknown;
     constructor(operationId: string, result: unknown);
 }
+/**
+ * **A stream of bytes, as every platform's `ReadableStream<Uint8Array>` satisfies it.**
+ *
+ * The same structural type `typespec-http-zod` publishes in `requests.gen.ts` and `typespec-hono`
+ * declares in its runtime, so a backend whose result is typed by the framework-free contract can be
+ * returned from a handler as it is. Declared here rather than imported because this file is copied
+ * into a consumer's Worker, where the emitter packages are not installed; the agreement test holds
+ * the declarations identical.
+ */
+export interface ByteStream {
+    getReader(): {
+        read(): Promise<{
+            readonly done: boolean;
+            readonly value?: Uint8Array | undefined;
+        }>;
+        releaseLock(): void;
+        cancel?(reason?: unknown): Promise<void>;
+    };
+}
 /**
  * The MCP result for what a handler returned: `{ status, body, headers }` for a response the
  * document declares.

package/dist/src/runtime.js

@@ -25,12 +25,16 @@ export class ResponseContractError extends Error {
     operationId;
     status;
     issues;
+    /**
+     * Fields declared and assigned rather than written as parameter properties, which are not
+     * erasable syntax: a consumer building with `erasableSyntaxOnly` could not compile this file.
+     */
     constructor(operationId, status, issues) {
         super(`${operationId} answered ${status} with a body its document does not permit`);
+        this.name = "ResponseContractError";
         this.operationId = operationId;
         this.status = status;
         this.issues = issues;
-        this.name = "ResponseContractError";
     }
 }
 /**
@@ -54,9 +58,13 @@ export class UndeclaredStatusError extends Error {
         this.name = "UndeclaredStatusError";
     }
 }
-/** A media type whose body is a JSON value. The rule the library and the server emitter apply. */
+/**
+ * A media type whose body is a JSON value. The rule the library and the server emitter apply, to the
+ * media type's essence: `type/subtype`, lowercased, with no parameters (RFC 9110 section 8.3.1), so
+ * `application/json; charset=utf-8` is JSON.
+ */
 function isJsonMediaType(type) {
-    return /^application\/(json|.*\+json)$/.test(type);
+    return /^application\/(json|.*\+json)$/.test((type.split(";")[0] ?? "").trim().toLowerCase());
 }
 /** RFC 9110 `token`, less `*`, which names a range rather than a type. */
 const MEDIA_TOKEN = "[!#$%&'+.^_`|~0-9A-Za-z-]+";
@@ -102,17 +110,54 @@ function refusedBody(input, message) {
 /**
  * The bytes of a binary body, which a handler may hand over in any of the forms the result type admits.
  *
- * A stream is buffered: a tool result is one message, and the block carries the whole of it.
- * `Response` reads it, because both runtimes this output runs on, Node and workerd, provide it.
+ * A stream is buffered: a tool result is one message, and the block carries the whole of it. It is
+ * read through its reader, which is all `ByteStream` promises, so a stream that is not the platform's
+ * - a contract value from a backend, a test double - is read the same way. A value that is not a
+ * `Uint8Array` is not a byte, and refuses the body rather than being coerced.
  */
 async function bytesOf(body) {
     if (body instanceof Uint8Array)
         return body;
     if (body instanceof ArrayBuffer)
         return new Uint8Array(body);
-    if (body instanceof ReadableStream)
-        return new Uint8Array(await new Response(body).arrayBuffer());
-    return undefined;
+    if (!isByteStream(body))
+        return undefined;
+    const reader = body.getReader();
+    const chunks = [];
+    let length = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            // A read may report no chunk and not be done, which `ByteStream` admits; it carries nothing.
+            if (value === undefined)
+                continue;
+            if (!(value instanceof Uint8Array)) {
+                // Refused part-way, so the producer is told it will not be read further.
+                await reader.cancel?.(value);
+                return undefined;
+            }
+            chunks.push(value);
+            length += value.byteLength;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+function isByteStream(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "getReader" in value &&
+        typeof value.getReader === "function");
 }
 /** Base64, in chunks, so a large body does not exceed the argument limit of one call. */
 function base64Of(bytes) {
@@ -122,6 +167,17 @@ function base64Of(bytes) {
     }
     return btoa(binary);
 }
+/**
+ * **The URI an embedded resource names: this operation's response, which nothing resolves.**
+ *
+ * The specification requires the `uri` and does not require that `resources/read` answer it: a tool
+ * may embed a resource "to provide additional context or data using a suitable URI scheme", and a
+ * custom scheme is allowed where it follows RFC 3986. The bytes are one call's answer, so there is
+ * nothing to list or read back, and this server declares no `resources` capability, which the
+ * specification asks for with a SHOULD. Stainless's MCP servers name such a body
+ * `resource://tool-response`; this names the operation too, so two tools' answers are not one URI.
+ */
+const TOOL_RESPONSE_URI = "resource://tool-response/";
 /**
  * The MCP result for what a handler returned: `{ status, body, headers }` for a response the
  * document declares.
@@ -163,8 +219,36 @@ export async function toolResult(declared, operationId, result) {
      * state something the document does not, so `content` stays `[]`: present, an array, and honest.
      */
     if (arm.schema !== undefined && answer.body !== undefined) {
-        const kind = declared.bodies?.[String(arm.status)];
-        if (mediaType === undefined || isJsonMediaType(mediaType)) {
+        const kinds = declared.bodies?.[String(arm.status)] ?? {};
+        const kind = mediaType === undefined
+            ? undefined
+            : Object.entries(kinds).find(([declaredType]) => admits(declaredType, mediaType))?.[1];
+        if (kind === "binary" && mediaType !== undefined) {
+            /**
+             * **Raw bytes are bytes whatever the media type**, as the library places a file, so a file
+             * declared `application/json` is not parsed and re-serialised. They are answered as the block
+             * MCP defines for their media type, `image` or `audio`, and as an embedded resource under any
+             * other: a blob with the media type served.
+             */
+            const bytes = await bytesOf(answer.body);
+            if (bytes === undefined) {
+                throw new ResponseContractError(operationId, status, refusedBody(answer.body, "a binary body is a Uint8Array, an ArrayBuffer or a stream of Uint8Array chunks"));
+            }
+            const block = /^(image|audio)\//.exec(mediaType.toLowerCase())?.[1];
+            toolAnswer.content = [
+                block === "image" || block === "audio"
+                    ? { type: block, data: base64Of(bytes), mimeType: mediaType }
+                    : {
+                        type: "resource",
+                        resource: {
+                            uri: `${TOOL_RESPONSE_URI}${encodeURIComponent(operationId)}`,
+                            mimeType: mediaType,
+                            blob: base64Of(bytes),
+                        },
+                    },
+            ];
+        }
+        else if (mediaType === undefined || isJsonMediaType(mediaType)) {
             /**
              * **Validated wherever the body is served as JSON**, which is also the only form a tool result
              * can carry structurally. An arm naming no media type is a hand-written arm, and a tool
@@ -198,27 +282,12 @@ export async function toolResult(declared, operationId, result) {
             }
             toolAnswer.content = [{ type: "text", text: String(parsed.data) }];
         }
-        else if (kind === "binary") {
-            /**
-             * **Raw bytes are answered as the block MCP defines for their media type**, carrying the data
-             * as base64 and the media type served. The emitter refuses every other binary media type, so
-             * one reaching here was declared by hand.
-             */
-            const block = /^(image|audio)\//.exec(mediaType)?.[1];
-            if (block !== "image" && block !== "audio") {
-                throw new ResponseContractError(operationId, status, refusedBody(answer.body, `no MCP content block carries a binary body as ${mediaType}`));
-            }
-            const bytes = await bytesOf(answer.body);
-            if (bytes === undefined) {
-                throw new ResponseContractError(operationId, status, refusedBody(answer.body, "a binary body is a Uint8Array, an ArrayBuffer or a ReadableStream"));
-            }
-            toolAnswer.content = [{ type: block, data: base64Of(bytes), mimeType: mediaType }];
-        }
         else {
             /**
-             * **A model under a media type that is not JSON is text the handler serialised**, which the
-             * schema does not describe, so it is answered as it is. `unvalidated-response-media-type`
-             * said so at compile time. Anything but a string is not that text.
+             * **A model under a textual media type that is not JSON is text the handler serialised**,
+             * which the schema does not describe, so it is answered as it is; under a type that is not
+             * text it is bytes, and has a `binary` entry. `unvalidated-response-media-type` said so at
+             * compile time. Anything but a string is not that text.
              */
             if (typeof answer.body !== "string") {
                 throw new ResponseContractError(operationId, status, refusedBody(answer.body, `a body answered as ${mediaType} is the text the handler supplies`));