typespec-http-mcp 0.1.0 → 0.2.0

package/dist/src/select.d.ts

@@ -1,5 +1,5 @@
 import { type Program } from "@typespec/compiler";
-import type { HttpOperation, HttpService } from "@typespec/http";
+import type { HttpOperation } from "@typespec/http";
 import type { EmittedRoute } from "typespec-http-zod";
 /**
  * Which operations become tools.
@@ -36,14 +36,9 @@ 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.
+ * **Each route's operation is read by its operation id**, from the library's `operations`. It was
+ * looked up by verb and path, which `@sharedRoute` does not make unique, so every member of a shared
+ * route was selected by one member's tags.
  */
-export declare function httpOperationFor(service: HttpService, route: EmittedRoute): HttpOperation | undefined;
-export declare function selectTools(program: Program, service: HttpService, routes: readonly EmittedRoute[], options: SelectionOptions): Selection;
+export declare function selectTools(program: Program, routes: readonly Pick<EmittedRoute, "operationId">[], operations: ReadonlyMap<string, HttpOperation>, options: SelectionOptions): Selection;

package/dist/src/select.js

@@ -1,40 +1,14 @@
 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.
+ * **Each route's operation is read by its operation id**, from the library's `operations`. It was
+ * looked up by verb and path, which `@sharedRoute` does not make unique, so every member of a shared
+ * route was selected by one member's tags.
  */
-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) {
+export function selectTools(program, routes, operations, options) {
     const available = new Set();
     const selected = [];
     for (const route of routes) {
-        const operation = httpOperationFor(service, route);
+        const operation = operations.get(route.operationId);
         if (operation === undefined)
             continue;
         const tags = getAllTags(program, operation.operation) ?? [];

package/dist/src/tools.js

@@ -1,7 +1,6 @@
-import { jsDocComment, objectKey, } from "typespec-http-zod";
+import { jsDocComment, mediaTypeTypeOf, objectKey, statusCodesOf, } from "typespec-http-zod";
 import { annotationsFor } from "./annotations.js";
-import { bodyKindsOf, bodyServingOf, isJsonMediaType, isMediaRange, membersOf } from "./bodies.js";
-import { CONTENTLESS_STATUS_CODES, STATUS_GROUPS } from "./statuses.js";
+import { bodyKindsOf, isJsonMediaType, membersOf } from "./bodies.js";
 /**
  * **Rendering lives here, with everything else that produces text.**
  *
@@ -39,10 +38,11 @@ const FIELDS_HELPER = `/**
  * **Zod 4 infers \`Record<string, never>\` for \`z.object({})\`.** That is a fair reading on its own -
  * no string key may exist - and lethal in an intersection: \`{ id: string } & Record<string, never>\`
  * makes \`id\` into \`string & never\`, so the input type is uninhabitable and the call site below
- * cannot compile. An empty model contributes nothing to an operation's input, and \`unknown\` is the
- * identity of \`&\`, so that is what it becomes.
+ * cannot compile. An empty model contributes nothing to an operation's input, so it becomes \`{}\`,
+ * the identity of \`&\` over the object types an input is made of - not \`unknown\`, which an input
+ * made of nothing else would then BE, and which the contract types' \`{}\` does not accept.
  */
-type Fields<T> = string extends keyof T ? ([T[string]] extends [never] ? unknown : T) : T;
+type Fields<T> = string extends keyof T ? ([T[string]] extends [never] ? {} : T) : T;
 
 `;
 const PRODUCED_HELPER = `/**
@@ -51,8 +51,11 @@ const PRODUCED_HELPER = `/**
  * An index signature and \`readonly\` are true of an inferred type without being obligations on a
  * producer, so both are dropped here - only where the shape has declared keys beside it, because an
  * index signature also arrives as a property's own declared type, where stripping it would destroy
- * the property. An explicit \`| undefined\` on an optional property is deliberately NOT removed:
- * dropping an index signature makes MORE values assignable, and removing \`| undefined\` makes fewer.
+ * the property.
+ *
+ * It is applied to the schema's INPUT, \`z.input\`, because that is what a result is checked against:
+ * a property with a default may be left out, and an optional property is \`?: T\`, because
+ * \`.exactOptional()\` refuses an explicit \`undefined\`. Both are what the contract types state.
  */
 type ProducedKeyOf<T> = keyof {
 	[K in keyof T as string extends K
@@ -110,7 +113,14 @@ export const DEFAULT_RUNTIME_MODULE = "./mcp-runtime.gen.js";
  */
 function intersectedValidators(entry) {
     const { names, route } = entry;
-    const groups = [names.path, names.query, names.header, names.body];
+    /**
+     * **A cookie is merged like a header, and for the same reason.** A tool call carries neither, so
+     * neither is transport the tool can set - both are inputs the operation needs, and a tool's
+     * arguments are one object merged from every location the document declares. The alternative was
+     * to refuse the operation, which would remove a working tool over a distinction the MCP surface
+     * does not have.
+     */
+    const groups = [names.path, names.query, names.header, names.cookie, names.body];
     return groups.filter((name) => name !== undefined && (route.bodyProperty === undefined || name !== names.body));
 }
 /**
@@ -130,12 +140,30 @@ function shapedValidators(entry) {
 function inputTypeOf(entry) {
     const parts = intersectedValidators(entry).map((name) => `Fields<z.infer<typeof ${name}>>`);
     if (entry.route.bodyProperty !== undefined && entry.names.body !== undefined) {
+        // `?: T`, as the sibling server types it: an absent body is an absent key.
         const optionalMark = entry.route.optionalBody ? "?" : "";
-        const optionalValue = entry.route.optionalBody ? " | undefined" : "";
-        parts.push(`{ ${objectKey(entry.route.bodyProperty)}${optionalMark}: z.infer<typeof ${entry.names.body}>${optionalValue} }`);
+        parts.push(`{ ${objectKey(entry.route.bodyProperty)}${optionalMark}: z.infer<typeof ${entry.names.body}> }`);
     }
+    const selected = selectedAcceptOf(entry);
+    if (selected !== undefined)
+        parts.push(`{ ${selected} }`);
     return parts.length === 0 ? EMPTY_INPUT : parts.join(" & ");
 }
+/**
+ * **The `accept` literal a tool supplies itself**, on a route several operations share, as
+ * `key: "literal"`.
+ *
+ * The server negotiates which operation answers, so its handler receives the one literal that reached
+ * it, and the header validator leaves `accept` out. A tool IS one of those operations, so the literal
+ * is known exactly here too: the handler receives it, and the caller is never asked for a value with
+ * one answer. It was missing, so a handler typed for the server could not be registered as a tool.
+ */
+function selectedAcceptOf(entry) {
+    const selected = entry.names.selectedAccept;
+    return selected === undefined
+        ? undefined
+        : `${objectKey(selected.name)}: ${JSON.stringify(selected.value)}`;
+}
 /**
  * The tool's ARGUMENT schema: every group the document declares, merged into one object.
  *
@@ -155,64 +183,27 @@ function inputSchemaOf(entry, sealed) {
     const constructor = sealed ? "z.strictObject" : "z.looseObject";
     const spreads = shapedValidators(entry).map((name) => `...${name}.shape`);
     if (entry.route.bodyProperty !== undefined && entry.names.body !== undefined) {
-        spreads.push(`${objectKey(entry.route.bodyProperty)}: ${entry.names.body}`);
+        /**
+         * **Optional where the document lets the body be absent.** It was required here while the
+         * handler's input said \`body?:\`, so a tool call omitting a body the document makes optional
+         * was refused before it reached the handler.
+         */
+        const optional = entry.route.optionalBody ? ".exactOptional()" : "";
+        spreads.push(`${objectKey(entry.route.bodyProperty)}: ${entry.names.body}${optional}`);
     }
     if (spreads.length === 0)
         return "z.strictObject({})";
     return `${constructor}({ ${spreads.join(", ")} })`;
 }
-/** The codes of the status group a range key names. */
-function groupCodesOf(status) {
-    return STATUS_GROUPS[Number(status.charAt(0))].codes;
-}
 /**
- * The type of the `contentType` a handler names for a member: the sibling emitter's rule.
+ * The status a result member is typed with: the codes its response answers with, written out.
  *
- * **A range is typed as the types inside it**: `image/*` is `` `image/${string}` ``, so `text/html`
- * under it does not compile, and TypeScript still narrows a literal member away from it. Only the
- * full range is `string`.
- */
-function contentTypeTypeOf(mediaType) {
-    if (!isMediaRange(mediaType))
-        return JSON.stringify(mediaType);
-    if (mediaType === "*/*")
-        return "string";
-    return `\`${mediaType.slice(0, -1)}\${string}\``;
-}
-/**
- * A member's status as a TypeScript type: disjoint from every other member's, by construction.
- *
- * **Written as a union of literals, never as Hono's type names.** This package's output imports no
- * Hono, so where the sibling emitter writes `Exclude<ClientErrorStatusCode, 404 | ContentlessStatusCode>`
- * this writes the codes that expression resolves to, from the same sets (`statuses.ts`, held equal to
- * Hono's declaration file by test):
- *
- * - an exact code is itself;
- * - a range is its group, less every code the operation declares exactly, and less the statuses that
- *   cannot carry a body where the range has one;
- * - `default` is every official status from 2xx to 5xx, less the exact codes, less every code a
- *   declared range covers, and less the contentless statuses where it has a body.
- *
- * **Disjoint is the property that makes a wrong body a compile error**: were `default` allowed to
- * overlap a declared status, a 404 carrying the default arm's body would type-check through it.
+ * **Written out, never as Hono's group types**, because this file imports nothing from Hono. The
+ * codes are the library's `statusCodesOf`, the same rule the server emitter and the contract types
+ * read, so a tool's result and a handler's result agree member by member.
  */
 function statusTypeOf(response, route) {
-    const { status } = response;
-    if (typeof status === "number")
-        return String(status);
-    const exact = new Set(route.responses.flatMap((candidate) => typeof candidate.status === "number" ? [candidate.status] : []));
-    const contentless = new Set(response.schema === undefined ? [] : CONTENTLESS_STATUS_CODES);
-    const candidates = status === "default"
-        ? [2, 3, 4, 5].flatMap((digit) => STATUS_GROUPS[digit].codes)
-        : groupCodesOf(status);
-    const ranged = new Set(status === "default"
-        ? route.responses.flatMap((candidate) => typeof candidate.status === "string" && candidate.status !== "default"
-            ? groupCodesOf(candidate.status)
-            : [])
-        : []);
-    const codes = candidates
-        .filter((code) => !exact.has(code) && !ranged.has(code) && !contentless.has(code))
-        .toSorted((a, b) => a - b);
+    const codes = statusCodesOf(response, route.responses, (candidate) => candidate.schema !== undefined);
     return codes.length === 0 ? "never" : codes.join(" | ");
 }
 /**
@@ -226,23 +217,28 @@ function resultTypeOf(entry) {
         const { response } = member;
         const fields = [`readonly status: ${statusTypeOf(response, entry.route)}`];
         if (member.choosesMediaType && member.mediaType !== undefined) {
-            fields.push(`readonly contentType: ${contentTypeTypeOf(member.mediaType)}`);
+            fields.push(`readonly contentType: ${mediaTypeTypeOf(member.mediaType)}`);
         }
-        switch (bodyServingOf(member)) {
+        switch (member.serving) {
             case "none":
                 fields.push("readonly body?: undefined");
                 break;
             case "stream":
-                fields.push("readonly body: ReadableStream");
+                fields.push("readonly body: ByteStream");
                 break;
             case "binary":
-                fields.push("readonly body: ReadableStream | Uint8Array<ArrayBuffer> | ArrayBuffer");
+                /**
+                 * **`ByteStream`, not `ReadableStream`, so a backend's contract value fits**, as the sibling
+                 * server types it. The contract types state a binary body structurally, because they cannot
+                 * name the platform stream; a platform stream still satisfies it.
+                 */
+                fields.push("readonly body: ByteStream | Uint8Array<ArrayBuffer> | ArrayBuffer");
                 break;
             case "unvalidated":
                 fields.push("readonly body: string");
                 break;
             default:
-                fields.push(`readonly body: Produced<z.infer<typeof ${member.schemaName}>>`);
+                fields.push(`readonly body: Produced<z.input<typeof ${member.schemaName}>>`);
         }
         if (response.headers.length > 0) {
             /**
@@ -328,7 +324,7 @@ export function renderTools(entries, declaredOperationIds, options) {
         if (entry.names.body !== undefined)
             imported.add(entry.names.body);
         for (const member of membersOf(entry.route, entry.names)) {
-            const serving = bodyServingOf(member);
+            const serving = member.serving;
             if ((serving === "json" || serving === "text") && member.schemaName !== undefined) {
                 imported.add(member.schemaName);
             }
@@ -349,6 +345,12 @@ export function renderTools(entries, declaredOperationIds, options) {
     const runtimeTypes = ["McpServer", "ServerContext", "ToolDeps"];
     if (entries.length > 0)
         runtimeTypes.push("Awaitable");
+    const usesByteStream = entries.some((entry) => membersOf(entry.route, entry.names).some((member) => {
+        const serving = member.serving;
+        return serving === "binary" || serving === "stream";
+    }));
+    if (usesByteStream)
+        runtimeTypes.push("ByteStream");
     const from = JSON.stringify(DEFAULT_RUNTIME_MODULE);
     const runtimeImport = [
         ...(entries.length > 0 ? [`import { toolResult } from ${from};`] : []),
@@ -364,7 +366,7 @@ export function renderTools(entries, declaredOperationIds, options) {
      */
     const usesFields = entries.some((entry) => intersectedValidators(entry).length > 0);
     const usesProduced = entries.some((entry) => membersOf(entry.route, entry.names).some((member) => {
-        const serving = bodyServingOf(member);
+        const serving = member.serving;
         return serving === "json" || serving === "text";
     }));
     const helpers = `${usesFields ? FIELDS_HELPER : ""}${usesProduced ? PRODUCED_HELPER : ""}`;
@@ -418,10 +420,16 @@ export function renderTools(entries, declaredOperationIds, options) {
          * The body kinds the runtime cannot read off an arm, only where one applies: a JSON body is
          * known from its media type, and most operations answer nothing else.
          */
-        const kinds = bodyKindsOf(entry.route);
-        const bodies = kinds.length === 0
+        const kinds = new Map();
+        for (const [status, mediaType, kind] of bodyKindsOf(entry.route, entry.names)) {
+            kinds.set(status, [
+                ...(kinds.get(status) ?? []),
+                `${JSON.stringify(mediaType)}: ${JSON.stringify(kind)}`,
+            ]);
+        }
+        const bodies = kinds.size === 0
             ? ""
-            : `, bodies: { ${kinds.map(([status, kind]) => `${JSON.stringify(status)}: ${JSON.stringify(kind)}`).join(", ")} }`;
+            : `, bodies: { ${[...kinds].map(([status, byType]) => `${JSON.stringify(status)}: { ${byType.join(", ")} }`).join(", ")} }`;
         const declared = `{ arms: ${entry.names.responses}, outputSchema: ${published ?? "undefined"}${bodies} }`;
         /**
          * **A parameterless tool must not DECLARE an argument it never reads.**
@@ -432,7 +440,13 @@ export function renderTools(entries, declaredOperationIds, options) {
          * omission is deliberate.
          */
         const parameterless = intersectedValidators(entry).length === 0 && entry.route.bodyProperty === undefined;
-        const argument = parameterless ? "{}" : "{ ...args }";
+        // The selected `accept` last, so a caller's own `accept` argument cannot replace it.
+        const supplied = selectedAcceptOf(entry);
+        const fields = [
+            ...(parameterless ? [] : ["...args"]),
+            ...(supplied === undefined ? [] : [supplied]),
+        ];
+        const argument = fields.length === 0 ? "{}" : `{ ${fields.join(", ")} }`;
         const argumentName = parameterless ? "_args" : "args";
         return `	{
 		const tool = server.registerTool(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-http-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeSpec emitter: generate an MCP tool surface, and the Zod validators it publishes, from an HTTP service definition, dispatching into the same handlers a generated HTTP server calls.",
   "keywords": [
     "cloudflare-workers",
@@ -45,29 +45,29 @@
     "provenance": true
   },
   "dependencies": {
-    "typespec-http-zod": "^0.26.0"
+    "typespec-http-zod": "^0.28.0"
   },
   "devDependencies": {
     "@hono/zod-validator": "^0.9.1",
     "@modelcontextprotocol/client": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
     "@types/node": "^26.5.1",
-    "@typespec/compiler": "1.16.0",
-    "@typespec/events": "0.86.0",
-    "@typespec/http": "1.16.0",
-    "@typespec/http-specs": "0.1.0-alpha.43",
-    "@typespec/openapi": "1.16.0",
-    "@typespec/openapi3": "1.16.0",
-    "@typespec/rest": "0.86.0",
-    "@typespec/sse": "0.86.0",
-    "@typespec/streams": "0.86.0",
-    "@typespec/versioning": "0.86.0",
-    "@typespec/xml": "0.86.0",
+    "@typespec/compiler": "1.17.0",
+    "@typespec/events": "0.87.0",
+    "@typespec/http": "1.17.0",
+    "@typespec/http-specs": "0.1.0-alpha.44",
+    "@typespec/openapi": "1.17.0",
+    "@typespec/openapi3": "1.17.0",
+    "@typespec/rest": "0.87.0",
+    "@typespec/sse": "0.87.0",
+    "@typespec/streams": "0.87.0",
+    "@typespec/versioning": "0.87.0",
+    "@typespec/xml": "0.87.0",
     "hono": "^4.13.7",
     "oxfmt": "^0.67.0",
     "oxlint": "^1.82.0",
     "typescript": "~7.0.2",
-    "typespec-hono": "0.23.0",
+    "typespec-hono": "0.25.0",
     "typespec-http-mcp": "link:.",
     "vitest": "^5.0.0",
     "wrangler": "^4.131.1",
@@ -77,6 +77,7 @@
     "@modelcontextprotocol/server": "^2.0.0",
     "@typespec/compiler": "^1.15.0",
     "@typespec/http": "^1.15.0",
+    "@typespec/openapi": "^1.15.0",
     "zod": "^4.5.0"
   },
   "engines": {
@@ -84,7 +85,7 @@
   },
   "tspMain": "lib/main.tsp",
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node --eval \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
     "test": "tsc -p tsconfig.build.json && vitest run",
     "test:unit": "tsc -p tsconfig.build.json && vitest run --project unit",
     "typecheck": "tsc -p tsconfig.json",