typespec-http-mcp 0.2.0 → 0.4.0

package/dist/src/lib.d.ts

@@ -75,6 +75,9 @@ type Diagnostics = {
     "tool-name-collision": {
         readonly default: CallableMessage<["first", "second", "name"]>;
     };
+    "shared-input-key": {
+        readonly default: CallableMessage<["operationId", "types"]>;
+    };
     "binary-tool-input": {
         readonly default: CallableMessage<["operationId", "types"]>;
     };

package/dist/src/lib.js

@@ -128,6 +128,23 @@ const diagnostics = {
      * contract no reader of the document could predict, and would put a whole upload through a model's
      * context window.
      */
+    /**
+     * **An operation two of whose inputs would arrive as one argument is not a tool.**
+     *
+     * A tool's arguments are the path, query, header and cookie groups spread into one object, the
+     * body merged or named beside them - the same input a server's handler receives. `@header("x")`
+     * beside `@query("x")` therefore published one `x` argument, the later group's schema replacing
+     * the earlier, and the handler was handed one value for two declarations (typespec-http-graphql,
+     * 2026-10-16). `typespec-http-zod` names the pair in `EmittedRoute.sharedInputKeys` and reports it
+     * as its own `shared-input-key`; this is the tool surface declining it, as `typespec-hono` declines
+     * to mount it.
+     */
+    "shared-input-key": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"operationId"}' is not a tool: ${"types"} would arrive as one argument, which holds one value. Give one of them a different name, or exclude the operation with 'exclude-tags'.`,
+        },
+    },
     "binary-tool-input": {
         severity: "warning",
         messages: {

package/dist/src/refusals.d.ts

@@ -2,6 +2,9 @@ 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: "shared-input-key";
+    readonly types: string;
+} | {
     readonly kind: "binary-tool-input";
     readonly types: string;
 } | {

package/dist/src/refusals.js

@@ -8,6 +8,14 @@ import { unvalidatedResponsesOf } from "./bodies.js";
  * 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.
  */
+/** How a `shared-input-key` refusal names where each of the two inputs comes from. */
+const INPUT_LOCATION_NOUNS = {
+    path: "path parameter",
+    query: "query parameter",
+    header: "header",
+    cookie: "cookie",
+    body: "body",
+};
 /** 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() ?? "";
@@ -70,6 +78,21 @@ function isMergeableBody(program, type) {
  */
 export function refusalFor(program, route, operation) {
     const types = route.requestContentTypes;
+    /**
+     * **Two inputs under one key cannot both be arguments.** A tool's arguments are the parameter
+     * groups spread into one object, as a server's handler input is, so `@header("x")` beside
+     * `@query("x")` published one `x` whose later schema replaced the earlier, and the handler was
+     * handed one value for two declarations. The library names every such pair; the operation is not
+     * a tool, for the reason `typespec-hono` does not mount it.
+     */
+    if (route.sharedInputKeys.length > 0) {
+        return {
+            kind: "shared-input-key",
+            types: route.sharedInputKeys
+                .map((shared) => `the ${INPUT_LOCATION_NOUNS[shared.first]} '${shared.key}' and the ${INPUT_LOCATION_NOUNS[shared.second]} '${shared.key}'`)
+                .join("; "),
+        };
+    }
     /**
      * 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
@@ -101,7 +124,12 @@ export function refusalFor(program, route, operation) {
      * body is merged into the argument object, so it must have properties to merge.
      */
     if (route.bodyProperty === undefined) {
-        const body = operation.parameters.body?.type;
+        /**
+         * **A body declared `void` or `never` is no body**, and the library lists no media type for
+         * one; read that way, there is nothing to merge. Read off the operation, its intrinsic type is
+         * not an object and the tool was refused as `non-object-body`.
+         */
+        const body = types.length === 0 ? undefined : operation.parameters.body?.type;
         if (!isMergeableBody(program, body)) {
             return { kind: "non-object-body", types: body?.kind ?? "unknown" };
         }

package/dist/src/tools.js

@@ -1,4 +1,4 @@
-import { jsDocComment, mediaTypeTypeOf, objectKey, statusCodesOf, } from "typespec-http-zod";
+import { jsDocComment, mediaTypeTypeOf, literal, objectKey, statusCodesOf, } from "typespec-http-zod";
 import { annotationsFor } from "./annotations.js";
 import { bodyKindsOf, isJsonMediaType, membersOf } from "./bodies.js";
 /**
@@ -14,7 +14,7 @@ import { bodyKindsOf, isJsonMediaType, membersOf } from "./bodies.js";
 function renderSecurity(requirements) {
     return `[${requirements
         .map((requirement) => `{ ${Object.entries(requirement)
-        .map(([scheme, scopes]) => `${JSON.stringify(scheme)}: [${scopes.map((s) => JSON.stringify(s)).join(", ")}]`)
+        .map(([scheme, scopes]) => `${literal(scheme)}: [${scopes.map((s) => literal(s)).join(", ")}]`)
         .join(", ")} }`)
         .join(", ")}]`;
 }
@@ -162,7 +162,7 @@ function selectedAcceptOf(entry) {
     const selected = entry.names.selectedAccept;
     return selected === undefined
         ? undefined
-        : `${objectKey(selected.name)}: ${JSON.stringify(selected.value)}`;
+        : `${objectKey(selected.name)}: ${literal(selected.value)}`;
 }
 /**
  * The tool's ARGUMENT schema: every group the document declares, merged into one object.
@@ -182,6 +182,24 @@ function selectedAcceptOf(entry) {
 function inputSchemaOf(entry, sealed) {
     const constructor = sealed ? "z.strictObject" : "z.looseObject";
     const spreads = shapedValidators(entry).map((name) => `...${name}.shape`);
+    /**
+     * **A decoded path parameter takes its VALUE schema, not the path validator's field.** That field
+     * is `z.preprocess(<decode>, <value schema>)`: it reads the segment TEXT a router extracts -
+     * `primitive.a` for `{.param}` - and hands on `a`. A tool argument is already the value, so through
+     * the decoder `{ param: "a" }` was refused as not the expansion the route declares, while
+     * `tools/list` published `param` as a plain string, and a value starting with the route's literal
+     * was rewritten without an error (issue #1). Six `@typespec/http-specs` path scenarios failed.
+     *
+     * Which parameters are decoded is the library's fact, `decodedPathParameters`, read rather than
+     * re-derived, so this cannot drift from the validator it overrides. The override comes after the
+     * spread, so it wins.
+     */
+    const path = entry.names.path;
+    if (path !== undefined) {
+        for (const name of entry.route.decodedPathParameters) {
+            spreads.push(`${objectKey(name)}: ${path}.shape[${literal(name)}].out`);
+        }
+    }
     if (entry.route.bodyProperty !== undefined && entry.names.body !== undefined) {
         /**
          * **Optional where the document lets the body be absent.** It was required here while the
@@ -351,7 +369,7 @@ export function renderTools(entries, declaredOperationIds, options) {
     }));
     if (usesByteStream)
         runtimeTypes.push("ByteStream");
-    const from = JSON.stringify(DEFAULT_RUNTIME_MODULE);
+    const from = literal(DEFAULT_RUNTIME_MODULE);
     const runtimeImport = [
         ...(entries.length > 0 ? [`import { toolResult } from ${from};`] : []),
         `import type { ${runtimeTypes.toSorted().join(", ")} } from ${from};`,
@@ -396,10 +414,10 @@ export function renderTools(entries, declaredOperationIds, options) {
         .join("\n");
     /** Every scope any selected operation demands, de-duplicated and ordered. */
     const scopes = [...new Set(entries.flatMap((entry) => [...entry.route.scopes]))].toSorted();
-    const scopesLiteral = `[${scopes.map((scope) => JSON.stringify(scope)).join(", ")}]`;
+    const scopesLiteral = `[${scopes.map((scope) => literal(scope)).join(", ")}]`;
     const declaredUnion = declaredOperationIds.length === 0
         ? "never"
-        : declaredOperationIds.map((id) => JSON.stringify(id)).join(" | ");
+        : declaredOperationIds.map((id) => literal(id)).join(" | ");
     /**
      * **Registered in a deterministic order, sorted by tool name.**
      *
@@ -410,10 +428,10 @@ export function renderTools(entries, declaredOperationIds, options) {
     const ordered = [...entries].toSorted((a, b) => a.toolName.localeCompare(b.toolName));
     const registrations = ordered
         .map((entry) => {
-        const title = entry.title === undefined ? "" : `\n\t\t\t\ttitle: ${JSON.stringify(entry.title)},`;
+        const title = entry.title === undefined ? "" : `\n\t\t\t\ttitle: ${literal(entry.title)},`;
         const description = entry.description === undefined
             ? ""
-            : `\n\t\t\t\tdescription: ${JSON.stringify(entry.description)},`;
+            : `\n\t\t\t\tdescription: ${literal(entry.description)},`;
         const published = outputSchemaOf(entry);
         const outputSchema = published === undefined ? "" : `\n\t\t\t\toutputSchema: ${published},`;
         /**
@@ -424,12 +442,12 @@ export function renderTools(entries, declaredOperationIds, options) {
         for (const [status, mediaType, kind] of bodyKindsOf(entry.route, entry.names)) {
             kinds.set(status, [
                 ...(kinds.get(status) ?? []),
-                `${JSON.stringify(mediaType)}: ${JSON.stringify(kind)}`,
+                `${literal(mediaType)}: ${literal(kind)}`,
             ]);
         }
         const bodies = kinds.size === 0
             ? ""
-            : `, bodies: { ${[...kinds].map(([status, byType]) => `${JSON.stringify(status)}: { ${byType.join(", ")} }`).join(", ")} }`;
+            : `, bodies: { ${[...kinds].map(([status, byType]) => `${literal(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.**
@@ -450,23 +468,23 @@ export function renderTools(entries, declaredOperationIds, options) {
         const argumentName = parameterless ? "_args" : "args";
         return `	{
 		const tool = server.registerTool(
-			${JSON.stringify(entry.toolName)},
+			${literal(entry.toolName)},
 			{${title}${description}
 				inputSchema: ${inputSchemaName(entry)},${outputSchema}
 				annotations: ${renderAnnotations(annotationsFor(entry.route.verb))},
 			},
 			async (${argumentName}, context) => {
-				const ctx = deps.context(context, ${JSON.stringify(entry.route.authentication)});
+				const ctx = deps.context(context, ${literal(entry.route.authentication)});
 				if (ctx === null) return deps.noContext(context);
 				return toolResult(
 					${declared},
-					${JSON.stringify(entry.route.operationId)},
+					${literal(entry.route.operationId)},
 					await handlersFor(context).${entry.route.operationId}(ctx, ${argument}),
 				);
 			},
 		);
 		if (deps.permits(${renderSecurity(entry.requirements)})) {
-			registered.push(${JSON.stringify(entry.toolName)});
+			registered.push(${literal(entry.toolName)});
 		} else {
 			tool.remove();
 		}
@@ -531,7 +549,7 @@ export type ToolsExhaustive<T> = T & Record<Exclude<keyof T, DeclaredOperationId
 export const SCOPES_SUPPORTED = ${scopesLiteral} as const;
 
 /** Every tool this file registers, in the order it registers them. */
-export const TOOL_NAMES = [${ordered.map((entry) => JSON.stringify(entry.toolName)).join(", ")}] as const;
+export const TOOL_NAMES = [${ordered.map((entry) => literal(entry.toolName)).join(", ")}] as const;
 
 /**
  * Register every tool this service declares, onto a server the APPLICATION owns.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-http-mcp",
-  "version": "0.2.0",
+  "version": "0.4.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,7 +45,7 @@
     "provenance": true
   },
   "dependencies": {
-    "typespec-http-zod": "^0.28.0"
+    "typespec-http-zod": "^0.30.0"
   },
   "devDependencies": {
     "@hono/zod-validator": "^0.9.1",
@@ -67,7 +67,7 @@
     "oxfmt": "^0.67.0",
     "oxlint": "^1.82.0",
     "typescript": "~7.0.2",
-    "typespec-hono": "0.25.0",
+    "typespec-hono": "0.27.0",
     "typespec-http-mcp": "link:.",
     "vitest": "^5.0.0",
     "wrangler": "^4.131.1",