@ultimat3/mcp 22.6.0 → 22.6.2

package/README.md

@@ -287,6 +287,24 @@ implements the emitted subset (objects, arrays, enums, `required`, `additionalPr
 bounds, `default`) and applies declared defaults. Actions still re-parse authoritatively
 inside their own handler.
 
+## Idempotency over MCP
+
+An `idempotent: true` action's tool carries one reserved, optional argument,
+`MCP_IDEMPOTENCY_KEY_ARG` (`'idempotencyKey'`, string, 1–255), advertised in `tools/list` and held
+to that schema here. `tools/call` takes it out of the arguments and hands it to `invoke` as the
+idempotency key — what the `Idempotency-Key` header is over HTTP, filed under action, caller and
+key — so an agent retrying a timed-out call with the same key gets the first result back:
+
+```json
+{ "method": "tools/call", "params": { "name": "sendNotification",
+  "arguments": { "caseId": "c1", "idempotencyKey": "7f0c…" } } }
+```
+
+The action's own input never sees the key. A non-idempotent tool does not advertise it and refuses
+it (`X_MCP_ARGS_INVALID`). An argument, not `params._meta`: `_meta` is for host metadata and a
+model-driven client cannot set it. An idempotent action whose input already names `idempotencyKey`
+is `X_MCP_IDEMPOTENCY_KEY_SHADOWED` at boot.
+
 ## Errors
 
 | Code | Meaning |
@@ -296,6 +314,7 @@ inside their own handler.
 | `X_MCP_SCOPE_UNKNOWN` | `defineAppMcp`'s `scopes:` names a tool this server does not project |
 | `X_MCP_SCOPE_CONFLICT` | two scopes in `defineAppMcp`'s `scopes:` claim one tool |
 | `X_MCP_ARGS_INVALID` | arguments failed the declared schema |
+| `X_MCP_IDEMPOTENCY_KEY_SHADOWED` | an idempotent action's input declares `idempotencyKey`, the reserved retry-key argument |
 | `X_MCP_PROTOCOL` | malformed envelope, unknown method, bad auth header |
 | `X_MCP_QUERY_REJECTED` | `db.query` given anything but one read-only statement |
 | `X_MCP_NOT_BRANCH_DB` | `db.migrate` aimed at a production or otherwise non-branch database |
@@ -315,6 +334,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `McpAppUnmountedError` | `X_MCP_APP_UNMOUNTED` | `src/errors.ts` |
 | `McpArgsInvalidError` | `X_MCP_ARGS_INVALID` | `src/errors.ts` |
 | `McpBodyTooLargeError` | `X_MCP_BODY_TOO_LARGE` | `src/errors.ts` |
+| `McpIdempotencyKeyShadowedError` | `X_MCP_IDEMPOTENCY_KEY_SHADOWED` | `src/errors.ts` |
 | `McpGroupConflictError` | `X_MCP_GROUP_CONFLICT` | `src/meta-errors.ts` |
 | `McpGroupUnknownError` | `X_MCP_GROUP_UNKNOWN` | `src/meta-errors.ts` |
 | `McpListParamsInvalidError` | `X_MCP_LIST_PARAMS_INVALID` | `src/meta-errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mcp",
-  "version": "22.6.0",
+  "version": "22.6.2",
   "description": "MCP server, dev tools, and the action-to-tool projection \u2014 one authz system, two surfaces",
   "license": "MIT",
   "type": "module",
@@ -31,13 +31,13 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "22.6.0",
-    "@ultimat3/core": "22.6.0",
-    "@ultimat3/entity": "22.6.0",
-    "@ultimat3/http": "22.6.0",
-    "@ultimat3/jobs": "22.6.0",
-    "@ultimat3/policy": "22.6.0",
-    "@ultimat3/query": "22.6.0",
-    "@ultimat3/schema": "22.6.0"
+    "@ultimat3/action": "22.6.2",
+    "@ultimat3/core": "22.6.2",
+    "@ultimat3/entity": "22.6.2",
+    "@ultimat3/http": "22.6.2",
+    "@ultimat3/jobs": "22.6.2",
+    "@ultimat3/policy": "22.6.2",
+    "@ultimat3/query": "22.6.2",
+    "@ultimat3/schema": "22.6.2"
   }
 }

package/src/errors.ts

@@ -24,6 +24,7 @@ export const MCP_ERROR_CODES = [
   'X_MCP_SURFACE_INVALID',
   'X_MCP_LIST_PARAMS_INVALID',
   'X_MCP_OAUTH_INVALID',
+  'X_MCP_IDEMPOTENCY_KEY_SHADOWED',
 ] as const;
 
 export type McpErrorCode = (typeof MCP_ERROR_CODES)[number];
@@ -49,6 +50,8 @@ export const MCP_ERROR_TITLES: Readonly<Record<McpErrorCode, string>> = {
   X_MCP_SURFACE_INVALID: 'the MCP meta surface is declared inconsistently',
   X_MCP_LIST_PARAMS_INVALID: "a tool's listParams names a key its own input does not accept",
   X_MCP_OAUTH_INVALID: 'the MCP oauth block cannot be published as protected-resource metadata',
+  X_MCP_IDEMPOTENCY_KEY_SHADOWED:
+    "an idempotent action's input declares idempotencyKey, the MCP argument reserved for the idempotency key",
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -430,3 +433,19 @@ export class McpOAuthInvalidError extends UltimateError {
     });
   }
 }
+
+/**
+ * An idempotent action's tool carries the reserved `idempotencyKey` argument, and this action's
+ * own input already names a field that. One argument cannot be both the input a handler reads and
+ * the key a retry replays under, so the projection refuses at boot instead of guessing which.
+ */
+export class McpIdempotencyKeyShadowedError extends UltimateError {
+  constructor(input: { readonly name: string; readonly argument: string }) {
+    super({
+      code: 'X_MCP_IDEMPOTENCY_KEY_SHADOWED',
+      cause: `${input.name} is idempotent and its input declares "${input.argument}", the MCP argument reserved for the idempotency key`,
+      fix: `rename ${input.name}'s "${input.argument}" input field — MCP clients send the Idempotency-Key as the reserved "${input.argument}" argument, and the action receives the rest`,
+      meta: { action: input.name, argument: input.argument },
+    });
+  }
+}

package/src/idempotency-arg.ts

@@ -0,0 +1,73 @@
+// The MCP half of `idempotent: true`: the Idempotency-Key an HTTP caller sends as a header, sent
+// by an MCP caller as one reserved, optional tool ARGUMENT. An argument and not `params._meta`:
+// `_meta` is protocol metadata a host fills (a progress token), and no model-driven client lets the
+// model set it — the retry that needs a key is the agent's own, so the key goes where the agent
+// writes. It is advertised in `tools/list`, enforced by `validate-args.ts` like every other field,
+// and taken back out before `invoke`, so the action's own input parse never sees it.
+
+import { MAX_IDEMPOTENCY_KEY_LENGTH } from '@ultimat3/action';
+import { McpIdempotencyKeyShadowedError } from './errors';
+import type { JsonSchema } from './wire';
+
+/** The reserved argument name on every idempotent action's tool. */
+export const MCP_IDEMPOTENCY_KEY_ARG = 'idempotencyKey';
+
+/**
+ * Contract text, not UI text — it is what `tools/list` publishes, the same bytes for every caller,
+ * like an action's `mcp.description`.
+ */
+const DESCRIPTION =
+  'Idempotency key. Retrying this call with the same key and the same arguments returns the ' +
+  'first result instead of running it again; the same key with different arguments is refused. ' +
+  'Any unique string, e.g. a UUID — reuse it only to retry.';
+
+const KEY_SCHEMA: JsonSchema = {
+  type: 'string',
+  description: DESCRIPTION,
+  minLength: 1,
+  maxLength: MAX_IDEMPOTENCY_KEY_LENGTH,
+};
+
+/**
+ * `schema` with the optional key argument. An input that is not an object has no argument to
+ * add, and is left alone; one that already names the argument is refused, never merged.
+ */
+export function withIdempotencyKeyArg(name: string, schema: JsonSchema): JsonSchema {
+  if (schema.type !== 'object') return schema;
+  const properties = schema.properties ?? {};
+  if (Object.hasOwn(properties, MCP_IDEMPOTENCY_KEY_ARG)) {
+    throw new McpIdempotencyKeyShadowedError({ name, argument: MCP_IDEMPOTENCY_KEY_ARG });
+  }
+  return { ...schema, properties: { ...properties, [MCP_IDEMPOTENCY_KEY_ARG]: KEY_SCHEMA } };
+}
+
+/**
+ * The call's arguments split into the action's input and the key. Absent, empty-handed or not an
+ * object: the input as given and no key — `invoke` then runs the action un-keyed, as HTTP does
+ * without the header.
+ */
+export function takeIdempotencyKeyArg(args: unknown): {
+  readonly input: unknown;
+  readonly idempotencyKey: string | null;
+} {
+  if (typeof args !== 'object' || args === null || Array.isArray(args)) {
+    return { input: args, idempotencyKey: null };
+  }
+  if (!Object.hasOwn(args, MCP_IDEMPOTENCY_KEY_ARG)) return { input: args, idempotencyKey: null };
+  const input: Record<string, unknown> = {};
+  let key: unknown;
+  for (const [field, value] of Object.entries(args)) {
+    if (field === MCP_IDEMPOTENCY_KEY_ARG) key = value;
+    // defineProperty, never `input[field] =`: a `__proto__` field would re-prototype the copy.
+    else
+      Object.defineProperty(input, field, {
+        value,
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      });
+  }
+  // `validate-args.ts` already held the value to the advertised string schema, so a non-string can
+  // only come from a caller that skipped it — and a value that is not a string is not a key.
+  return { input, idempotencyKey: typeof key === 'string' ? key : null };
+}

package/src/index.ts

@@ -63,6 +63,7 @@ export {
   McpAppUnmountedError,
   McpArgsInvalidError,
   McpBodyTooLargeError,
+  McpIdempotencyKeyShadowedError,
   McpNotBranchDbError,
   McpOAuthInvalidError,
   McpProtocolError,
@@ -86,6 +87,7 @@ export {
   toolsFrom,
   toolsListed,
 } from './from-action';
+export { MCP_IDEMPOTENCY_KEY_ARG } from './idempotency-arg';
 export { toWireSchema } from './input-schema';
 export type { ListFilterOp, McpListParams } from './list-params';
 export { DEFAULT_LIST_MAX_LIMIT, listParamsSchema } from './list-params';

package/src/projectable.ts

@@ -10,6 +10,7 @@ import type { AnyQuery } from '@ultimat3/query';
 import { isQuery, queryName, sourceFor } from '@ultimat3/query';
 import { asCallerContext } from './caller-context';
 import type { McpExposure, ProjectablePrimitive } from './from-action';
+import { takeIdempotencyKeyArg, withIdempotencyKeyArg } from './idempotency-arg';
 import { toWireSchema } from './input-schema';
 import type { McpListParams } from './list-params';
 
@@ -40,16 +41,26 @@ export function asProjectable(listed: ListedPrimitive): ProjectablePrimitive {
 
 export function primitiveFromAction(target: AnyAction): ProjectablePrimitive {
   const exposure = exposureOf(target.mcp);
+  // Throws `X_ACTION_UNREGISTERED` on an unnamed action rather than projecting a tool called
+  // `''`: a nameless tool is unaddressable by the scope map, by `tools/call`, and by the author.
+  const name = actionName(target);
+  const wire = toWireSchema(target.input);
+  // `idempotent: true` is honoured on this surface exactly as over HTTP: the caller's key reaches
+  // `invoke`, which files it under the action, the caller and the key (`idempotencyKeyFor`).
+  const keyed = target.describe().idempotent;
   return {
-    // Throws `X_ACTION_UNREGISTERED` on an unnamed action rather than projecting a tool called
-    // `''`: a nameless tool is unaddressable by the scope map, by `tools/call`, and by the author.
-    name: actionName(target),
+    name,
     ...(exposure === undefined ? {} : { mcp: exposure }),
     ...(exposure?.description === undefined ? {} : { description: exposure.description }),
-    inputJsonSchema: toWireSchema(target.input),
+    inputJsonSchema: keyed ? withIdempotencyKeyArg(name, wire) : wire,
     mutates: true,
     // The actor rides in on the options: `invoke` swaps it inside the one execution path.
-    run: ({ input, actor }) => invoke(target, input, { surface: 'mcp', actor }),
+    run: keyed
+      ? ({ input: args, actor }) => {
+          const { input, idempotencyKey } = takeIdempotencyKeyArg(args);
+          return invoke(target, input, { surface: 'mcp', actor, idempotencyKey });
+        }
+      : ({ input, actor }) => invoke(target, input, { surface: 'mcp', actor }),
   };
 }