typespec-http-mcp 0.1.0

package/dist/src/emitter.js

@@ -0,0 +1,237 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { emitFile, NoTarget, resolvePath } from "@typespec/compiler";
+import { getDoc, getSummary } from "@typespec/compiler";
+import { emitHttpZod } from "typespec-http-zod";
+import { PACKAGE_NAME, reportDiagnostic } from "./lib.js";
+import { nameTools } from "./names.js";
+import { collisionsFor } from "./coexistence.js";
+import { refusalFor, warningsFor } from "./refusals.js";
+import { renderTools } from "./tools.js";
+import { httpOperationFor, selectTools } from "./select.js";
+/**
+ * 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";
+/** Where this package's own runtime source lives, to be copied beside the generated code. */
+const RUNTIME_SOURCE = fileURLToPath(new URL("../../src/runtime.ts", import.meta.url));
+/** The header the emitted runtime carries, matching every other generated file. */
+function generatedRuntimeBanner(hint) {
+    const second = hint === undefined
+        ? "// A copy of this package's runtime, emitted so the generated code imports no package at run time."
+        : `// Regenerate with: ${hint}`;
+    return `// GENERATED by typespec-http-mcp. DO NOT EDIT.
+${second}
+`;
+}
+/**
+ * The options with `runtime-module` refused and removed, at the top level and per service.
+ *
+ * **Removed, not only reported**, because the library validates nothing about a key it no longer
+ * declares, and a wrapper passing options through should not hand it one. The same refusal the
+ * sibling server emitter makes, for the same option.
+ */
+function withoutRuntimeModule(context) {
+    const options = context.options;
+    const refuse = (value) => {
+        reportDiagnostic(context.program, {
+            code: "runtime-module-removed",
+            format: { value: String(value) },
+            target: NoTarget,
+        });
+    };
+    const { "runtime-module": topLevel, services, ...rest } = options;
+    if (topLevel !== undefined)
+        refuse(topLevel);
+    const kept = services === undefined
+        ? undefined
+        : Object.fromEntries(Object.entries(services).map(([name, service]) => {
+            const { "runtime-module": perService, ...others } = service;
+            if (perService !== undefined)
+                refuse(perService);
+            return [name, others];
+        }));
+    return {
+        ...context,
+        options: kept === undefined ? rest : { ...rest, services: kept },
+    };
+}
+function resolveToolOptions(options, serviceName) {
+    const perService = options.services?.[serviceName];
+    return {
+        emitTools: perService?.["emit-tools"] ?? true,
+        toolTags: perService?.["tool-tags"] ?? options["tool-tags"],
+        excludeTags: perService?.["exclude-tags"] ?? options["exclude-tags"] ?? [],
+        toolPrefix: perService?.["tool-prefix"] ?? options["tool-prefix"],
+    };
+}
+/**
+ * Where a diagnostic about an operation should point.
+ *
+ * **Keyed on verb and path, never on operation name.** Matching by name never succeeds for an
+ * operation declared inside an `interface`, which is most of them -- a defect this estate has
+ * already paid for once, where a whole class of refusal silently pointed at nothing.
+ */
+function targetFor(emitted, operationId) {
+    const route = emitted.routes.find((candidate) => candidate.operationId === operationId);
+    if (route === undefined)
+        return NoTarget;
+    return httpOperationFor(emitted.service, route)?.operation ?? NoTarget;
+}
+/**
+ * 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 async function $onEmit(context) {
+    const options = context.options;
+    /**
+     * Raised once per program, before anything is written: it is about the arrangement, not about any
+     * one service, and a consumer needs to see it before they trust what landed on disk.
+     */
+    for (const collision of collisionsFor(context.program, PACKAGE_NAME, context.emitterOutputDir)) {
+        reportDiagnostic(context.program, {
+            code: "shared-output-dir",
+            target: NoTarget,
+            format: { emitter: collision.emitter, differing: collision.differing.join(", ") },
+        });
+    }
+    for (const emitted of await emitHttpZod(withoutRuntimeModule(context))) {
+        await emitFile(context.program, {
+            path: resolvePath(emitted.outputDir, "mcp-runtime.gen.ts"),
+            content: `${generatedRuntimeBanner(emitted.options.regenerateHint)}${readFileSync(RUNTIME_SOURCE, "utf8")}`,
+        });
+        const serviceName = emitted.service.namespace.name;
+        const resolved = resolveToolOptions(options, serviceName);
+        if (!resolved.emitTools)
+            continue;
+        const selection = selectTools(context.program, emitted.service, emitted.routes, {
+            toolTags: resolved.toolTags,
+            excludeTags: resolved.excludeTags,
+        });
+        if (selection.selected.length === 0) {
+            reportDiagnostic(context.program, {
+                code: "no-tools-selected",
+                target: NoTarget,
+                format: {
+                    service: serviceName,
+                    configured: resolved.toolTags === undefined
+                        ? "(unset, so every operation)"
+                        : resolved.toolTags.join(", "),
+                    available: selection.available.length === 0 ? "(none)" : selection.available.join(", "),
+                },
+            });
+            continue;
+        }
+        const named = nameTools(selection.selected, resolved.toolPrefix);
+        for (const refused of named.unrepresentable) {
+            reportDiagnostic(context.program, {
+                code: "unrepresentable-tool-name",
+                target: targetFor(emitted, refused.operationId),
+                format: { name: refused.name },
+            });
+        }
+        for (const collision of named.collisions) {
+            reportDiagnostic(context.program, {
+                code: "tool-name-collision",
+                target: targetFor(emitted, collision.second),
+                format: { first: collision.first, second: collision.second, name: collision.name },
+            });
+        }
+        const entries = [];
+        /**
+         * Refusals counted as they happen, so the invariant below can be arithmetic rather than a
+         * guess. A silent drop is then impossible: the numbers stop adding up.
+         */
+        let refused = named.unrepresentable.length + named.collisions.length * 2;
+        for (const route of emitted.routes) {
+            const toolName = named.names.get(route.operationId);
+            if (toolName === undefined)
+                continue;
+            const names = emitted.schemaNames.get(route.operationId);
+            const operation = httpOperationFor(emitted.service, route);
+            if (names === undefined || operation === undefined)
+                continue;
+            /** A refusal removes the operation from the surface, so it is counted, never skipped. */
+            const refusal = refusalFor(context.program, route, operation);
+            if (refusal !== undefined) {
+                refused += 1;
+                reportDiagnostic(context.program, {
+                    code: refusal.kind,
+                    target: targetFor(emitted, route.operationId),
+                    format: { operationId: route.operationId, types: refusal.types },
+                });
+                continue;
+            }
+            const description = getDoc(context.program, operation.operation);
+            const title = getSummary(context.program, operation.operation);
+            const described = description !== undefined || title !== undefined;
+            for (const warning of warningsFor(route, names, described)) {
+                const target = targetFor(emitted, route.operationId);
+                if (warning.code === "unvalidated-response-media-type") {
+                    reportDiagnostic(context.program, {
+                        code: warning.code,
+                        target,
+                        format: { operationId: route.operationId, ...warning.format },
+                    });
+                }
+                else {
+                    reportDiagnostic(context.program, {
+                        code: warning.code,
+                        target,
+                        format: { operationId: route.operationId },
+                    });
+                }
+            }
+            entries.push({
+                route,
+                names,
+                toolName,
+                /**
+                 * **Read from the IR, not re-derived.** The library publishes the document's own
+                 * requirements as of 0.25.0; before that it published only a flat scope union and a
+                 * boolean, so both server emitters rebuilt this by hand from a third read of the
+                 * program. Two hand-written copies of one rule, neither compared against the other.
+                 */
+                requirements: route.security,
+                /**
+                 * **The description a model reads to decide whether to call this tool.**
+                 *
+                 * `@doc` rather than `@summary`: the summary becomes the tool's `title`, which is for
+                 * display. Both are published by `@typespec/openapi3`, so neither is a new fact.
+                 */
+                description,
+                /**
+                 * **Read from `@summary` directly, not from `EmittedRoute.summary`.**
+                 *
+                 * The library's `summary` is `getSummary ?? getDoc`, which is right for its purposes and
+                 * wrong here: with only a doc comment declared it would emit a `title` byte-identical to
+                 * the `description`, so every tool would carry the same sentence twice in a payload the
+                 * model reads. A title is for display and is absent unless the spec declares one.
+                 */
+                title,
+            });
+        }
+        /**
+         * **`emitted + refused === selected`, asserted from structured counts rather than by reading
+         * the file back.** Deciding anything by pattern-matching emitted text is how this estate
+         * acquired a class of defect it then had to hunt for.
+         */
+        if (entries.length + refused !== selection.selected.length) {
+            throw new Error(`typespec-http-mcp internal invariant: ${entries.length} emitted + ${refused} refused ` +
+                `!== ${selection.selected.length} selected for '${serviceName}'`);
+        }
+        const rendered = renderTools(entries, emitted.routes.map((route) => route.operationId), {
+            sealed: emitted.options.sealObjectSchemas,
+            hint: emitted.options.regenerateHint,
+        });
+        await emitFile(context.program, {
+            path: resolvePath(emitted.outputDir, "mcp.gen.ts"),
+            content: rendered.text,
+        });
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The public API.
+ *
+ * Re-exports `typespec-http-zod` wholesale, as `typespec-hono` does, so a consumer building on this
+ * emitter has one specifier to import from rather than needing to know which package minted which
+ * name.
+ */
+export * from "typespec-http-zod";
+export { DEFAULT_RUNTIME_MODULE, $onEmit } from "./emitter.js";
+export { $lib, EmitterOptionsSchema, type EmitterOptions } from "./lib.js";

package/dist/src/index.js

@@ -0,0 +1,10 @@
+/**
+ * The public API.
+ *
+ * Re-exports `typespec-http-zod` wholesale, as `typespec-hono` does, so a consumer building on this
+ * emitter has one specifier to import from rather than needing to know which package minted which
+ * name.
+ */
+export * from "typespec-http-zod";
+export { DEFAULT_RUNTIME_MODULE, $onEmit } from "./emitter.js";
+export { $lib, EmitterOptionsSchema } from "./lib.js";

package/dist/src/lib.d.ts

@@ -0,0 +1,119 @@
+import { type CallableMessage, type DiagnosticReport, type JSONSchemaType, type Program, type TypeSpecLibrary } from "@typespec/compiler";
+import { type EmitterOptions as HttpZodOptions } from "typespec-http-zod";
+/**
+ * Everything `typespec-http-zod` accepts, plus what an MCP tool surface needs on top.
+ *
+ * **DERIVED, never restated, and the distinction is load-bearing.** This emitter runs the whole of
+ * `typespec-http-zod` and adds files beside its output; every option that package accepts has to
+ * reach it. Written as a second literal list, an option added there would be rejected here as
+ * unknown, or worse, accepted and silently dropped -- output that is wrong in a way no test of
+ * either package would see. `test/options.test.ts` asserts the forwarding as a CLASS.
+ *
+ * **`runtime-module` is declared here only to be REFUSED** (`runtime-module-removed`). The library no
+ * longer has the option, and a schema without the key would report only "must NOT have additional
+ * properties", which tells a consumer upgrading from a version that documented the option neither why
+ * nor what to do instead.
+ */
+export type EmitterOptions = HttpZodOptions & {
+    /** Refused. See `runtime-module-removed`. */
+    "runtime-module"?: string;
+    /**
+     * Tags that mark an operation as a tool. Unset means every operation is one.
+     *
+     * **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. Read with `getAllTags`, which
+     * includes tags inherited from the enclosing interface and namespace -- `getTags` returns only an
+     * operation's own, so an operation inside a `@tag`-carrying interface would report none and be
+     * silently dropped.
+     */
+    "tool-tags"?: string[];
+    /** Tags that exclude an operation from the tool surface, even when `tool-tags` selected it. */
+    "exclude-tags"?: string[];
+    /**
+     * Prepended to every tool name, verbatim -- the author owns the separator.
+     *
+     * The result is validated against MCP's name rule and REFUSED if it fails, never rewritten: an
+     * operation id is a fact the document publishes, and re-spelling it invents a second name for
+     * one thing.
+     */
+    "tool-prefix"?: string;
+    /**
+     * Per-service overrides this emitter adds on top of the library's.
+     *
+     * **The library's own `services` map is preserved**, because the type is an intersection: an
+     * option added there still arrives here, and this only widens what each entry may carry.
+     */
+    services?: Record<string, {
+        "emit-tools"?: boolean;
+        "tool-tags"?: string[];
+        "exclude-tags"?: string[];
+        "tool-prefix"?: string;
+        /** Refused. See `runtime-module-removed`. */
+        "runtime-module"?: string;
+    }>;
+};
+declare const EmitterOptionsSchema: JSONSchemaType<EmitterOptions>;
+/**
+ * **Spelled out rather than inferred, and every type in it imported through THIS package's own
+ * specifier.** Both this package and `typespec-http-zod` declare `@typespec/compiler` as a peer, so a
+ * side-by-side checkout resolves two physically distinct copies of the identical version. TypeScript
+ * then has a choice of which copy to name in the emitted declarations, and naming the other
+ * package's produces `TS2883`, whose message is exactly the problem: *"this is likely not portable"*.
+ *
+ * A published `.d.ts` naming a `node_modules/.pnpm/...` path is broken for everyone who installed
+ * differently. **A consumer never hits this**, because a peer dependency is installed once and both
+ * packages share it -- which is precisely why it is worth guarding rather than trusting: the failure
+ * exists only in the arrangement that BUILDS the package, and would ship silently.
+ */
+type Diagnostics = {
+    "no-tools-selected": {
+        readonly default: CallableMessage<["service", "configured", "available"]>;
+    };
+    "unrepresentable-tool-name": {
+        readonly default: CallableMessage<["name"]>;
+    };
+    "tool-name-collision": {
+        readonly default: CallableMessage<["first", "second", "name"]>;
+    };
+    "binary-tool-input": {
+        readonly default: CallableMessage<["operationId", "types"]>;
+    };
+    "non-json-request": {
+        readonly default: CallableMessage<["operationId", "types"]>;
+    };
+    "non-object-body": {
+        readonly default: CallableMessage<["operationId", "types"]>;
+    };
+    "binary-tool-output": {
+        readonly default: CallableMessage<["operationId", "types"]>;
+    };
+    "streamed-tool-output": {
+        readonly default: CallableMessage<["operationId", "types"]>;
+    };
+    "unvalidated-response-media-type": {
+        readonly default: CallableMessage<["operationId", "status", "types"]>;
+    };
+    "headers-only-success": {
+        readonly default: CallableMessage<["operationId"]>;
+    };
+    "tool-without-description": {
+        readonly default: CallableMessage<["operationId"]>;
+    };
+    "shared-output-dir": {
+        readonly default: CallableMessage<["emitter", "differing"]>;
+    };
+    "runtime-module-removed": {
+        readonly default: CallableMessage<["value"]>;
+    };
+};
+/**
+ * This emitter's name, as `tspconfig.yaml`, the compiler and every diagnostic code all spell it.
+ *
+ * **One literal, because two would be a guard that stops working silently.** `coexistence.ts` looks
+ * this emitter up in `program.compilerOptions.options` by name; a second copy that drifted would
+ * find nothing and report no collision, with nothing to indicate the check had stopped running.
+ */
+export declare const PACKAGE_NAME = "typespec-http-mcp";
+export declare const $lib: TypeSpecLibrary<Diagnostics, EmitterOptions>;
+export declare const reportDiagnostic: <C extends keyof Diagnostics, M extends keyof Diagnostics[C]>(program: Program, diagnostic: DiagnosticReport<Diagnostics, C, M>) => void;
+export { EmitterOptionsSchema };

package/dist/src/lib.js

@@ -0,0 +1,278 @@
+import { createTypeSpecLibrary, paramMessage, } from "@typespec/compiler";
+import { EmitterOptionsSchema as httpZodOptions, } from "typespec-http-zod";
+const toolSelection = {
+    "tool-tags": { type: "array", items: { type: "string" }, nullable: true },
+    "exclude-tags": { type: "array", items: { type: "string" }, nullable: true },
+    "tool-prefix": { type: "string", nullable: true },
+};
+/**
+ * **A spread of the published schema, so a new key arrives for free.**
+ *
+ * `properties` is spread rather than re-listed for the same reason the type is aliased rather than
+ * re-declared. The MCP-only keys are added to that spread, never by copying the library's list.
+ */
+/**
+ * The published schema, narrowed to the object variant it actually is.
+ *
+ * **`JSONSchemaType<T>` is a UNION of variants** -- an object schema, an `anyOf`, and others --
+ * and spreading a union-typed value yields a union, which then matches no single target. The value
+ * `typespec-http-zod` publishes is the object variant (measured: its runtime keys are `type`,
+ * `additionalProperties`, `properties`, `required`, with `type === "object"`). Narrowing once here
+ * is what keeps the four spreads below honest rather than casting at each of them, and
+ * `test/options.test.ts` grades the RESULT as a class, so a narrowing that ever became untrue would
+ * surface as a missing option rather than as a silent type hole.
+ */
+const httpZodObject = httpZodOptions;
+const EmitterOptionsSchema = {
+    ...httpZodObject,
+    properties: {
+        ...httpZodObject.properties,
+        ...toolSelection,
+        // Accepted by the schema so that setting it reaches `runtime-module-removed`.
+        "runtime-module": { type: "string", nullable: true },
+        /**
+         * **Spread from the library's own entry rather than restated**, so a per-service option added
+         * there still validates here.
+         */
+        services: {
+            ...httpZodObject.properties.services,
+            additionalProperties: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    ...httpZodObject.properties.services.additionalProperties.properties,
+                    ...toolSelection,
+                    "emit-tools": { type: "boolean", nullable: true },
+                    "runtime-module": { type: "string", nullable: true },
+                },
+                required: [],
+            },
+        },
+    },
+    /**
+     * **Asserted, and the assertion is graded rather than trusted.**
+     *
+     * The spread above carries the whole published schema, which is what keeps a new library option
+     * arriving here for free. It also carries `dependencies`, `dependentRequired` and
+     * `dependentSchemas`, whose TYPES are written over `keyof HttpZodOptions`. This emitter's option
+     * type adds three keys the library does not have, so those families no longer match under
+     * `exactOptionalPropertyTypes` -- `TS2375`. None of them is present at run time (measured: the
+     * published object's only keys are `type`, `additionalProperties`, `properties` and `required`)
+     * and this schema uses none of them.
+     *
+     * `typespec-hono` does not hit this because the only key it adds, `services`, the library already
+     * has, so its key set is identical.
+     *
+     * **What stops this hiding a real defect is `test/options.test.ts`**, which asserts as a CLASS
+     * that every option the library publishes appears here, top level and per service. A spread that
+     * silently stopped forwarding would fail there, where a type error would no longer.
+     */
+};
+/**
+ * What this emitter refuses that the library does not.
+ *
+ * The library refuses what no OpenAPI document can state. Everything here is narrower: what no MCP
+ * TOOL can express. Two different questions, and keeping them in separate libraries is what stops a
+ * consumer who wants validators without a tool surface inheriting a refusal about tools.
+ *
+ * **Warnings about the document, never errors.** A TypeSpec `error` sets `program.hasError()`, and
+ * `@typespec/openapi3` then writes nothing -- so an error here would cost the consumer their whole
+ * document over one operation this emitter happens not to like. The one error is about the
+ * CONFIGURATION, `runtime-module-removed`, where a warning would let a setting be silently ignored.
+ */
+const diagnostics = {
+    /**
+     * The selection matched nothing, for any reason: a typo in `tool-tags`, an `exclude-tags` that
+     * swallowed everything, an explicit empty list.
+     *
+     * The message names the tags the service ACTUALLY declares alongside the ones configured, because
+     * that is the cheap half of the fix and the emitter already has it.
+     */
+    "no-tools-selected": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `No operation in '${"service"}' was selected as a tool. Configured tool-tags: ${"configured"}. Tags this service declares: ${"available"}. Adjust 'tool-tags' or 'exclude-tags', or remove them to select every operation.`,
+        },
+    },
+    /**
+     * A tool name MCP cannot carry.
+     *
+     * Refused rather than rewritten. An operation id is a contract fact the document publishes; a
+     * generated second spelling of it is a name no reader of the document can predict. TypeSpec
+     * permits characters MCP's rule does not, so this fires for real specs rather than only in theory.
+     */
+    "unrepresentable-tool-name": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"name"}' is not a name MCP can carry: a tool name is 1 to 128 characters of A-Z, a-z, 0-9, '_', '-' or '.'. Name the operation with '@operationId("...")', or shorten 'tool-prefix'. This emitter will not re-spell a published operation id.`,
+        },
+    },
+    /**
+     * Another emitter writes where this one writes, with options that disagree.
+     *
+     * Fires only when the resolved LIBRARY options differ. Sharing a directory with matching options
+     * is the arrangement that makes one set of validators serve both surfaces, and it is silent.
+     */
+    "shared-output-dir": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"emitter"}' writes to the same emitter-output-dir as this emitter with different options (${"differing"}), so 'schemas.gen.ts' is written twice with different content and whichever emitter is listed LAST in 'emit:' wins. Give each emitter its own 'emitter-output-dir', or set the same values on both.`,
+        },
+    },
+    /**
+     * A request body an MCP tool argument cannot carry.
+     *
+     * A tool's arguments are JSON. A raw `bytes` body, a stream, or a `multipart/form-data` upload is
+     * not JSON and cannot become one without inventing an encoding the document never states.
+     * **Refused rather than approximated**: base64-ing a body into a string argument would publish a
+     * contract no reader of the document could predict, and would put a whole upload through a model's
+     * context window.
+     */
+    "binary-tool-input": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"operationId"}' takes a binary or multipart request body (${"types"}), which an MCP tool argument cannot carry: tool arguments are JSON. Exclude it with 'exclude-tags', or declare a JSON-bodied operation for the tool surface.`,
+        },
+    },
+    /**
+     * A response body an MCP tool result cannot carry, because it is raw bytes with no content block.
+     *
+     * A tool result is content blocks. MCP has an `image` and an `audio` block, each carrying base64
+     * data and its media type, and those are what an `image/*` or `audio/*` body becomes. 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. **Refused rather than approximated**: base64 in
+     * a text block would publish an encoding no reader of the document could predict, and would put a
+     * whole download through a model's context window.
+     */
+    "binary-tool-output": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"operationId"}' answers with a binary body (${"types"}) that no MCP content block carries: a tool result is text, JSON, an 'image/*' block or an 'audio/*' block. Exclude it with 'exclude-tags', or declare an image or audio media type, or a JSON body, for the tool surface.`,
+        },
+    },
+    /**
+     * A streamed response, which a tool result cannot be.
+     *
+     * An SSE or JSONL response is unbounded and arrives over time; a tool call answers with one message.
+     * Buffering waits on a stream that may never end, and answering the first event would publish a
+     * contract no reader of the document could predict.
+     */
+    "streamed-tool-output": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"operationId"}' answers with a stream (${"types"}), and an MCP tool result is one message. Exclude it with 'exclude-tags', or declare an operation that answers once for the tool surface.`,
+        },
+    },
+    /**
+     * A response the handler supplies as text, answered without being checked against its schema.
+     *
+     * A model declared under a media type that is not JSON -- an `Item` as `application/xml` -- has no
+     * serialisation this emitter can derive from the document, so the handler returns the text and the
+     * tool answers it as is. The same code, and the same trigger, as the sibling server emitter's, so a
+     * project emitting both surfaces reads one warning about one response.
+     */
+    "unvalidated-response-media-type": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"operationId"}' answers ${"status"} as ${"types"}, which this emitter cannot serialise from the schema. The handler returns that body as text and the tool answers it without validating it. Declare a JSON media type, or a string body, to have it checked.`,
+        },
+    },
+    /**
+     * A request body with no properties to merge into a tool's argument object.
+     *
+     * A tool takes ONE object. The document states the body separately from the parameters, so the
+     * two are merged -- and a scalar, enum, union or array body has nothing to merge. Naming it under
+     * an invented property would publish a contract no reader of the document could predict.
+     */
+    "non-object-body": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"operationId"}' has a request body that is not an object (${"types"}), and an MCP tool's arguments are one object with named properties. Wrap it in a model with a named property, or exclude the operation with 'exclude-tags'.`,
+        },
+    },
+    /**
+     * Every declared request media type is one a tool cannot send.
+     *
+     * Fires only where NO JSON media 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 worth a diagnostic.
+     */
+    "non-json-request": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"operationId"}' declares only non-JSON request media types (${"types"}), and an MCP tool sends JSON. Declare 'application/json' alongside them.`,
+        },
+    },
+    /**
+     * A success that carries headers and no body.
+     *
+     * The tool would return nothing a model can read: response headers go to `_meta`, which a model
+     * does not see. **Not a refusal** -- the tool is still emitted, because the operation is callable
+     * and its effect may be the point. It is a warning because the value is invisible where it
+     * matters.
+     */
+    "headers-only-success": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"operationId"}' answers with response headers and no body, so its tool returns nothing a model can read: headers are carried in '_meta', which a model does not see. Declare the value in the response body.`,
+        },
+    },
+    /**
+     * `runtime-module` is set, and this emitter no longer substitutes its runtime.
+     *
+     * **The option made an application OWN a copy of generated logic**, because the generated tools
+     * imported the application's `Ctx` and `Result` from the same module as arm selection and the
+     * tool-result rules. So every consumer that needed its own caller context or result shape copied
+     * those too, and a copy ages with every release it is not updated for.
+     *
+     * Nothing the option 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. **An error rather
+     * than a warning**, because the option's value is ignored, and an emitter that silently ignores a
+     * setting produces output its author did not ask for.
+     */
+    "runtime-module-removed": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'runtime-module' is set to '${"value"}', and typespec-http-mcp no longer substitutes its runtime: 'mcp-runtime.gen.ts' is always emitted. Remove the option and delete the module it pointed at. The caller context is inferred from 'deps.context', and a handler returns '{ status, body, headers }' for any response the document declares. See the Upgrading section of docs/guides.md.`,
+        },
+    },
+    /**
+     * A selected operation with nothing for a model to read.
+     *
+     * A model chooses a tool by its description. Fires only for SELECTED operations: an opinion about
+     * an operation that is not a tool is not this emitter's business.
+     */
+    "tool-without-description": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"operationId"}' becomes a tool with no description. A model chooses tools by their description, so an undescribed one is unlikely to be called correctly. Add a doc comment, or '@summary'.`,
+        },
+    },
+    /**
+     * Two selected operations produce one tool name.
+     *
+     * **BOTH are refused, and that is deliberate.** Keeping one and dropping the other would make the
+     * tool surface depend on which operation the emitter happened to reach first -- a surface that
+     * works and is wrong, which is strictly worse than one that is absent and says so.
+     */
+    "tool-name-collision": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"first"}' and '${"second"}' both produce the tool name '${"name"}', so neither is emitted. Give one of them an '@operationId', or set a per-service 'tool-prefix'.`,
+        },
+    },
+};
+/**
+ * This emitter's name, as `tspconfig.yaml`, the compiler and every diagnostic code all spell it.
+ *
+ * **One literal, because two would be a guard that stops working silently.** `coexistence.ts` looks
+ * this emitter up in `program.compilerOptions.options` by name; a second copy that drifted would
+ * find nothing and report no collision, with nothing to indicate the check had stopped running.
+ */
+export const PACKAGE_NAME = "typespec-http-mcp";
+export const $lib = createTypeSpecLibrary({
+    name: PACKAGE_NAME,
+    diagnostics,
+    emitter: { options: EmitterOptionsSchema },
+});
+export const reportDiagnostic = $lib.reportDiagnostic;
+export { EmitterOptionsSchema };