typespec-http-mcp 0.1.0 → 0.3.0

package/src/runtime.ts

@@ -7,7 +7,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
@@ -31,10 +31,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
@@ -85,21 +85,27 @@ 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 bodies?: {
+		readonly [status: string]: { readonly [mediaType: string]: "text" | "binary" };
+	};
 }
 
 /**
@@ -115,13 +121,20 @@ export interface ToolResponses {
  * log.
  */
 export class ResponseContractError extends Error {
-	constructor(
-		readonly operationId: string,
-		readonly status: number,
-		readonly issues: ZodError["issues"],
-	) {
+	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"]) {
 		super(`${operationId} answered ${status} with a body its document does not permit`);
 		this.name = "ResponseContractError";
+		this.operationId = operationId;
+		this.status = status;
+		this.issues = issues;
 	}
 }
 
@@ -134,22 +147,28 @@ export class ResponseContractError extends Error {
  * answered, because answering would publish a status the contract does not state.
  */
 export class UndeclaredStatusError extends Error {
-	constructor(
-		readonly operationId: string,
-		readonly result: unknown,
-	) {
+	readonly operationId: string;
+	readonly result: unknown;
+
+	constructor(operationId: string, result: unknown) {
 		const status =
 			typeof result === "object" && result !== null && "status" in result
 				? String(result.status)
 				: "no status";
 		super(`${operationId} answered ${status}, which its document does not declare`);
+		this.operationId = operationId;
+		this.result = result;
 		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: string): boolean {
-	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. */
@@ -198,17 +217,71 @@ function refusedBody(input: unknown, message: string): ZodError["issues"] {
 	return [{ code: "custom", path: [], message, input }];
 }
 
+/**
+ * **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 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: unknown): Promise<Uint8Array | undefined> {
 	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: Uint8Array[] = [];
+	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: unknown): value is ByteStream {
+	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. */
@@ -220,10 +293,26 @@ function base64Of(bytes: Uint8Array): string {
 	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/";
+
 /** One block of a tool result, as the MCP specification defines the ones this runtime answers with. */
 type ContentBlock =
 	| { readonly type: "text"; readonly text: string }
-	| { readonly type: "image" | "audio"; readonly data: string; readonly mimeType: string };
+	| { readonly type: "image" | "audio"; readonly data: string; readonly mimeType: string }
+	| {
+			readonly type: "resource";
+			readonly resource: { readonly uri: string; readonly mimeType: string; readonly blob: string };
+	  };
 
 /**
  * The MCP result for what a handler returned: `{ status, body, headers }` for a response the
@@ -284,8 +373,43 @@ export async function toolResult(
 	 * 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
@@ -317,37 +441,12 @@ export async function toolResult(
 				throw new ResponseContractError(operationId, status, parsed.error.issues);
 			}
 			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(

package/dist/src/statuses.d.ts

@@ -1,35 +0,0 @@
-/**
- * **The status codes a handler's result may name, as values, held equal to Hono's own types.**
- *
- * One handler object serves both the HTTP surface `typespec-hono` generates and this tool surface,
- * and `typespec-hono` types a result's `status` with Hono's status-code unions. This package's output
- * must not import Hono, so it writes the same sets as literal unions, and a type the two emitters
- * disagree on is a handler that compiles against one surface and not the other.
- * `test/runtime/status-codes.test.ts` reads Hono's declaration file and compares every set here with
- * it, and the agreement arm compiles the two emitted signatures against each other.
- */
-/** Hono's `InfoStatusCode` to `ServerErrorStatusCode`, by the digit a range key starts with. */
-export declare const STATUS_GROUPS: {
-    readonly 1: {
-        readonly type: "InfoStatusCode";
-        readonly codes: readonly [100, 101, 102, 103];
-    };
-    readonly 2: {
-        readonly type: "SuccessStatusCode";
-        readonly codes: readonly [200, 201, 202, 203, 204, 205, 206, 207, 208, 226];
-    };
-    readonly 3: {
-        readonly type: "RedirectStatusCode";
-        readonly codes: readonly [300, 301, 302, 303, 304, 305, 306, 307, 308];
-    };
-    readonly 4: {
-        readonly type: "ClientErrorStatusCode";
-        readonly codes: readonly [400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 421, 422, 423, 424, 425, 426, 428, 429, 431, 451];
-    };
-    readonly 5: {
-        readonly type: "ServerErrorStatusCode";
-        readonly codes: readonly [500, 501, 502, 503, 504, 505, 506, 507, 508, 510, 511];
-    };
-};
-/** Hono's `ContentlessStatusCode`: a status that cannot carry a body. */
-export declare const CONTENTLESS_STATUS_CODES: readonly [101, 204, 205, 304];

package/dist/src/statuses.js

@@ -1,29 +0,0 @@
-/**
- * **The status codes a handler's result may name, as values, held equal to Hono's own types.**
- *
- * One handler object serves both the HTTP surface `typespec-hono` generates and this tool surface,
- * and `typespec-hono` types a result's `status` with Hono's status-code unions. This package's output
- * must not import Hono, so it writes the same sets as literal unions, and a type the two emitters
- * disagree on is a handler that compiles against one surface and not the other.
- * `test/runtime/status-codes.test.ts` reads Hono's declaration file and compares every set here with
- * it, and the agreement arm compiles the two emitted signatures against each other.
- */
-/** Hono's `InfoStatusCode` to `ServerErrorStatusCode`, by the digit a range key starts with. */
-export const STATUS_GROUPS = {
-    1: { type: "InfoStatusCode", codes: [100, 101, 102, 103] },
-    2: { type: "SuccessStatusCode", codes: [200, 201, 202, 203, 204, 205, 206, 207, 208, 226] },
-    3: { type: "RedirectStatusCode", codes: [300, 301, 302, 303, 304, 305, 306, 307, 308] },
-    4: {
-        type: "ClientErrorStatusCode",
-        codes: [
-            400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418,
-            421, 422, 423, 424, 425, 426, 428, 429, 431, 451,
-        ],
-    },
-    5: {
-        type: "ServerErrorStatusCode",
-        codes: [500, 501, 502, 503, 504, 505, 506, 507, 508, 510, 511],
-    },
-};
-/** Hono's `ContentlessStatusCode`: a status that cannot carry a body. */
-export const CONTENTLESS_STATUS_CODES = [101, 204, 205, 304];