typespec-http-mcp 0.1.0

package/dist/src/runtime.js

@@ -0,0 +1,280 @@
+/**
+ * The arm that answers for a status, in the document's own precedence order.
+ *
+ * Exact code, then the `NXX` range, then `default`. Sorting the rule out once here is what stops
+ * every application re-deriving it, and getting it silently wrong when a `404` and a `4XX` both apply.
+ */
+export function armFor(arms, status) {
+    return (arms.find((arm) => arm.status === status) ??
+        arms.find((arm) => arm.status === `${Math.floor(status / 100)}XX`) ??
+        arms.find((arm) => arm.status === "default"));
+}
+/**
+ * A response body that does not match the schema the document publishes for its status.
+ *
+ * **Thrown, so the application decides what a contract failure answers with**, the same class and
+ * the same fields as the sibling server emitter's. The MCP server turns a thrown error into a
+ * tool-execution error; an application that wants something else catches it around `registerTools`'
+ * handlers.
+ *
+ * `issues` are Zod's, so they carry paths and codes. They also carry the offending VALUES; an
+ * application that logs them should decide whether its results may contain anything it would not
+ * log.
+ */
+export class ResponseContractError extends Error {
+    operationId;
+    status;
+    issues;
+    constructor(operationId, status, issues) {
+        super(`${operationId} answered ${status} with a body its document does not permit`);
+        this.operationId = operationId;
+        this.status = status;
+        this.issues = issues;
+        this.name = "ResponseContractError";
+    }
+}
+/**
+ * A handler answered with a status its operation does not declare.
+ *
+ * **Unreachable from a typed handler.** The generated `Tools` interface types every result as the
+ * union of the declared statuses, so a literal outside it does not compile. This is what a CAST
+ * produces, or a result that crossed a boundary the type system cannot see into. Thrown rather than
+ * answered, because answering would publish a status the contract does not state.
+ */
+export class UndeclaredStatusError extends Error {
+    operationId;
+    result;
+    constructor(operationId, result) {
+        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. */
+function isJsonMediaType(type) {
+    return /^application\/(json|.*\+json)$/.test(type);
+}
+/** RFC 9110 `token`, less `*`, which names a range rather than a type. */
+const MEDIA_TOKEN = "[!#$%&'+.^_`|~0-9A-Za-z-]+";
+const SERVED_MEDIA_TYPE = new RegExp(`^(${MEDIA_TOKEN})/${MEDIA_TOKEN}\\s*(;.*)?$`);
+/**
+ * Whether an offered media type, which may be a range such as `image/*`, admits a served one.
+ *
+ * The sibling server emitter's `mediaTypeWithin`, rule for rule: a range admits a concrete type inside
+ * it, never its own spelling or a type with no subtype; type names compare case-insensitively
+ * (RFC 9110 section 8.3.1), and parameters such as `charset` are allowed.
+ */
+function admits(offered, served) {
+    if (!offered.endsWith("/*"))
+        return offered === served;
+    const type = SERVED_MEDIA_TYPE.exec(served)?.[1];
+    if (type === undefined)
+        return false;
+    if (offered === "*/*")
+        return true;
+    return type.toLowerCase() === offered.slice(0, -2).toLowerCase();
+}
+/**
+ * The media type a result is served as, or `undefined` where the arm names none.
+ *
+ * Where the arm offers several, or only a wildcard range, the handler names the one it answers with,
+ * and a type the arm does not offer is as undeclared as a status it does not. A range admits every
+ * type inside it: `image/*` is what lets a handler answer `image/png`.
+ */
+function mediaTypeOf(arm, contentType, operationId, result) {
+    const offered = arm.contentTypes ?? [];
+    const choosing = offered.length > 1 || offered.some((type) => type.endsWith("/*"));
+    if (!choosing)
+        return offered[0];
+    if (typeof contentType === "string" && offered.some((type) => admits(type, contentType))) {
+        return contentType;
+    }
+    throw new UndeclaredStatusError(operationId, result);
+}
+/** A body that is not what its arm says it is, as one issue in Zod's own shape. */
+function refusedBody(input, message) {
+    return [{ code: "custom", path: [], message, input }];
+}
+/**
+ * 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.
+ */
+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;
+}
+/** Base64, in chunks, so a large body does not exceed the argument limit of one call. */
+function base64Of(bytes) {
+    let binary = "";
+    for (let offset = 0; offset < bytes.length; offset += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
+    }
+    return btoa(binary);
+}
+/**
+ * The MCP result for what a handler returned: `{ status, body, headers }` for a response the
+ * document declares.
+ *
+ * **In the runtime rather than in `deps`, on the same test the sibling emitter applies**: every rule
+ * below is published -- by the document (the arms, their bodies, their headers) or by the MCP
+ * specification (the result shape, its content blocks, `isError`, the text mirror). An application
+ * forced to supply this would be re-implementing two standards, and getting either wrong differently
+ * from everybody else.
+ *
+ * **What is answered is the PARSED body, not the one the handler returned**, as on the HTTP surface:
+ * a schema that strips undeclared keys strips them here too, so a field the document does not publish
+ * does not reach a model.
+ *
+ * Asynchronous because a binary body may be a stream, which is read to its end before it is answered.
+ */
+export async function toolResult(declared, operationId, result) {
+    const answer = typeof result === "object" && result !== null ? result : {};
+    const { status } = answer;
+    const arm = typeof status === "number" ? armFor(declared.arms, status) : undefined;
+    if (arm === undefined || typeof status !== "number") {
+        throw new UndeclaredStatusError(operationId, result);
+    }
+    const mediaType = mediaTypeOf(arm, answer.contentType, operationId, result);
+    /**
+     * **`isError` is decided from the STATUS, not from whether the arm is an error model.**
+     *
+     * MCP's `isError` marks a tool-execution error the model can self-correct from, which is exactly
+     * what a declared 4xx or 5xx is: the service's own published failure, with a body the model can
+     * read. It is decided from the status because `armFor` may resolve to a range or `default`, whose
+     * numeric status only the result carries.
+     */
+    const isError = status >= 400;
+    const toolAnswer = { content: [] };
+    /** Whether the body was answered as JSON text, which `structuredContent` then mirrors. */
+    let servedAsJson = false;
+    /**
+     * A bodyless arm carries nothing a model can read, and inventing a confirmation sentence would
+     * 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)) {
+            /**
+             * **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
+             * result's text is JSON, so it is validated too.
+             */
+            const parsed = arm.schema.safeParse(answer.body);
+            if (!parsed.success) {
+                throw new ResponseContractError(operationId, status, parsed.error.issues);
+            }
+            servedAsJson = true;
+            // The text mirror is kept even beside `structuredContent`: MCP recommends it for clients
+            // that read only `content`.
+            toolAnswer.content = [{ type: "text", text: JSON.stringify(parsed.data) }];
+            /**
+             * **Where this arm's schema IS the published `outputSchema`.** MCP obliges a tool that
+             * declares an `outputSchema` to return conforming `structuredContent`, and a failure's body
+             * does not conform to the success schema the tool published.
+             */
+            if (declared.outputSchema !== undefined && arm.schema === declared.outputSchema) {
+                toolAnswer.structuredContent = parsed.data;
+            }
+        }
+        else if (kind === "text") {
+            /**
+             * **A string body under a media type that is not JSON IS the text**, so it is checked against
+             * its schema exactly as the sibling server emitter checks it, and the parsed string answered.
+             */
+            const parsed = arm.schema.safeParse(answer.body);
+            if (!parsed.success) {
+                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.
+             */
+            if (typeof answer.body !== "string") {
+                throw new ResponseContractError(operationId, status, refusedBody(answer.body, `a body answered as ${mediaType} is the text the handler supplies`));
+            }
+            toolAnswer.content = [{ type: "text", text: answer.body }];
+        }
+    }
+    /**
+     * **A success the published `outputSchema` does not describe fails here, by name.**
+     *
+     * The SDK refuses a result that is not an error and carries no `structuredContent` once a tool
+     * declares an `outputSchema`. The emitter publishes one only where every 2xx and 3xx response the
+     * document declares shares its body, but `default` covers the statuses nobody listed, 2xx and 3xx
+     * among them. Such a success is answered only if its body also meets the published schema;
+     * otherwise it is the contract failure it is, rather than the SDK's "no structured content".
+     *
+     * **The body the HANDLER returned is checked, not the one its own arm parsed.** An object schema
+     * strips the keys it does not declare, so a `Problem`-parsed body has already lost every key a
+     * `Widget` needs: checking that would refuse a body that meets both. The text mirror is then the
+     * published schema's parse, because that is what `structuredContent` carries.
+     */
+    if (!isError &&
+        declared.outputSchema !== undefined &&
+        toolAnswer.structuredContent === undefined) {
+        const conforming = declared.outputSchema.safeParse(answer.body);
+        if (!conforming.success) {
+            throw new ResponseContractError(operationId, status, conforming.error.issues);
+        }
+        toolAnswer.structuredContent = conforming.data;
+        if (servedAsJson) {
+            toolAnswer.content = [{ type: "text", text: JSON.stringify(conforming.data) }];
+        }
+    }
+    if (isError)
+        toolAnswer.isError = true;
+    /**
+     * **Response headers go to `_meta`, keyed by the WIRE name, never to `structuredContent`.**
+     *
+     * Putting them in `structuredContent` breaks the declared `outputSchema`, which MCP forbids;
+     * dropping them is a loss the consumer cannot see. `_meta` is MCP's slot for implementation data
+     * outside the tool contract, and the key is namespaced so it collides with nothing. Only the
+     * headers the arm declares are carried, and an optional one the handler left out is omitted. A
+     * model cannot read `_meta`, so a value that matters to a caller belongs in the response body --
+     * which `headers-only-success` warns about.
+     */
+    const supplied = typeof answer.headers === "object" && answer.headers !== null
+        ? answer.headers
+        : {};
+    const carried = {};
+    for (const header of arm.headers ?? []) {
+        const value = supplied[header.name];
+        if (value !== undefined)
+            carried[header.name] = value;
+    }
+    if (Object.keys(carried).length > 0) {
+        toolAnswer._meta = { "typespec-http-mcp/response-headers": carried };
+    }
+    return toolAnswer;
+}

package/dist/src/select.d.ts

@@ -0,0 +1,49 @@
+import { type Program } from "@typespec/compiler";
+import type { HttpOperation, HttpService } from "@typespec/http";
+import type { EmittedRoute } from "typespec-http-zod";
+/**
+ * Which operations become tools.
+ *
+ * **`getAllTags`, never `getTags`, and the difference is a silent defect.** `getTags` returns only an
+ * operation's OWN tags, so an operation declared inside a `@tag`-carrying `interface` reports none.
+ * Measured on a fixture tagging all three levels:
+ *
+ * ```
+ * GET    /things       getTags: ["agent"]  getAllTags: ["service-level","agent"]
+ * DELETE /things/{id}  getTags: []         getAllTags: ["service-level"]
+ * POST   /bulk         getTags: []         getAllTags: ["service-level","agent","admin"]
+ * ```
+ *
+ * where `/bulk` is a member of a tagged interface. Tagging a whole interface is the obvious way to
+ * mark a group of operations as tools, so `getTags` would break the primary use case invisibly --
+ * the same failure shape this estate already recorded for matching operations by NAME, which never
+ * succeeded for an operation inside an `interface`.
+ *
+ * **A `@tag` on the service namespace propagates to every operation.** That is correct and
+ * documented: it is how a whole service is marked, and it is also why a tag chosen for grouping and
+ * a tag chosen for selection should not be the same word.
+ *
+ * Selection is by tag because `@typespec/openapi3` PUBLISHES tags. A reader of the document can see
+ * exactly which operations are tools, which is what keeps this out of decorator territory.
+ */
+export interface Selection {
+    /** Operation ids the tag configuration matched. */
+    readonly selected: readonly string[];
+    /** Every tag any operation in the service carries, for a diagnostic that has to be actionable. */
+    readonly available: readonly string[];
+}
+export interface SelectionOptions {
+    readonly toolTags: readonly string[] | undefined;
+    readonly excludeTags: readonly string[];
+}
+/** The `HttpOperation` behind each emitted route, keyed by verb and path. */
+export declare function operationsById(service: HttpService): ReadonlyMap<string, HttpOperation>;
+/**
+ * Look an operation up by verb and path, never by name.
+ *
+ * **Matching on operation NAME silently fails for every operation declared inside an `interface`**,
+ * which is most of them in a real spec -- a defect this estate has already paid for once. The verb
+ * and the path are what both the route and the document agree on.
+ */
+export declare function httpOperationFor(service: HttpService, route: EmittedRoute): HttpOperation | undefined;
+export declare function selectTools(program: Program, service: HttpService, routes: readonly EmittedRoute[], options: SelectionOptions): Selection;

package/dist/src/select.js

@@ -0,0 +1,59 @@
+import { getAllTags } from "@typespec/compiler";
+/**
+ * The lookup key both sides agree on.
+ *
+ * **Lower-cased, and that is not cosmetic.** `EmittedRoute.verb` is UPPERCASE (`"GET"`) while
+ * `HttpOperation.verb` is lowercase (`"get"`) -- measured, on this package's own fixture. A
+ * case-sensitive key misses every operation, and the failure is silent in the worst possible way:
+ * the emitter selects nothing, reports `no-tools-selected`, and the message blames the tag
+ * configuration. It was caught here only because a fixture asserted that an unnarrowed selection
+ * selects SOMETHING.
+ */
+function keyOf(verb, path) {
+    return `${verb.toLowerCase()} ${path}`;
+}
+/** The `HttpOperation` behind each emitted route, keyed by verb and path. */
+export function operationsById(service) {
+    const byVerbAndPath = new Map();
+    for (const operation of service.operations) {
+        byVerbAndPath.set(keyOf(operation.verb, operation.path), operation);
+    }
+    return byVerbAndPath;
+}
+/**
+ * Look an operation up by verb and path, never by name.
+ *
+ * **Matching on operation NAME silently fails for every operation declared inside an `interface`**,
+ * which is most of them in a real spec -- a defect this estate has already paid for once. The verb
+ * and the path are what both the route and the document agree on.
+ */
+export function httpOperationFor(service, route) {
+    return operationsById(service).get(keyOf(route.verb, route.path));
+}
+export function selectTools(program, service, routes, options) {
+    const available = new Set();
+    const selected = [];
+    for (const route of routes) {
+        const operation = httpOperationFor(service, route);
+        if (operation === undefined)
+            continue;
+        const tags = getAllTags(program, operation.operation) ?? [];
+        for (const tag of tags)
+            available.add(tag);
+        if (options.excludeTags.some((tag) => tags.includes(tag)))
+            continue;
+        /**
+         * **Unset means every operation, and the alternative was rejected deliberately.** A magic tag
+         * name (`"tool"`, `"mcp"`) is a rule an author cannot see in the document and cannot discover,
+         * and it makes a correctly configured emitter produce nothing at all.
+         *
+         * **Union, not intersection.** OpenAPI tags are a flat set with no AND semantics, so "carries
+         * any of these" is the only reading the published document supports.
+         */
+        if (options.toolTags !== undefined && !options.toolTags.some((tag) => tags.includes(tag))) {
+            continue;
+        }
+        selected.push(route.operationId);
+    }
+    return { selected, available: [...available].toSorted() };
+}

package/dist/src/statuses.d.ts

@@ -0,0 +1,35 @@
+/**
+ * **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

@@ -0,0 +1,29 @@
+/**
+ * **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];

package/dist/src/tools.d.ts

@@ -0,0 +1,37 @@
+import { type EmittedRoute, type RouteSchemaNames } from "typespec-http-zod";
+import type { SecurityRequirement } from "./runtime.js";
+/**
+ * Where emitted output imports its runtime from: the copy this package writes beside it.
+ *
+ * **Always this module.** `runtime-module` used to replace it, and that made an application own a
+ * copy of generated logic -- see the `runtime-module-removed` diagnostic.
+ *
+ * **Deliberately NOT `./runtime.gen.js`, which is what the sibling server emitter uses.** Both
+ * emitters run `typespec-http-zod`, and a consumer who wants both surfaces may point them at one
+ * output directory. `emitFile` has no duplicate-path detection -- measured, `@typespec/compiler`
+ * 1.15.0 `dist/src/core/emitter-utils.js:19-27` -- so two emitters writing one path is a silent
+ * last-writer-wins whose winner is decided by the ORDER of `emit:` in `tspconfig.yaml`. Measured
+ * end to end: with divergent `seal-object-schemas`, one order produced 19 unsealed objects and the
+ * other 11 unsealed plus 8 sealed, exit 0 and no diagnostic either time.
+ *
+ * Giving this package its own runtime filename means the only file the two can contest is
+ * `schemas.gen.ts`, which is byte-identical under identical options.
+ */
+export declare const DEFAULT_RUNTIME_MODULE = "./mcp-runtime.gen.js";
+export interface ToolEntry {
+    readonly route: EmittedRoute;
+    readonly names: RouteSchemaNames;
+    readonly toolName: string;
+    readonly requirements: readonly SecurityRequirement[];
+    readonly description: string | undefined;
+    readonly title: string | undefined;
+}
+export interface RenderedTools {
+    readonly text: string;
+    /** Operation ids that became tools. */
+    readonly emitted: readonly string[];
+}
+export declare function renderTools(entries: readonly ToolEntry[], declaredOperationIds: readonly string[], options: {
+    readonly sealed: boolean;
+    readonly hint: string | undefined;
+}): RenderedTools;