typespec-http-mcp 0.1.0

package/dist/src/names.d.ts

@@ -0,0 +1,34 @@
+/**
+ * What an operation is called on the MCP surface.
+ *
+ * **The source is the operation id the DOCUMENT publishes, and it is never re-spelled.** An
+ * operation id is a contract fact; a generated second spelling of it is a name no reader of the
+ * document can predict. So a name this emitter cannot carry is REFUSED rather than rewritten -- the
+ * same rule the sibling emitter holds for path templates, and for the same reason: a surface that
+ * works and is wrong is strictly worse than one that is absent and says so.
+ */
+export declare function toolNameFor(operationId: string, prefix: string | undefined): string;
+export declare function isRepresentable(name: string): boolean;
+export interface NamedTools {
+    /** Operation id to tool name, for everything that survived. */
+    readonly names: ReadonlyMap<string, string>;
+    /** Operation ids refused because the name is unrepresentable. */
+    readonly unrepresentable: readonly {
+        readonly operationId: string;
+        readonly name: string;
+    }[];
+    /** Tool names two operations both produced. BOTH operations are refused. */
+    readonly collisions: readonly {
+        readonly name: string;
+        readonly first: string;
+        readonly second: string;
+    }[];
+}
+/**
+ * Name every selected operation, and report what cannot be named.
+ *
+ * **A collision refuses BOTH operations, deliberately.** Keeping one and dropping the other would
+ * make the tool surface depend on which operation the emitter happened to reach first -- a surface
+ * that answers, and answers as the wrong operation.
+ */
+export declare function nameTools(selected: readonly string[], prefix: string | undefined): NamedTools;

package/dist/src/names.js

@@ -0,0 +1,55 @@
+/**
+ * What an operation is called on the MCP surface.
+ *
+ * **The source is the operation id the DOCUMENT publishes, and it is never re-spelled.** An
+ * operation id is a contract fact; a generated second spelling of it is a name no reader of the
+ * document can predict. So a name this emitter cannot carry is REFUSED rather than rewritten -- the
+ * same rule the sibling emitter holds for path templates, and for the same reason: a surface that
+ * works and is wrong is strictly worse than one that is absent and says so.
+ */
+/**
+ * MCP's own rule: 1 to 128 characters of `A-Z`, `a-z`, `0-9`, `_`, `-` or `.`.
+ *
+ * TypeSpec permits characters this does not -- `$` reaches an operation id through a template
+ * instantiation -- so this refuses for real specs rather than only in theory.
+ */
+const MCP_TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
+export function toolNameFor(operationId, prefix) {
+    // Prepended verbatim: the author owns the separator, because any separator this emitter chose
+    // would be a spelling decision the document does not state.
+    return prefix === undefined ? operationId : `${prefix}${operationId}`;
+}
+export function isRepresentable(name) {
+    return MCP_TOOL_NAME.test(name);
+}
+/**
+ * Name every selected operation, and report what cannot be named.
+ *
+ * **A collision refuses BOTH operations, deliberately.** Keeping one and dropping the other would
+ * make the tool surface depend on which operation the emitter happened to reach first -- a surface
+ * that answers, and answers as the wrong operation.
+ */
+export function nameTools(selected, prefix) {
+    const names = new Map();
+    const unrepresentable = [];
+    const byName = new Map();
+    const collisions = [];
+    for (const operationId of selected) {
+        const name = toolNameFor(operationId, prefix);
+        if (!isRepresentable(name)) {
+            unrepresentable.push({ operationId, name });
+            continue;
+        }
+        const first = byName.get(name);
+        if (first !== undefined) {
+            collisions.push({ name, first, second: operationId });
+            continue;
+        }
+        byName.set(name, operationId);
+        names.set(operationId, name);
+    }
+    // Both sides of a collision are refused, so the winner recorded above is removed too.
+    for (const collision of collisions)
+        names.delete(collision.first);
+    return { names, unrepresentable, collisions };
+}

package/dist/src/refusals.d.ts

@@ -0,0 +1,52 @@
+import { type Program } from "@typespec/compiler";
+import type { HttpOperation } from "@typespec/http";
+import type { EmittedRoute, RouteSchemaNames } from "typespec-http-zod";
+export type Refusal = {
+    readonly kind: "binary-tool-input";
+    readonly types: string;
+} | {
+    readonly kind: "non-json-request";
+    readonly types: string;
+} | {
+    readonly kind: "non-object-body";
+    readonly types: string;
+} | {
+    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.
+ *
+ * **Not a refusal: a reserved-expansion path parameter.** That is a ROUTING fact -- it decides how a
+ * router matches a URL. MCP has no URI template, and the handler receives the same string either
+ * way. The sibling server emitter refuses it and should; that the two emitters have different
+ * refusal sets from one intermediate representation is the split working, not a gap.
+ */
+export declare function refusalFor(program: Program, route: EmittedRoute, operation: HttpOperation): Refusal | undefined;
+/** A quality warning, with what its message names. */
+export type Warning = {
+    readonly code: "headers-only-success" | "tool-without-description";
+    readonly format: object;
+} | {
+    readonly code: "unvalidated-response-media-type";
+    readonly format: {
+        readonly status: string;
+        readonly types: string;
+    };
+};
+/**
+ * Quality warnings: the tool is still emitted.
+ *
+ * `headers-only-success` fires where a 2xx or 3xx response carries headers and no body, so everything
+ * that response produces lands in `_meta` -- which a model does not read. Read off each declared
+ * response, ranges included, because a `2XX` with a header and no body answers the same way.
+ *
+ * `unvalidated-response-media-type` fires once per status whose body under some media type is a model
+ * no serialisation derives from -- an `Item` as `application/xml`. The handler supplies that text and
+ * the tool answers it unvalidated. The sibling server emitter raises the same warning, under the same
+ * code, for the same responses.
+ */
+export declare function warningsFor(route: EmittedRoute, names: RouteSchemaNames, described: boolean): readonly Warning[];

package/dist/src/refusals.js

@@ -0,0 +1,167 @@
+import { getDiscriminator } from "@typespec/compiler";
+import { hasContentBlock, unvalidatedResponsesOf } from "./bodies.js";
+/**
+ * What this emitter cannot express as a tool, and what it can express but should warn about.
+ *
+ * **The two are kept apart deliberately.** A REFUSAL removes the operation from the tool surface, so
+ * it must be counted: `emitted + refused === selected` is the invariant that makes a silent drop
+ * arithmetically impossible. A WARNING leaves the tool in place and says something about its quality.
+ * Conflating them would let a quality complaint quietly delete a tool.
+ */
+/** A media type a tool can actually send. `application/json`, and the `+json` structured suffix. */
+function isJson(contentType) {
+    const type = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+    return type === "application/json" || type.endsWith("+json");
+}
+function isMultipart(contentType) {
+    return (contentType.split(";")[0]?.trim().toLowerCase() ?? "").startsWith("multipart/");
+}
+/**
+ * Whether a request body can be MERGED into a tool's argument object.
+ *
+ * **A tool's arguments are one object, and the document states the body separately from the
+ * parameters, so the two are merged here.** A body that is a scalar, an enum, a union or an array
+ * has no properties to merge -- `@body body: string` produces a `ZodString`, and spreading its
+ * (absent) shape emits a file that does not compile. Naming it under an invented property would
+ * publish a contract no reader of the document could predict, and would break the shared handler
+ * signature, which takes the bare value.
+ *
+ * A body the library already NAMES is safe whatever its type: it is nested rather than merged.
+ */
+function isMergeableBody(program, type) {
+    if (type === undefined)
+        return true;
+    if (type.kind !== "Model")
+        return false;
+    // An array is a Model with an integer-keyed indexer, and has no properties to merge.
+    if (type.indexer?.key?.name === "integer")
+        return false;
+    /**
+     * A model carrying `@discriminator` is emitted as a UNION of its variants, not as an object --
+     * measured: `z.discriminatedUnion("kind", [...])`, which has no shape. Which variant arrived is
+     * decided by a value, so there is no single set of properties to merge into the arguments.
+     */
+    if (getDiscriminator(program, type) !== undefined)
+        return false;
+    /**
+     * **A TYPED index signature does not survive the merge.** A model carrying declared keys beside a
+     * `Record<float32>` spreads its shape into the argument object, and the index type is left behind:
+     * the merge publishes `{ [x: string]: unknown }` where the handler declares
+     * `{ [x: string]: number }`. Measured on the corpus, that is a `TS2345` in a file the consumer
+     * cannot edit.
+     *
+     * An `unknown`-valued indexer is ordinary model openness and merges without loss, so it is not
+     * refused -- the same distinction the library draws between openness and a dictionary.
+     */
+    for (let model = type; model !== undefined; model = model.baseModel) {
+        const indexer = model.indexer;
+        if (indexer?.key?.name === "string" && indexer.value?.kind !== "Intrinsic")
+            return false;
+    }
+    return true;
+}
+/**
+ * Why this operation cannot be a tool, or `undefined` where it can.
+ *
+ * **Not a refusal: a reserved-expansion path parameter.** That is a ROUTING fact -- it decides how a
+ * router matches a URL. MCP has no URI template, and the handler receives the same string either
+ * way. The sibling server emitter refuses it and should; that the two emitters have different
+ * refusal sets from one intermediate representation is the split working, not a gap.
+ */
+export function refusalFor(program, route, operation) {
+    const types = route.requestContentTypes;
+    /**
+     * 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.
+     */
+    if (route.rawBodyProperty !== undefined) {
+        return {
+            kind: "binary-tool-input",
+            types: types.length === 0 ? "a raw body" : types.join(", "),
+        };
+    }
+    if (types.some(isMultipart)) {
+        return { kind: "binary-tool-input", types: types.join(", ") };
+    }
+    /**
+     * Only where NO JSON type is declared beside them. Where one is, the tool sends JSON and the
+     * others are simply unreachable from MCP, which is not a defect.
+     */
+    if (types.length > 0 && !types.some(isJson)) {
+        return { kind: "non-json-request", types: types.join(", ") };
+    }
+    /**
+     * A body the library named is nested under that name and is safe whatever its type. An unnamed
+     * body is merged into the argument object, so it must have properties to merge.
+     */
+    if (route.bodyProperty === undefined) {
+        const body = operation.parameters.body?.type;
+        if (!isMergeableBody(program, body)) {
+            return { kind: "non-object-body", types: body?.kind ?? "unknown" };
+        }
+    }
+    /**
+     * **A stream is not one message, and a tool result is.** An SSE or JSONL response is unbounded and
+     * arrives over time; a tool call answers once. Buffering it would wait on a stream that may never
+     * end, and answering its first event would publish a contract no reader of the document could
+     * predict.
+     */
+    const streamed = route.responses.filter((response) => response.streamed);
+    if (streamed.length > 0) {
+        return {
+            kind: "streamed-tool-output",
+            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;
+}
+/**
+ * Quality warnings: the tool is still emitted.
+ *
+ * `headers-only-success` fires where a 2xx or 3xx response carries headers and no body, so everything
+ * that response produces lands in `_meta` -- which a model does not read. Read off each declared
+ * response, ranges included, because a `2XX` with a header and no body answers the same way.
+ *
+ * `unvalidated-response-media-type` fires once per status whose body under some media type is a model
+ * no serialisation derives from -- an `Item` as `application/xml`. The handler supplies that text and
+ * the tool answers it unvalidated. The sibling server emitter raises the same warning, under the same
+ * code, for the same responses.
+ */
+export function warningsFor(route, names, described) {
+    const warnings = [];
+    const headersOnlySuccess = route.responses.some((response) => isSuccess(response.status) && response.schema === undefined && response.headers.length > 0);
+    if (headersOnlySuccess)
+        warnings.push({ code: "headers-only-success", format: {} });
+    for (const { status, types } of unvalidatedResponsesOf(route, names)) {
+        warnings.push({
+            code: "unvalidated-response-media-type",
+            format: { status: String(status), types: types.join(", ") },
+        });
+    }
+    if (!described)
+        warnings.push({ code: "tool-without-description", format: {} });
+    return warnings;
+}
+/** A 2xx or 3xx status key, exact or ranged. */
+function isSuccess(status) {
+    if (typeof status === "number")
+        return status >= 200 && status < 400;
+    return status === "2XX" || status === "3XX";
+}

package/dist/src/runtime.d.ts

@@ -0,0 +1,191 @@
+import type { CallToolResult, McpServer, ServerContext } from "@modelcontextprotocol/server";
+import type { ZodError, ZodType } from "zod";
+/**
+ * **What generated code imports at run time -- and the only thing this package puts in its output.**
+ *
+ * **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
+ * separation rather than trusting it.
+ *
+ * **Always emitted, never substituted.** `runtime-module` used to point the generated file at a
+ * module of the application's own, which made the application own a copy of the arm selection and
+ * the result rules below. Nothing it was for needs it now: the caller context is inferred from
+ * `deps.context`, and what a handler returns is the union of the responses the document declares.
+ */
+/**
+ * The SDK types the generated signatures name, re-exported so emitted code has ONE specifier.
+ *
+ * **`export type`, not `export`.** Measured: `McpServer`, `ServerContext` and `CallToolResult` are
+ * type-only exports of `@modelcontextprotocol/server`; only `isCallToolResult` is a runtime value
+ * among them. A value re-export of any of these compiles and then fails at run time with
+ * `SyntaxError: The requested module does not provide an export named ...`.
+ */
+export type { CallToolResult, McpServer, ServerContext };
+/**
+ * One status an operation may answer with, and what the document publishes for it.
+ *
+ * **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
+ * 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
+ * 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
+ * code, then a range, then the catch-all. `schema: undefined` is a statement rather than an absence:
+ * a response the document says carries no body has no validator.
+ */
+export interface ResponseArm {
+    /** Every media type this response offers, including a single one. Absent where there is no body. */
+    readonly contentTypes?: readonly string[];
+    /**
+     * The headers this response declares, by the WIRE name the response sets. `optional` is the
+     * document's `required: false`. Absent where the response declares none.
+     */
+    readonly headers?: readonly {
+        readonly name: string;
+        readonly optional: boolean;
+    }[];
+    readonly status: number | "default" | `${1 | 2 | 3 | 4 | 5}XX`;
+    readonly schema: ZodType | undefined;
+}
+/**
+ * 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 declare function armFor(arms: readonly ResponseArm[], status: number): ResponseArm | undefined;
+/** An OpenAPI security requirement: scheme name to the scopes it demands. */
+export type SecurityRequirement = Readonly<Record<string, readonly string[]>>;
+export type Awaitable<T> = T | Promise<T>;
+/** What the document declares a tool may answer with, handed to {@link toolResult}. */
+export interface ToolResponses {
+    /** The operation's declared responses, in OpenAPI's precedence order. */
+    readonly arms: readonly ResponseArm[];
+    /**
+     * The schema this tool PUBLISHED, or `undefined` where it published none.
+     *
+     * Carried separately from the arms because MCP obliges a tool declaring an `outputSchema` to
+     * return conforming `structuredContent`, and which arm's schema was published is a decision the
+     * emitter made rather than something readable off the arms.
+     */
+    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.
+     *
+     * **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.
+     *
+     * - `"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.
+     *
+     * 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.
+     */
+    readonly bodies?: {
+        readonly [status: string]: "text" | "binary";
+    };
+}
+/**
+ * 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 declare class ResponseContractError extends Error {
+    readonly operationId: string;
+    readonly status: number;
+    readonly issues: ZodError["issues"];
+    constructor(operationId: string, status: number, issues: ZodError["issues"]);
+}
+/**
+ * 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 declare class UndeclaredStatusError extends Error {
+    readonly operationId: string;
+    readonly result: unknown;
+    constructor(operationId: string, result: unknown);
+}
+/**
+ * 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 declare function toolResult(declared: ToolResponses, operationId: string, result: unknown): Promise<CallToolResult>;
+/**
+ * What the emitter cannot derive from the document, and the application must answer.
+ *
+ * The admission test for a member is the sibling emitter's: *the generated code cannot proceed
+ * without an answer*. Everything derivable lives above, in the runtime.
+ *
+ * **`C` is the caller context, and `registerTools` INFERS it from `context`.** An application whose
+ * `context` returns a `Caller` has handlers typed `(ctx: Caller, input)`, with nothing to declare.
+ */
+export interface ToolDeps<C = unknown> {
+    /**
+     * Whether the caller this server was built for may SEE this tool.
+     *
+     * **Consulted at REGISTRATION, not at call time.** The MCP specification says the tool set may
+     * vary by the authorisation presented on the request, since credentials are per-request input
+     * rather than connection state -- so the idiomatic gesture is that a caller does not see a tool
+     * they cannot call, rather than being refused after calling it. That is a genuine divergence
+     * from an HTTP surface, where a 403 is the right answer and middleware is the right shape.
+     *
+     * Receives the `security` the document publishes for the operation: satisfying ANY ONE requirement
+     * authorises, and every scheme WITHIN a requirement must be satisfied together. An anonymous
+     * alternative is the empty requirement `{}`, which every caller satisfies: `@useAuth(NoAuth)` is
+     * `[{}]` and `NoAuth | BearerAuth` is `[{}, { BearerAuth: [] }]`. An operation declaring no auth
+     * at all is `[]`. Both are facts rather than absences, because an application may still choose to
+     * hide a public tool from an anonymous caller.
+     *
+     * A grant that selects nothing is not an error: nothing is registered and `tools/list` answers
+     * with a well-formed empty list. `registerTools` returns the names it did register, which is how
+     * an application observes that.
+     */
+    readonly permits: (requirements: readonly SecurityRequirement[]) => boolean;
+    /**
+     * The caller's context, or `null` when there is none to establish.
+     *
+     * `authentication` is what the DOCUMENT says and only that, decided at generation time:
+     *
+     * - `"none"`: no alternative asks for anything, `@useAuth(NoAuth)` or no auth at all;
+     * - `"optional"`: an anonymous alternative sits beside a real one, `NoAuth | BearerAuth`, so a
+     *   caller presenting a credential is recognised and one presenting none is still admitted;
+     * - `"required"`: every alternative asks for something.
+     *
+     * Nothing richer is offered, because nothing richer is published -- the sibling emitter once
+     * invented a distinction from whether a path had parameters, which no OpenAPI keyword expresses.
+     */
+    readonly context: (context: ServerContext, authentication: "none" | "optional" | "required") => C | null;
+    /** The result when {@link context} returns `null`. The application's to decide. */
+    readonly noContext: (context: ServerContext) => CallToolResult;
+}