@ultimat3/mcp 23.0.0 → 25.0.0

package/src/wire.ts

@@ -6,6 +6,7 @@
 // Reference: https://modelcontextprotocol.io/specification (2025-06-18).
 
 import { frameworkVersion } from '@ultimat3/core';
+import type { WireJsonSchema } from '@ultimat3/schema';
 
 /** MCP protocol version advertised on `initialize`. */
 export const MCP_PROTOCOL_VERSION = '2025-06-18';
@@ -62,47 +63,10 @@ export const INVALID_PARAMS = -32602;
 export const INTERNAL_ERROR = -32603;
 
 /**
- * The JSON Schema subset the framework emits and `validate-args.ts` enforces. Narrow on
- * purpose: a tool schema an agent cannot fully understand is a tool it will call wrong.
+ * The JSON Schema subset a tool publishes and `validate-args.ts` enforces — `@ultimat3/schema`'s
+ * `WireJsonSchema`, declared there so `@ultimat3/action`'s `.tool()` speaks the same one.
  */
-export interface JsonSchema {
-  readonly type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'null';
-  readonly title?: string;
-  readonly description?: string;
-  readonly properties?: Readonly<Record<string, JsonSchema>>;
-  readonly required?: readonly string[];
-  readonly additionalProperties?: boolean;
-  readonly items?: JsonSchema;
-  readonly enum?: readonly (string | number | boolean | null)[];
-  readonly const?: string | number | boolean | null;
-  readonly default?: unknown;
-  /**
-   * NOT in the subset, and deliberately absent: `format` NAMES a rule whose meaning lives in
-   * `@ultimat3/schema` (`uuid`, `email`, `iana-time-zone`, `bcp47-locale`), and this package
-   * cannot enforce it without a second definition of each one — which would drift from the parse
-   * the action itself runs and refuse values that surface accepts. So it is dropped by
-   * `input-schema.ts` rather than published unchecked: an agent told `format: 'uuid'` by a server
-   * that accepted `"not-a-uuid"` obeyed a rule nothing checked. `pattern` below is the opposite
-   * case — the rule travels WITH the schema as a source string, so it is enforceable and is kept.
-   *
-   * `readonly format?: never;` states it in the type: a narrow() that starts copying `format`
-   * again fails to compile rather than shipping a silent pass.
-   */
-  readonly format?: never;
-  readonly minimum?: number;
-  readonly maximum?: number;
-  readonly minLength?: number;
-  readonly maxLength?: number;
-  /**
-   * A `RegExp.source` string, JSON Schema semantics (a partial match unless it anchors itself).
-   * In the subset because `validate-args.ts` enforces it: without it `tools/list` published
-   * `{minLength,maxLength}` for a field whose OpenAPI component carried the pattern, so an HTTP
-   * client and an MCP agent held different contracts for one declaration and the agent's only
-   * way to learn the format was `X_INPUT_INVALID` from the action's own parse.
-   */
-  readonly pattern?: string;
-  readonly anyOf?: readonly JsonSchema[];
-}
+export type JsonSchema = WireJsonSchema;
 
 /** An empty-object schema — the honest shape for a no-argument tool. */
 export const NO_ARGS: JsonSchema = { type: 'object', properties: {}, additionalProperties: false };
@@ -149,3 +113,20 @@ export function paramsOf(req: JsonRpcRequest): Record<string, unknown> | null {
   if (typeof req.params !== 'object' || req.params === null) return null;
   return req.params as Record<string, unknown>;
 }
+
+/**
+ * Which wire one message arrived on, so a refusal can name the unit THAT transport counts in.
+ * `handle` is transport-independent and stays so — this is a hint for the wording of one fix, never
+ * a branch in dispatch. HTTP carries its mounted path because `mcpHttpRoute({ path })` is a knob:
+ * a batch refusal that told every client to retry `POST /mcp` was wrong for an app mounted at
+ * `/app-mcp`, which is how this came to be threaded rather than spelled.
+ */
+export type McpWire =
+  | { readonly transport: 'http'; readonly path: string }
+  | { readonly transport: 'stdio' };
+
+/** The unit a transport counts one request in — or the neutral word when no wire said. */
+export const messageUnitOf = (wire: McpWire | undefined): string => {
+  if (wire === undefined) return 'message';
+  return wire.transport === 'http' ? `POST ${wire.path}` : 'line';
+};

package/src/input-schema.ts

@@ -1,140 +0,0 @@
-// A Standard Schema (`t.object({...})`, Zod, Valibot) -> the JSON Schema subset the wire speaks.
-//
-// Two `JsonSchema` types exist on purpose. `@ultimat3/schema` emits the full draft-07 vocabulary;
-// `wire.ts` declares the narrow subset `validate-args.ts` can actually ENFORCE. Handing an agent a
-// keyword the server ignores is worse than omitting it — the agent obeys a rule nothing checks and
-// gets a silent pass. So this is a real projection, not a cast: a keyword outside the subset is
-// dropped here, and `tools/list` publishes only what the resolver will hold a call to.
-//
-// `format` is the keyword that rule is easiest to get wrong on: it is expressive, and it is a NAME
-// whose meaning lives in `@ultimat3/schema` — enforcing it here would be a second definition of
-// `uuid`/`email`/`iana-time-zone` that can only drift from the parse the action itself runs. So it
-// is dropped, and `wire.ts` types it `never` so re-adding it does not compile. `pattern` is kept
-// for the mirror-image reason: the rule travels with the schema, so this server can hold a call
-// to it. A tool needing a format enforced declares a `pattern` beside it.
-
-import type { JsonSchema as RichJsonSchema } from '@ultimat3/schema';
-import { toMcpInputSchema } from '@ultimat3/schema';
-import type { JsonSchema } from './wire';
-
-/** Introspect any Standard Schema and narrow the result to the wire subset. */
-export function toWireSchema(schema: unknown): JsonSchema {
-  return narrow(toMcpInputSchema(schema));
-}
-
-function narrow(source: RichJsonSchema): JsonSchema {
-  // exactOptionalPropertyTypes: every field is attached only when it is present, never as
-  // an explicit `undefined` — `tools/list` serialises this object verbatim.
-  return {
-    ...(source.type === undefined ? {} : { type: source.type }),
-    ...(source.title === undefined ? {} : { title: source.title }),
-    ...(source.description === undefined ? {} : { description: source.description }),
-    ...(source.properties === undefined ? {} : { properties: narrowProperties(source.properties) }),
-    ...(source.required === undefined ? {} : { required: source.required }),
-    ...narrowAdditional(source.additionalProperties),
-    ...(source.items === undefined ? {} : { items: narrow(source.items) }),
-    ...(source.enum === undefined ? {} : { enum: source.enum }),
-    ...(source.const === undefined ? {} : { const: source.const }),
-    ...(source.default === undefined ? {} : { default: source.default }),
-    ...(source.minimum === undefined ? {} : { minimum: source.minimum }),
-    ...(source.maximum === undefined ? {} : { maximum: source.maximum }),
-    ...(source.minLength === undefined ? {} : { minLength: source.minLength }),
-    ...(source.maxLength === undefined ? {} : { maxLength: source.maxLength }),
-    ...(source.pattern === undefined ? {} : { pattern: source.pattern }),
-    ...(source.anyOf === undefined ? {} : { anyOf: source.anyOf.map(narrow) }),
-  };
-}
-
-function narrowProperties(
-  properties: Readonly<Record<string, RichJsonSchema>>,
-): Readonly<Record<string, JsonSchema>> {
-  const out: Record<string, JsonSchema> = {};
-  for (const [key, child] of Object.entries(properties)) {
-    // `out[key] = …` is not an assignment for exactly one name — `__proto__` runs
-    // `Object.prototype`'s setter and RE-PROTOTYPES this record instead of adding a key, so a
-    // field an author declared disappears from `tools/list` and from what `validate-args.ts`
-    // reads back. The twin of `validate-args.ts`'s `put`, on the schema side.
-    Object.defineProperty(out, key, {
-      value: narrow(child),
-      writable: true,
-      enumerable: true,
-      configurable: true,
-    });
-  }
-  return out;
-}
-
-/**
- * A record schema says "extra keys, shaped like this". The wire subset can only say yes or no,
- * and `validate-args.ts` reads `false` as "reject unknown keys" — so an unrepresentable value
- * schema becomes `true` (permit) rather than a rejection the agent was never warned about.
- */
-function narrowAdditional(value: boolean | RichJsonSchema | undefined): {
-  readonly additionalProperties?: boolean;
-} {
-  if (value === undefined) return {};
-  return { additionalProperties: typeof value === 'boolean' ? value : true };
-}
-
-/**
- * A Standard Schema → the `outputSchema` a tool publishes, or `undefined` when its root is not an
- * object (MCP's `structuredContent` is one) or it cannot be introspected.
- *
- * STRUCTURE ONLY — type, properties, required, items, enum, const, anyOf, title, description. A
- * client validates `structuredContent` against this document and refuses the call on a miss, so
- * every keyword here is a promise about a value the server produced: a bound, a pattern or
- * `additionalProperties: false` on a query's rows (read from the database, never re-parsed) is a
- * promise nothing enforces on the way out. Fewer constraints is the honest projection of an output.
- */
-export function toOutputSchema(schema: unknown): JsonSchema | undefined {
-  let rich: RichJsonSchema;
-  try {
-    rich = toMcpInputSchema(schema);
-  } catch {
-    return undefined;
-  }
-  if (rich.type !== 'object') return undefined;
-  return shape(rich);
-}
-
-/** `{ rows: [<row>] }` — a query's answer as `structuredContent`. `undefined` when no row schema. */
-export function toRowsOutputSchema(rows: unknown): JsonSchema | undefined {
-  if (rows === undefined) return undefined;
-  const row = toOutputSchema(rows);
-  if (row === undefined) return undefined;
-  return {
-    type: 'object',
-    properties: { rows: { type: 'array', items: row } },
-    required: ['rows'],
-  };
-}
-
-function shape(source: RichJsonSchema): JsonSchema {
-  return {
-    ...(source.type === undefined ? {} : { type: source.type }),
-    ...(source.title === undefined ? {} : { title: source.title }),
-    ...(source.description === undefined ? {} : { description: source.description }),
-    ...(source.properties === undefined ? {} : { properties: shapeProperties(source.properties) }),
-    ...(source.required === undefined ? {} : { required: source.required }),
-    ...(source.items === undefined ? {} : { items: shape(source.items) }),
-    ...(source.enum === undefined ? {} : { enum: source.enum }),
-    ...(source.const === undefined ? {} : { const: source.const }),
-    ...(source.anyOf === undefined ? {} : { anyOf: source.anyOf.map(shape) }),
-  };
-}
-
-function shapeProperties(
-  properties: Readonly<Record<string, RichJsonSchema>>,
-): Readonly<Record<string, JsonSchema>> {
-  const out: Record<string, JsonSchema> = {};
-  for (const [key, child] of Object.entries(properties)) {
-    // `narrowProperties`' reason: `out['__proto__'] = …` re-prototypes instead of adding a key.
-    Object.defineProperty(out, key, {
-      value: shape(child),
-      writable: true,
-      enumerable: true,
-      configurable: true,
-    });
-  }
-  return out;
-}