@ultimat3/mcp 2.0.0 → 3.0.0

package/CLAUDE.md

@@ -49,6 +49,28 @@ import. The CLI wires it.
   fails, every caller simply sees every tool.
 - Resolve order is visibility → scope → args → policy. Validating first leaks a schema;
   running the policy first decides a refusal from attacker-supplied input.
+- **A key's membership of a declared schema is `Object.hasOwn(properties, key)`, never
+  `properties[key] === undefined`.** The arguments of a `tools/call` are NAMED by the caller, and
+  `Object.prototype` supplies a value for `constructor`, `toString`, `hasOwnProperty` and
+  `__proto__` on every plain object — so the index read answered "declared" for four names no
+  schema declares, and `validate-args.ts` accepted them past an `additionalProperties: false` that
+  forbids them and then dropped them. Third instance of the class in the framework, after
+  `@ultimat3/i18n`'s catalog lookup and `@ultimat3/schema`'s `coerce`. Its twin: a validated key
+  lands on the result through `Object.defineProperty`, because `out[key] = v` for `__proto__` runs
+  the setter on `Object.prototype` and re-prototypes the record instead of adding a key.
+- **Anything a tool RETURNS is rendered totally.** `jsonResult` is handed an action's own return
+  value, and `JSON.stringify` answers `undefined` for a handler that returned nothing (a
+  `ContentBlock.text` that is not a string is an invalid frame) and THROWS on a bigint, a cycle or
+  a `toJSON` the value carries. Unreadable is an ordinary `isError` result, never an escape past
+  `server.ts`'s catch, which would report a bug in the tool for a fault in the rendering.
+  `query-limits.ts`' `rowBytes` holds the same line one layer earlier: a row the driver decoded
+  into a bigint costs `Infinity` and is cut by the byte ceiling, rather than raising inside the cap
+  that exists to protect the answer.
+- **A thrown value is read with `stringField` from `@ultimat3/core`, never `typeof e.code ===
+  'string'`.** `asFrameworkError` reads four fields off whatever an app's handler threw; each read
+  is a getter call, or a `Proxy` trap, inside the catch block that owes the caller a response — and
+  a probe that raises there leaves the JSON-RPC request with no answer at all, not even the
+  `-32603` the transport promises for a genuine bug.
 - A framework error rendered into a tool result is **byte-identical to
   `UltimateError.format()`** — one denial must not read one way over MCP and another in the
   terminal. `server.ts` renders it; the test pins it against `format()`, never a literal.

package/package.json

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

package/src/query-limits.ts

@@ -56,9 +56,21 @@ export function resolveQueryLimits(requested: unknown): QueryLimits {
 
 const encoder = new TextEncoder();
 
-/** Serialised size of one row, plus the separator it costs inside the JSON array. */
+/**
+ * Serialised size of one row, plus the separator it costs inside the JSON array.
+ *
+ * A row the driver decoded into something JSON cannot hold — a bigint from an `int8` column, a
+ * cycle — costs `Infinity`, which is not a fudge: the row cannot be returned to the agent at all,
+ * and the ceiling it blows is already the one whose answer ("select fewer columns") is the right
+ * one. Raising instead would take down the tool that owes the agent a reply, from inside the cap
+ * that exists to protect it.
+ */
 function rowBytes(row: readonly unknown[]): number {
-  return encoder.encode(JSON.stringify(row)).length + 1;
+  try {
+    return encoder.encode(JSON.stringify(row)).length + 1;
+  } catch {
+    return Number.POSITIVE_INFINITY;
+  }
 }
 
 /**

package/src/registry.ts

@@ -223,7 +223,25 @@ export function textResult(text: string, isError = false): McpToolResult {
   return isError ? { content, isError: true } : { content };
 }
 
-/** JSON payload as a text block — stable 2-space form so an agent can diff two calls. */
+/**
+ * JSON payload as a text block — stable 2-space form so an agent can diff two calls.
+ *
+ * TOTAL, because the value is an app's: `toolFromAction` hands an action's own return value
+ * straight here, and `JSON.stringify` answers `undefined` for a handler that returned nothing —
+ * a `text` that is not a string is an invalid MCP frame — and THROWS on a bigint, a cycle or a
+ * `toJSON` the value carries. A throw would leave the server's catch reporting a bug in the tool
+ * for a fault in the rendering, so the unreadable case is an ordinary `isError` result: the same
+ * three-line shape every other expected failure comes back as, and one an agent can act on.
+ */
 export function jsonResult(value: unknown): McpToolResult {
-  return textResult(JSON.stringify(value, null, 2));
+  let text: string | undefined;
+  try {
+    text = JSON.stringify(value, null, 2);
+  } catch {
+    return textResult(
+      'the tool ran, but its result is not JSON (a bigint, a cycle, or a toJSON that threw) — the tool has to return a JSON-serialisable value',
+      true,
+    );
+  }
+  return textResult(text ?? 'null');
 }

package/src/server.ts

@@ -3,6 +3,7 @@
 // and an already-resolved caller, and returns a response or `null` for a notification.
 // Both transports (http, stdio) and every test drive this one function.
 
+import { stringField } from '@ultimat3/core';
 import { formatIssues } from '@ultimat3/schema';
 import { auditToolCall, outcomeForCode } from './audit';
 import { McpScopeDeniedError } from './errors';
@@ -242,17 +243,21 @@ interface FrameworkError {
  * transport must stay independent of which package threw.
  */
 function asFrameworkError(error: unknown): FrameworkError | undefined {
-  if (typeof error !== 'object' || error === null) return undefined;
-  const e = error as { code?: unknown; title?: unknown; cause?: unknown; fix?: unknown };
-  if (typeof e.code !== 'string' || !e.code.startsWith('X_')) return undefined;
+  // `stringField` from `@ultimat3/core`, never `typeof e.code === 'string'`: the value is whatever
+  // an app's handler, its driver or its SDK threw, so each read is a getter call or a `Proxy`
+  // trap. This runs inside the catch block that owes the caller an answer, and a probe that
+  // raises here leaves the JSON-RPC request with no response at all — not even the `-32603` the
+  // header promises for a genuine bug.
+  const code = stringField(error, 'code');
+  if (code === undefined || !code.startsWith('X_')) return undefined;
   return {
-    code: e.code,
-    title: typeof e.title === 'string' ? e.title : '',
-    cause: typeof e.cause === 'string' ? e.cause : 'unknown',
+    code,
+    title: stringField(error, 'title') ?? '',
+    cause: stringField(error, 'cause') ?? 'unknown',
     // A substituted fix is still a fix an agent will act on, so it has to be runnable. `see docs`
-    // named no docs and no command; `e.code` is already narrowed to an `X_` string by the guard
+    // named no docs and no command; `code` is already narrowed to an `X_` string by the guard
     // above, so the substitute is the one command that explains exactly this code.
-    fix: typeof e.fix === 'string' ? e.fix : `x errors explain ${e.code}`,
+    fix: stringField(error, 'fix') ?? `x errors explain ${code}`,
   };
 }
 

package/src/validate-args.ts

@@ -78,29 +78,43 @@ function object(
   const out: Record<string, unknown> = {};
 
   for (const key of Object.keys(source)) {
-    if (properties[key] === undefined) {
+    // `Object.hasOwn`, never `properties[key] === undefined`: the second walks the prototype
+    // chain, so `constructor`, `toString` and `__proto__` read as DECLARED on every schema and an
+    // argument named after one was accepted past an `additionalProperties: false` that forbids it,
+    // then silently dropped. Same discriminator as the loop below, which always had it right.
+    if (!Object.hasOwn(properties, key)) {
       if (schema.additionalProperties === false) {
         issues.push({ path: join(path, key), message: 'unknown property' });
         continue;
       }
-      out[key] = source[key];
+      put(out, key, source[key]);
     }
   }
   for (const [key, child] of Object.entries(properties)) {
     const at = join(path, key);
     const present = Object.hasOwn(source, key) && source[key] !== undefined;
     if (!present) {
-      if (child.default !== undefined) out[key] = child.default;
+      if (child.default !== undefined) put(out, key, child.default);
       else if (schema.required?.includes(key) === true) {
         issues.push({ path: at, message: 'is required' });
       }
       continue;
     }
-    out[key] = walk(child, source[key], at, issues);
+    put(out, key, walk(child, source[key], at, issues));
   }
   return out;
 }
 
+/**
+ * One validated key onto the result. `out[key] = value` is not an assignment for exactly one
+ * name: `__proto__` runs `Object.prototype`'s setter and REPLACES the object's prototype instead
+ * of adding a key, so a caller-chosen argument name decides what the handler's `args.isAdmin`
+ * reads. `defineProperty` writes a plain own data property whatever the name is.
+ */
+function put(out: Record<string, unknown>, key: string, value: unknown): void {
+  Object.defineProperty(out, key, { value, writable: true, enumerable: true, configurable: true });
+}
+
 function array(schema: JsonSchema, input: unknown, path: string, issues: ArgIssue[]): unknown {
   if (!Array.isArray(input)) {
     issues.push({ path, message: 'must be an array' });