typespec-http-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bison Digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# typespec-http-mcp
+
+A TypeSpec emitter that generates an **MCP tool surface** from an HTTP service definition, and the
+Zod validators it publishes.
+
+The generated code dispatches into **the same handler object** a generated HTTP server calls, so one
+implementation serves both surfaces and neither is written twice.
+
+```yaml
+# tspconfig.yaml
+emit:
+  - typespec-http-mcp
+options:
+  typespec-http-mcp:
+    emitter-output-dir: "{project-root}/src/generated"
+```
+
+Install it as a **devDependency**: nothing it emits imports it.
+
+```sh
+pnpm add -D typespec-http-mcp
+pnpm add @modelcontextprotocol/server zod
+```
+
+## What it emits, and what you write
+
+The generated file is **never edited, only called**. You own the `McpServer`, the transport and the
+authentication in front of it:
+
+```ts
+import { McpServer, createMcpHandler, type AuthInfo } from "@modelcontextprotocol/server";
+import { registerTools } from "./generated/mcp.gen.js";
+import type { ToolDeps } from "./generated/mcp-runtime.gen.js";
+import { handlers } from "./handlers.js"; // the same object your HTTP server gets
+
+/**
+ * The factory runs PER REQUEST and receives that request's verified identity, so `deps` is built
+ * here rather than once at module scope. Built once, `permits` would close over no caller and every
+ * client would see an identical tool list.
+ */
+const handler = createMcpHandler((context) => {
+	const scopes = context.authInfo?.scopes ?? [];
+
+	const deps: ToolDeps<AuthInfo> = {
+		permits: (requirements) =>
+			requirements.length === 0 ||
+			requirements.some((requirement) =>
+				Object.entries(requirement).every(([, needed]) =>
+					needed.every((scope) => scopes.includes(scope)),
+				),
+			),
+		context: (serverContext) => serverContext.http?.authInfo ?? null,
+		noContext: () => ({ content: [{ type: "text", text: "Not authenticated." }], isError: true }),
+	};
+
+	const server = new McpServer({ name: "widgets", version: "1.0.0" });
+	registerTools(server, () => handlers, deps);
+	return server;
+});
+
+export default {
+	fetch(request: Request): Promise<Response> {
+		return handler.fetch(request);
+	},
+};
+```
+
+`createMcpHandler` returns an object with a `fetch` method -- **not a callable**. Calling the
+returned value directly is the shape of Cloudflare's `agents` wrapper, not of this SDK, and gives
+`TypeError: handler is not a function`.
+
+## What a handler returns
+
+A handler returns `{ status, body, headers }` for any response the document declares, failures
+included:
+
+```ts
+import type { AuthInfo } from "@modelcontextprotocol/server";
+import type { Tools } from "./generated/mcp.gen.js";
+
+export const handlers = {
+	WidgetTools_read: (caller, input) => {
+		const widget = widgets.get(input.widgetId);
+		return widget === undefined
+			? { status: 404, body: { resource: input.widgetId } }
+			: { status: 200, body: widget };
+	},
+} satisfies Tools<AuthInfo>;
+```
+
+`caller` has the type `deps.context` returns, which `registerTools` infers; nothing declares it.
+`satisfies` keeps each `status` a literal, which is what selects the response
+it belongs to. **It is not an annotation**: annotating the object widens it, and the check that
+refuses a handler for an operation the spec no longer declares stops working. Where the same object
+also serves a generated HTTP server, write `satisfies Operations<Caller>` from that server's file
+instead, because a tool set may be a subset of the operations.
+
+What the model receives follows from the document:
+
+- a 4xx or 5xx is a tool-execution error, `isError: true`, whose text is that status's own body;
+- a JSON body is parsed against the schema its status publishes, and the parsed value is what is
+  sent. A body that does not match throws `ResponseContractError`, and a status the operation does
+  not declare throws `UndeclaredStatusError`;
+- `structuredContent` carries the body when its schema is the tool's `outputSchema`;
+- response headers are carried in `_meta["typespec-http-mcp/response-headers"]`, keyed by wire name.
+
+## What is derived, and from what
+
+Nothing is invented. Every field of a tool comes from something the document already states, or from
+a published specification:
+
+| tool field                   | derived from                                         |
+| ---------------------------- | ---------------------------------------------------- |
+| `name`                       | the operation id the document publishes              |
+| `title`                      | `@summary`                                           |
+| `description`                | `@doc`                                               |
+| `inputSchema`                | the emitted Zod schema, **input** projection         |
+| `outputSchema`               | the body every 2xx and 3xx status shares             |
+| `annotations.readOnlyHint`   | the method's safety, per IANA's HTTP Method Registry |
+| `annotations.idempotentHint` | the method's idempotence, same source                |
+| which operations are tools   | `@tag`, which `@typespec/openapi3` publishes         |
+
+There are **no decorators**. A decorator would let a spec state something the OpenAPI document
+cannot publish, so the emitted surface would enforce a rule no reader of the contract can see.
+
+## Documentation
+
+- [`docs/reference.md`](docs/reference.md) -- every option and every diagnostic.
+- [`docs/architecture.md`](docs/architecture.md) -- what each module owns, and the boundaries that are enforced.
+- [`docs/oracles.md`](docs/oracles.md) -- what each emitted artefact is compared against.
+- [`docs/guides.md`](docs/guides.md) -- wiring it up, serving both surfaces, and testing one.
+- [`docs/releasing.md`](docs/releasing.md) -- the local-registry rehearsal and the proof this package passed.
+- [`docs/measurements.md`](docs/measurements.md) -- the probes the design rests on.
+
+## Working record
+
+[`HANDOVER.md`](HANDOVER.md) -- state, the traps, and what is open.
+
+## Licence
+
+MIT.

package/dist/src/annotations.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The MCP tool hints, derived from the method's own semantics.
+ *
+ * **Every value here comes from RFC 9110, and the oracle that grades it is IANA's HTTP Method
+ * Registry** -- a table a third party publishes, not the one below. An arm that recomputed
+ * `verb in {GET, HEAD}` from this same map would agree with any mistake it contains.
+ *
+ * | hint | source |
+ * | --- | --- |
+ * | `readOnlyHint` | RFC 9110 s9.2.1, safe methods |
+ * | `idempotentHint` | RFC 9110 s9.2.2, idempotent methods |
+ * | `destructiveHint` | no external source; see below |
+ * | `openWorldHint` | not derivable, never written |
+ */
+export interface ToolAnnotations {
+    readonly readOnlyHint?: boolean;
+    readonly idempotentHint?: boolean;
+    readonly destructiveHint?: boolean;
+}
+/**
+ * What this emitter states about a method, and what it deliberately leaves unsaid.
+ *
+ * - `readOnlyHint: true` for a safe method. **`false` is never written**: it is MCP's default, so
+ *   writing it says nothing while implying the emitter knows something it does not.
+ * - `idempotentHint` is written in BOTH directions, because the document's method makes both
+ *   derivable. POST and PATCH are explicitly not idempotent, and saying so is a fact rather than a
+ *   guess.
+ * - `destructiveHint: true` for DELETE only. **Omitted for POST and PATCH**, where MCP's default of
+ *   `true` stands: the document gives no basis to contradict it, and an emitter must not invent one.
+ * - `openWorldHint` is never written. Whether an operation reaches beyond this service is not
+ *   something any OpenAPI keyword states.
+ */
+export declare function annotationsFor(verb: string): ToolAnnotations;

package/dist/src/annotations.js

@@ -0,0 +1,41 @@
+/**
+ * The MCP tool hints, derived from the method's own semantics.
+ *
+ * **Every value here comes from RFC 9110, and the oracle that grades it is IANA's HTTP Method
+ * Registry** -- a table a third party publishes, not the one below. An arm that recomputed
+ * `verb in {GET, HEAD}` from this same map would agree with any mistake it contains.
+ *
+ * | hint | source |
+ * | --- | --- |
+ * | `readOnlyHint` | RFC 9110 s9.2.1, safe methods |
+ * | `idempotentHint` | RFC 9110 s9.2.2, idempotent methods |
+ * | `destructiveHint` | no external source; see below |
+ * | `openWorldHint` | not derivable, never written |
+ */
+/** Safe methods: RFC 9110 s9.2.1. A safe method is also idempotent, s9.2.2. */
+const SAFE = new Set(["get", "head"]);
+/** Idempotent methods: RFC 9110 s9.2.2. */
+const IDEMPOTENT = new Set(["get", "head", "put", "delete"]);
+/**
+ * What this emitter states about a method, and what it deliberately leaves unsaid.
+ *
+ * - `readOnlyHint: true` for a safe method. **`false` is never written**: it is MCP's default, so
+ *   writing it says nothing while implying the emitter knows something it does not.
+ * - `idempotentHint` is written in BOTH directions, because the document's method makes both
+ *   derivable. POST and PATCH are explicitly not idempotent, and saying so is a fact rather than a
+ *   guess.
+ * - `destructiveHint: true` for DELETE only. **Omitted for POST and PATCH**, where MCP's default of
+ *   `true` stands: the document gives no basis to contradict it, and an emitter must not invent one.
+ * - `openWorldHint` is never written. Whether an operation reaches beyond this service is not
+ *   something any OpenAPI keyword states.
+ */
+export function annotationsFor(verb) {
+    const method = verb.toLowerCase();
+    const annotations = {};
+    if (SAFE.has(method))
+        annotations.readOnlyHint = true;
+    annotations.idempotentHint = IDEMPOTENT.has(method);
+    if (method === "delete")
+        annotations.destructiveHint = true;
+    return annotations;
+}

package/dist/src/bodies.d.ts

@@ -0,0 +1,69 @@
+import type { EmittedResponse, EmittedRoute, RouteSchemaNames } from "typespec-http-zod";
+/**
+ * **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 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.
+ *
+ * **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.
+ */
+export interface ResultMember {
+    readonly response: EmittedResponse;
+    /** The identifier the library declared this status's body under. */
+    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[];
+/**
+ * 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.
+ *
+ * - `"text"`: a string body, parsed against its schema and answered as a text block;
+ * - `"binary"`: raw bytes, answered as an `image` or `audio` block.
+ *
+ * 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.
+ */
+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.
+ *
+ * **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.
+ */
+export declare function bodyKindsOf(route: EmittedRoute): readonly (readonly [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"];
+    readonly types: readonly string[];
+}[];

package/dist/src/bodies.js

@@ -0,0 +1,94 @@
+/**
+ * **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";
+}
+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,
+        }));
+    });
+}
+/**
+ * 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.
+ *
+ * **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.
+ */
+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"]] : [];
+    });
+}
+/** 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")
+            .flatMap((member) => (member.mediaType === undefined ? [] : [member.mediaType]));
+        return types.length === 0 ? [] : [{ status: response.status, types }];
+    });
+}

package/dist/src/coexistence.d.ts

@@ -0,0 +1,13 @@
+import type { Program } from "@typespec/compiler";
+export interface Collision {
+    readonly emitter: string;
+    /** The library options the two emitters resolve differently. */
+    readonly differing: readonly string[];
+}
+/**
+ * Another emitter writing where this one writes, with library options that disagree.
+ *
+ * Returns nothing when the options MATCH: that arrangement produces byte-identical content and is
+ * the one worth encouraging.
+ */
+export declare function collisionsFor(program: Program, self: string, selfOutputDir: string): Collision[];

package/dist/src/coexistence.js

@@ -0,0 +1,91 @@
+/**
+ * **Two emitters writing one file is a silent last-writer-wins, and the winner is decided by the
+ * order of `emit:` in `tspconfig.yaml`.**
+ *
+ * `emitFile` has no duplicate-path detection -- measured in `@typespec/compiler@1.15.0`,
+ * `dist/src/core/emitter-utils.js:19-27`, which does `mkdirp`, records the path and writes. Two
+ * emitters that both run `typespec-http-zod` therefore both write `schemas.gen.ts`.
+ *
+ * Measured end to end on the published packages, with divergent `seal-object-schemas`:
+ *
+ * | `emit:` order | surviving `schemas.gen.ts` |
+ * | --- | --- |
+ * | server first, then library | 19 `z.object` -- unsealed |
+ * | library first, then server | 11 `z.object`, 8 `z.strictObject` -- sealed |
+ *
+ * Exit 0 both times, no diagnostic either time, and the two files differ. In the first row the
+ * server was generated believing schemas were sealed while the surviving file is not, so it
+ * validates more permissively than the emitter that wrote it believed.
+ *
+ * **The collision is opt-in, which is why this is a warning and not a refusal.** With nothing
+ * configured, `emitterOutputDir` defaults to `[outputDir, packageName]`
+ * (`dist/src/core/program.js:367-369`), so each emitter writes into a directory of its own and
+ * nothing collides. Only a consumer who deliberately points both at one directory can reach this --
+ * and that is a good arrangement when the options match, because it is what makes one set of
+ * validators serve both surfaces.
+ */
+/**
+ * The options that decide what `typespec-http-zod` writes.
+ *
+ * **Only these.** An emitter that shares a directory but does not accept them is not running the
+ * same library and is not contesting the same file -- `@typespec/openapi3` alongside a server
+ * emitter is the ordinary case, and warning about it would be noise.
+ */
+const SHARED_LIBRARY_OPTIONS = [
+    "contracts-output-dir",
+    "contracts-package",
+    "seal-object-schemas",
+    "compile-schemas",
+    "key-vocabularies",
+    "regenerate-hint",
+];
+/** Reproduces the compiler's own default, so a comparison means the same thing unconfigured. */
+function outputDirOf(program, emitter) {
+    const options = program.compilerOptions.options?.[emitter];
+    const configured = options?.["emitter-output-dir"];
+    if (typeof configured === "string")
+        return configured;
+    const base = program.compilerOptions.outputDir;
+    return base === undefined ? undefined : `${base}/${emitter}`;
+}
+/**
+ * Whether an emitter runs `typespec-http-zod`, read from the option schema its library PUBLISHES.
+ *
+ * **Not from whether it was given one of these options.** That was the rule, and it held only while
+ * both emitters were configured with a `runtime-module`: an emitter running the library on its
+ * defaults sets none of them, and a sibling beside it with `compile-schemas: false` then rewrote
+ * `schemas.gen.ts` with nothing said. An emitter that accepts every one of these options is running
+ * the library that reads them, whatever it was configured with.
+ */
+function runsLibrary(program, emitter) {
+    const loaded = program.emitters.find((ref) => ref.metadata.name === emitter);
+    const declared = loaded?.library.definition?.emitter?.options?.properties;
+    return declared !== undefined && SHARED_LIBRARY_OPTIONS.every((key) => key in declared);
+}
+/**
+ * Another emitter writing where this one writes, with library options that disagree.
+ *
+ * Returns nothing when the options MATCH: that arrangement produces byte-identical content and is
+ * the one worth encouraging.
+ */
+export function collisionsFor(program, self, selfOutputDir) {
+    const collisions = [];
+    const mine = program.compilerOptions.options?.[self];
+    for (const emitter of program.compilerOptions.emit ?? []) {
+        if (emitter === self)
+            continue;
+        if (outputDirOf(program, emitter) !== selfOutputDir)
+            continue;
+        if (!runsLibrary(program, emitter))
+            continue;
+        const theirs = program.compilerOptions.options?.[emitter];
+        const differing = SHARED_LIBRARY_OPTIONS.filter((key) => {
+            const a = mine?.[key];
+            const b = theirs?.[key];
+            return JSON.stringify(a ?? null) !== JSON.stringify(b ?? null);
+        });
+        if (differing.length > 0)
+            collisions.push({ emitter, differing });
+    }
+    return collisions;
+}

package/dist/src/emitter.d.ts

@@ -0,0 +1,15 @@
+import type { EmitContext } from "@typespec/compiler";
+/**
+ * Where emitted output imports its runtime from. Declared where the import is rendered, and
+ * re-exported here beside the code that writes the file.
+ */
+export { DEFAULT_RUNTIME_MODULE } from "./tools.js";
+/**
+ * Run the library, then add the MCP surface beside what it wrote.
+ *
+ * **This file may import only `./lib.js`, its own modules, the library's public API and external
+ * packages.** The same rule the library's own emitter entry point holds itself to, and for the same
+ * reason: it makes "the published API is sufficient to build an emitter on" true by construction
+ * rather than by assertion.
+ */
+export declare function $onEmit(context: EmitContext): Promise<void>;