@nifrajs/mcp 1.13.0 → 2.0.0

package/README.md

@@ -0,0 +1,33 @@
+# @nifrajs/mcp
+
+Build transport-agnostic MCP servers and interactive MCP Apps for Nifra applications.
+
+```sh
+bun add @nifrajs/mcp
+```
+
+```ts
+import { createMcpServer, defineMcpTool } from "@nifrajs/mcp"
+
+const tools = [
+  defineMcpTool({
+    name: "health",
+    description: "Report service health",
+    handler: () => ({ text: "ok" }),
+  }),
+]
+
+const mcp = createMcpServer({ name: "orders", version: "1.0.0", tools })
+```
+
+Mount `mcp.fetch` at `POST /mcp`. The package also exposes the JSON-RPC protocol and Streamable HTTP
+layers directly, plus `defineMcpWidget` and the React adapter for tool results that render UI in MCP
+hosts.
+
+## For AI agents
+
+Start with [`LLM.md`](./LLM.md) — this package's contract card (the exports you call + its footguns),
+one cheap read instead of the whole corpus. For the wider framework: the repo's
+[`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
+[`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
+done-gate, or `nifra mcp` to give the agent live project tools.

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { bridgeScript, type McpAppBridge } from "./bridge.js";
 export { type McpHttpOptions, respondMcpHttp } from "./http.js";
 export * from "./protocol.js";
 export { type CreateMcpServerOptions, createMcpServer, type McpServer } from "./server.js";
+export type { InferOutput, StandardIssue, StandardResult, StandardSchemaV1, } from "./standard.js";
 export { type DefineMcpToolOptions, defineMcpTool, type McpToolHandlerResult, type McpUiIntent, } from "./tool.js";
 export { type DefineMcpWidgetOptions, defineMcpWidget, type McpWidget, uiResourceMeta, widgetDocument, } from "./widget.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,KAAK,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC/D,cAAc,eAAe,CAAA;AAC7B,OAAO,EAAE,KAAK,sBAAsB,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA;AAC1F,OAAO,EACL,KAAK,oBAAoB,EACzB,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,WAAW,GACjB,MAAM,WAAW,CAAA;AAClB,OAAO,EACL,KAAK,sBAAsB,EAC3B,eAAe,EACf,KAAK,SAAS,EACd,cAAc,EACd,cAAc,GACf,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,KAAK,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC/D,cAAc,eAAe,CAAA;AAC7B,OAAO,EAAE,KAAK,sBAAsB,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA;AAC1F,YAAY,EACV,WAAW,EACX,aAAa,EACb,cAAc,EACd,gBAAgB,GACjB,MAAM,eAAe,CAAA;AACtB,OAAO,EACL,KAAK,oBAAoB,EACzB,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,WAAW,GACjB,MAAM,WAAW,CAAA;AAClB,OAAO,EACL,KAAK,sBAAsB,EAC3B,eAAe,EACf,KAAK,SAAS,EACd,cAAc,EACd,cAAc,GACf,MAAM,aAAa,CAAA"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAqB,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAuB,cAAc,EAAE,MAAM,WAAW,CAAA;AAC/D,cAAc,eAAe,CAAA;AAC7B,OAAO,EAA+B,eAAe,EAAkB,MAAM,aAAa,CAAA;AAC1F,OAAO,EAEL,aAAa,GAGd,MAAM,WAAW,CAAA;AAClB,OAAO,EAEL,eAAe,EAEf,cAAc,EACd,cAAc,GACf,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAqB,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAuB,cAAc,EAAE,MAAM,WAAW,CAAA;AAC/D,cAAc,eAAe,CAAA;AAC7B,OAAO,EAA+B,eAAe,EAAkB,MAAM,aAAa,CAAA;AAO1F,OAAO,EAEL,aAAa,GAGd,MAAM,WAAW,CAAA;AAClB,OAAO,EAEL,eAAe,EAEf,cAAc,EACd,cAAc,GACf,MAAM,aAAa,CAAA"}

package/dist/standard.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The Standard Schema v1 interface (https://standardschema.dev), vendored as types + a tiny
+ * runtime so any compliant validator - nifra's `t`, zod, valibot, arktype, … - can type and
+ * validate tool arguments without coupling this package to a validator. The spec is MIT-licensed
+ * and explicitly designed to be copied; this package stays dependency-free.
+ */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        } | undefined;
+    };
+}
+export type StandardResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<StandardIssue>;
+};
+export interface StandardIssue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }> | undefined;
+}
+/** The validated (post-transform) type of a Standard Schema. */
+export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+/** Render issues as one agent-readable line per problem: `location: message`. */
+export declare function formatIssues(issues: ReadonlyArray<StandardIssue>): string;
+/**
+ * The wire JSON Schema of a Standard Schema, when it carries one. nifra's `t` schemas ARE
+ * JSON Schema (exposed as `.jsonSchema`), so tools authored with `t` advertise a full
+ * `inputSchema` for free. Schemas from other vendors return `undefined` - pass an explicit
+ * `inputSchema` alongside `input` for those.
+ */
+export declare function jsonSchemaOf(schema: StandardSchemaV1): Record<string, unknown> | undefined;
+//# sourceMappingURL=standard.d.ts.map

package/dist/standard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard.d.ts","sourceRoot":"","sources":["../src/standard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,gBAAgB,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK;IAC/D,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;QACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,cAAc,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAA;QAC/F,QAAQ,CAAC,KAAK,CAAC,EAAE;YAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;YAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;SAAE,GAAG,SAAS,CAAA;KAChF,CAAA;CACF;AAED,MAAM,MAAM,cAAc,CAAC,MAAM,IAC7B;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;CAAE,CAAA;AAErD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,WAAW,GAAG;QAAE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAA;KAAE,CAAC,GAAG,SAAS,CAAA;CACvF;AAED,gEAAgE;AAChE,MAAM,MAAM,WAAW,CAAC,MAAM,SAAS,gBAAgB,IAAI,WAAW,CACpE,MAAM,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,CAC7B,CAAC,QAAQ,CAAC,CAAA;AAEX,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,MAAM,CASzE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAK1F"}

package/dist/standard.js

@@ -0,0 +1,30 @@
+/**
+ * The Standard Schema v1 interface (https://standardschema.dev), vendored as types + a tiny
+ * runtime so any compliant validator - nifra's `t`, zod, valibot, arktype, … - can type and
+ * validate tool arguments without coupling this package to a validator. The spec is MIT-licensed
+ * and explicitly designed to be copied; this package stays dependency-free.
+ */
+/** Render issues as one agent-readable line per problem: `location: message`. */
+export function formatIssues(issues) {
+    return issues
+        .map((issue) => {
+        const path = (issue.path ?? [])
+            .map((seg) => String(typeof seg === "object" && seg !== null ? seg.key : seg))
+            .join(".");
+        return path === "" ? issue.message : `${path}: ${issue.message}`;
+    })
+        .join("; ");
+}
+/**
+ * The wire JSON Schema of a Standard Schema, when it carries one. nifra's `t` schemas ARE
+ * JSON Schema (exposed as `.jsonSchema`), so tools authored with `t` advertise a full
+ * `inputSchema` for free. Schemas from other vendors return `undefined` - pass an explicit
+ * `inputSchema` alongside `input` for those.
+ */
+export function jsonSchemaOf(schema) {
+    const candidate = schema.jsonSchema;
+    return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate)
+        ? candidate
+        : undefined;
+}
+//# sourceMappingURL=standard.js.map

package/dist/standard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard.js","sourceRoot":"","sources":["../src/standard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyBH,iFAAiF;AACjF,MAAM,UAAU,YAAY,CAAC,MAAoC;IAC/D,OAAO,MAAM;SACV,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACb,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;aAC5B,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;aAC7E,IAAI,CAAC,GAAG,CAAC,CAAA;QACZ,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAA;IAClE,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAA;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,MAAwB;IACnD,MAAM,SAAS,GAAI,MAAmC,CAAC,UAAU,CAAA;IACjE,OAAO,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;QACrF,CAAC,CAAE,SAAqC;QACxC,CAAC,CAAC,SAAS,CAAA;AACf,CAAC"}

package/dist/tool.d.ts

@@ -7,6 +7,7 @@
  * `tools/call` result, so the host knows to render the widget — see {@link ../protocol.ts}.
  */
 import type { McpContentBlock, McpTool, McpToolContext } from "./protocol.js";
+import type { InferOutput, StandardSchemaV1 } from "./standard.js";
 import type { McpWidget } from "./widget.js";
 /** The ergonomic result an MCP-tool handler may return (coerced to the protocol's {@link McpToolResult}). */
 export type McpToolHandlerResult = string | {
@@ -26,10 +27,23 @@ export type McpToolHandlerResult = string | {
  * union — pick a known tag or a custom one.
  */
 export type McpUiIntent = "table" | "list" | "cards" | "form" | "metric" | "detail" | "chart" | (string & {});
-export interface DefineMcpToolOptions {
+/** The default when no `input` schema is given: arguments arrive untyped and unvalidated. */
+type UntypedArgs = StandardSchemaV1<unknown, Record<string, unknown>>;
+export interface DefineMcpToolOptions<S extends StandardSchemaV1 = UntypedArgs> {
     readonly name: string;
     readonly description: string;
-    /** JSON Schema for the arguments. Defaults to an empty object schema. */
+    /**
+     * A Standard Schema for the arguments (nifra's `t`, zod, valibot, arktype, …). It validates every
+     * call before the handler runs - invalid arguments return an in-band `isError` result naming each
+     * issue, so the calling agent can correct and retry - and it types the handler's `args`. Schemas
+     * that carry a JSON Schema (nifra's `t` does) also become the advertised `inputSchema` for free.
+     */
+    readonly input?: S;
+    /**
+     * JSON Schema for the wire descriptor (`tools/list`). Defaults to `input`'s own JSON Schema when
+     * it exposes one, else an empty object schema. Pass explicitly when `input` comes from a vendor
+     * whose schemas carry no JSON Schema, so the agent still sees real parameter docs.
+     */
     readonly inputSchema?: Record<string, unknown>;
     /** Link a widget so the tool's result renders as interactive UI in MCP Apps hosts (iframe). */
     readonly widget?: McpWidget;
@@ -37,7 +51,8 @@ export interface DefineMcpToolOptions {
      * in `_meta.ui.intent`. Independent of `widget` — a tool can offer both (widget for MCP Apps hosts,
      * intent for generative builders). */
     readonly intent?: McpUiIntent;
-    readonly handler: (args: Record<string, unknown>, context: McpToolContext) => McpToolHandlerResult | Promise<McpToolHandlerResult>;
+    readonly handler: (args: InferOutput<S>, context: McpToolContext) => McpToolHandlerResult | Promise<McpToolHandlerResult>;
 }
-export declare function defineMcpTool(opts: DefineMcpToolOptions): McpTool;
+export declare function defineMcpTool<S extends StandardSchemaV1 = UntypedArgs>(opts: DefineMcpToolOptions<S>): McpTool;
+export {};
 //# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,EAAiB,MAAM,eAAe,CAAA;AAC5F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C,6GAA6G;AAC7G,MAAM,MAAM,oBAAoB,GAC5B,MAAM,GACN;IACE,yFAAyF;IACzF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,kDAAkD;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,eAAe,EAAE,CAAA;IAC7C,gFAAgF;IAChF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAC3B,CAAA;AAEL;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB,OAAO,GACP,MAAM,GACN,OAAO,GACP,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEjB,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9C,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;IAC3B;;0CAEsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,CAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,cAAc,KACpB,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;CAC1D;AAmCD,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CASjE"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,EAAiB,MAAM,eAAe,CAAA;AAC5F,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAElE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C,6GAA6G;AAC7G,MAAM,MAAM,oBAAoB,GAC5B,MAAM,GACN;IACE,yFAAyF;IACzF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,kDAAkD;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,eAAe,EAAE,CAAA;IAC7C,gFAAgF;IAChF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAC3B,CAAA;AAEL;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACnB,OAAO,GACP,MAAM,GACN,OAAO,GACP,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEjB,6FAA6F;AAC7F,KAAK,WAAW,GAAG,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAErE,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,gBAAgB,GAAG,WAAW;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAClB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9C,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;IAC3B;;0CAEsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,CAChB,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EACpB,OAAO,EAAE,cAAc,KACpB,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;CAC1D;AAgCD,wBAAgB,aAAa,CAAC,CAAC,SAAS,gBAAgB,GAAG,WAAW,EACpE,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC5B,OAAO,CA2BT"}

package/dist/tool.js

@@ -6,6 +6,7 @@
  * `widget` is passed, the tool advertises it via `_meta.ui.resourceUri` on both `tools/list` and each
  * `tools/call` result, so the host knows to render the widget — see {@link ../protocol.ts}.
  */
+import { formatIssues, jsonSchemaOf } from "./standard.js";
 /** Build a tool's descriptor `_meta` from its widget link and/or render intent (both under `ui`). */
 function toolMeta(widget, intent) {
     if (widget === undefined && intent === undefined)
@@ -15,11 +16,7 @@ function toolMeta(widget, intent) {
         ui.resourceUri = widget.uri;
     if (intent !== undefined)
         ui.intent = intent;
-    const meta = { ui };
-    // Deprecated-flat alias for hosts that still read it.
-    if (widget !== undefined)
-        meta["ui/resourceUri"] = widget.uri;
-    return meta;
+    return { ui };
 }
 const EMPTY_OBJECT_SCHEMA = {
     type: "object",
@@ -42,12 +39,29 @@ function coerce(result) {
 }
 export function defineMcpTool(opts) {
     const meta = toolMeta(opts.widget, opts.intent);
+    const input = opts.input;
     return {
         name: opts.name,
         description: opts.description,
-        inputSchema: opts.inputSchema ?? EMPTY_OBJECT_SCHEMA,
+        inputSchema: opts.inputSchema ??
+            (input !== undefined ? jsonSchemaOf(input) : undefined) ??
+            EMPTY_OBJECT_SCHEMA,
         ...(meta !== undefined ? { _meta: meta } : {}),
-        handler: async (args, context) => coerce(await opts.handler(args, context)),
+        handler: async (args, context) => {
+            let validated = args;
+            if (input !== undefined) {
+                const result = await input["~standard"].validate(args);
+                if (result.issues !== undefined) {
+                    // In-band failure (not a protocol error): the agent reads the issues and retries corrected.
+                    return {
+                        content: [{ type: "text", text: `Invalid arguments: ${formatIssues(result.issues)}` }],
+                        isError: true,
+                    };
+                }
+                validated = result.value;
+            }
+            return coerce(await opts.handler(validated, context));
+        },
     };
 }
 //# sourceMappingURL=tool.js.map

package/dist/tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoDH,qGAAqG;AACrG,SAAS,QAAQ,CAAC,MAAkB,EAAE,MAAe;IACnD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IAClE,MAAM,EAAE,GAA4B,EAAE,CAAA;IACtC,IAAI,MAAM,KAAK,SAAS;QAAE,EAAE,CAAC,WAAW,GAAG,MAAM,CAAC,GAAG,CAAA;IACrD,IAAI,MAAM,KAAK,SAAS;QAAE,EAAE,CAAC,MAAM,GAAG,MAAM,CAAA;IAC5C,MAAM,IAAI,GAA4B,EAAE,EAAE,EAAE,CAAA;IAC5C,sDAAsD;IACtD,IAAI,MAAM,KAAK,SAAS;QAAE,IAAI,CAAC,gBAAgB,CAAC,GAAG,MAAM,CAAC,GAAG,CAAA;IAC7D,OAAO,IAAI,CAAA;AACb,CAAC;AAED,MAAM,mBAAmB,GAA4B;IACnD,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE,EAAE;IACd,oBAAoB,EAAE,KAAK;CAC5B,CAAA;AAED,SAAS,MAAM,CAAC,MAA4B;IAC1C,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAA;IAC7C,MAAM,OAAO,GACX,MAAM,CAAC,OAAO;QACd,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IACjF,OAAO;QACL,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,MAAM,CAAC,iBAAiB,KAAK,SAAS;YACxC,CAAC,CAAC,EAAE,iBAAiB,EAAE,MAAM,CAAC,iBAAiB,EAAE;YACjD,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtD,CAAA;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAA0B;IACtD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;IAC/C,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,mBAAmB;QACpD,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;KAC5E,CAAA;AACH,CAAC"}
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}

package/dist/widget.d.ts

@@ -27,8 +27,7 @@ export interface DefineMcpWidgetOptions {
      * `mcpApp.callTool(...)`. The bridge global is defined before this runs. */
     readonly html: string;
 }
-/** The MCP Apps `_meta.ui.resourceUri` link, emitted nested (current spec) AND flat (the deprecated
- * `ui/resourceUri`, still read by some hosts) so a tool renders across the transition. */
+/** The MCP Apps `_meta.ui.resourceUri` link. */
 export declare function uiResourceMeta(uri: string): Record<string, unknown>;
 /** A widget: the resource to register on the server, its `ui://` URI, and the `_meta` link for its tool. */
 export interface McpWidget {

package/dist/widget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"widget.d.ts","sourceRoot":"","sources":["../src/widget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,KAAK,WAAW,EAAW,MAAM,eAAe,CAAA;AAEzD,MAAM,WAAW,sBAAsB;IACrC,yFAAyF;IACzF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,sGAAsG;IACtG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB;gFAC4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED;0FAC0F;AAC1F,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEnE;AAED,4GAA4G;AAC5G,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAA;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACvC;AAMD;4BAC4B;AAC5B,wBAAgB,cAAc,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAgBnE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,SAAS,CAavE"}
+{"version":3,"file":"widget.d.ts","sourceRoot":"","sources":["../src/widget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,KAAK,WAAW,EAAW,MAAM,eAAe,CAAA;AAEzD,MAAM,WAAW,sBAAsB;IACrC,yFAAyF;IACzF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,sGAAsG;IACtG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB;gFAC4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,gDAAgD;AAChD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEnE;AAED,4GAA4G;AAC5G,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAA;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACvC;AAMD;4BAC4B;AAC5B,wBAAgB,cAAc,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAgBnE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,SAAS,CAavE"}

package/dist/widget.js

@@ -14,10 +14,9 @@
  */
 import { bridgeScript } from "./bridge.js";
 import { UI_MIME } from "./protocol.js";
-/** The MCP Apps `_meta.ui.resourceUri` link, emitted nested (current spec) AND flat (the deprecated
- * `ui/resourceUri`, still read by some hosts) so a tool renders across the transition. */
+/** The MCP Apps `_meta.ui.resourceUri` link. */
 export function uiResourceMeta(uri) {
-    return { ui: { resourceUri: uri }, "ui/resourceUri": uri };
+    return { ui: { resourceUri: uri } };
 }
 function escapeHtml(text) {
     return text.replace(/[&<>]/g, (c) => (c === "&" ? "&amp;" : c === "<" ? "&lt;" : "&gt;"));

package/dist/widget.js.map

@@ -1 +1 @@
-{"version":3,"file":"widget.js","sourceRoot":"","sources":["../src/widget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAoB,OAAO,EAAE,MAAM,eAAe,CAAA;AAiBzD;0FAC0F;AAC1F,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,EAAE,gBAAgB,EAAE,GAAG,EAAE,CAAA;AAC5D,CAAC;AASD,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAA;AAC3F,CAAC;AAED;4BAC4B;AAC5B,MAAM,UAAU,cAAc,CAAC,IAA4B;IACzD,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,CAAA;IACjD,OAAO;;;;;SAKA,KAAK;UACJ,YAAY,EAAE;EACtB,IAAI,CAAC,IAAI,IAAI,EAAE;;;EAGf,IAAI,CAAC,IAAI;;;CAGV,CAAA;AACD,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAA4B;IAC1D,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,wDAAwD,IAAI,CAAC,GAAG,IAAI,CAAC,CAAA;IACvF,CAAC;IACD,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,CAAA;IACjC,MAAM,QAAQ,GAAgB;QAC5B,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,QAAQ,EAAE,OAAO;QACjB,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;KAC/D,CAAA;IACD,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAA;AACpE,CAAC"}
+{"version":3,"file":"widget.js","sourceRoot":"","sources":["../src/widget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAoB,OAAO,EAAE,MAAM,eAAe,CAAA;AAiBzD,gDAAgD;AAChD,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,EAAE,CAAA;AACrC,CAAC;AASD,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAA;AAC3F,CAAC;AAED;4BAC4B;AAC5B,MAAM,UAAU,cAAc,CAAC,IAA4B;IACzD,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,CAAA;IACjD,OAAO;;;;;SAKA,KAAK;UACJ,YAAY,EAAE;EACtB,IAAI,CAAC,IAAI,IAAI,EAAE;;;EAGf,IAAI,CAAC,IAAI;;;CAGV,CAAA;AACD,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAA4B;IAC1D,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,wDAAwD,IAAI,CAAC,GAAG,IAAI,CAAC,CAAA;IACvF,CAAC;IACD,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,CAAA;IACjC,MAAM,QAAQ,GAAgB;QAC5B,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,QAAQ,EAAE,OAAO;QACjB,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;KAC/D,CAAA;IACD,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAA;AACpE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/mcp",
-  "version": "1.13.0",
+  "version": "2.0.0",
   "description": "Build MCP servers — and MCP Apps (interactive `ui://` widgets, SEP-1865) — for a nifra app. The transport-agnostic JSON-RPC core (also used by `@nifrajs/cli`'s dev MCP), a Streamable-HTTP handler you mount at `POST /mcp`, and `defineMcpWidget`/`defineMcpTool` for tool results that render real UI in MCP hosts.",
   "keywords": [
     "bun",
@@ -53,6 +53,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "devDependencies": {
+    "react": "19.2.7"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nifrajs/nifra.git",

package/src/index.ts

@@ -13,6 +13,12 @@ export { bridgeScript, type McpAppBridge } from "./bridge.ts"
 export { type McpHttpOptions, respondMcpHttp } from "./http.ts"
 export * from "./protocol.ts"
 export { type CreateMcpServerOptions, createMcpServer, type McpServer } from "./server.ts"
+export type {
+  InferOutput,
+  StandardIssue,
+  StandardResult,
+  StandardSchemaV1,
+} from "./standard.ts"
 export {
   type DefineMcpToolOptions,
   defineMcpTool,

package/src/standard.ts

@@ -0,0 +1,54 @@
+/**
+ * The Standard Schema v1 interface (https://standardschema.dev), vendored as types + a tiny
+ * runtime so any compliant validator - nifra's `t`, zod, valibot, arktype, … - can type and
+ * validate tool arguments without coupling this package to a validator. The spec is MIT-licensed
+ * and explicitly designed to be copied; this package stays dependency-free.
+ */
+
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly "~standard": {
+    readonly version: 1
+    readonly vendor: string
+    readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>
+    readonly types?: { readonly input: Input; readonly output: Output } | undefined
+  }
+}
+
+export type StandardResult<Output> =
+  | { readonly value: Output; readonly issues?: undefined }
+  | { readonly issues: ReadonlyArray<StandardIssue> }
+
+export interface StandardIssue {
+  readonly message: string
+  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }> | undefined
+}
+
+/** The validated (post-transform) type of a Standard Schema. */
+export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+  Schema["~standard"]["types"]
+>["output"]
+
+/** Render issues as one agent-readable line per problem: `location: message`. */
+export function formatIssues(issues: ReadonlyArray<StandardIssue>): string {
+  return issues
+    .map((issue) => {
+      const path = (issue.path ?? [])
+        .map((seg) => String(typeof seg === "object" && seg !== null ? seg.key : seg))
+        .join(".")
+      return path === "" ? issue.message : `${path}: ${issue.message}`
+    })
+    .join("; ")
+}
+
+/**
+ * The wire JSON Schema of a Standard Schema, when it carries one. nifra's `t` schemas ARE
+ * JSON Schema (exposed as `.jsonSchema`), so tools authored with `t` advertise a full
+ * `inputSchema` for free. Schemas from other vendors return `undefined` - pass an explicit
+ * `inputSchema` alongside `input` for those.
+ */
+export function jsonSchemaOf(schema: StandardSchemaV1): Record<string, unknown> | undefined {
+  const candidate = (schema as { jsonSchema?: unknown }).jsonSchema
+  return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate)
+    ? (candidate as Record<string, unknown>)
+    : undefined
+}

package/src/tool.ts

@@ -8,6 +8,8 @@
  */
 
 import type { McpContentBlock, McpTool, McpToolContext, McpToolResult } from "./protocol.ts"
+import type { InferOutput, StandardSchemaV1 } from "./standard.ts"
+import { formatIssues, jsonSchemaOf } from "./standard.ts"
 import type { McpWidget } from "./widget.ts"
 
 /** The ergonomic result an MCP-tool handler may return (coerced to the protocol's {@link McpToolResult}). */
@@ -40,10 +42,24 @@ export type McpUiIntent =
   | "chart"
   | (string & {})
 
-export interface DefineMcpToolOptions {
+/** The default when no `input` schema is given: arguments arrive untyped and unvalidated. */
+type UntypedArgs = StandardSchemaV1<unknown, Record<string, unknown>>
+
+export interface DefineMcpToolOptions<S extends StandardSchemaV1 = UntypedArgs> {
   readonly name: string
   readonly description: string
-  /** JSON Schema for the arguments. Defaults to an empty object schema. */
+  /**
+   * A Standard Schema for the arguments (nifra's `t`, zod, valibot, arktype, …). It validates every
+   * call before the handler runs - invalid arguments return an in-band `isError` result naming each
+   * issue, so the calling agent can correct and retry - and it types the handler's `args`. Schemas
+   * that carry a JSON Schema (nifra's `t` does) also become the advertised `inputSchema` for free.
+   */
+  readonly input?: S
+  /**
+   * JSON Schema for the wire descriptor (`tools/list`). Defaults to `input`'s own JSON Schema when
+   * it exposes one, else an empty object schema. Pass explicitly when `input` comes from a vendor
+   * whose schemas carry no JSON Schema, so the agent still sees real parameter docs.
+   */
   readonly inputSchema?: Record<string, unknown>
   /** Link a widget so the tool's result renders as interactive UI in MCP Apps hosts (iframe). */
   readonly widget?: McpWidget
@@ -52,7 +68,7 @@ export interface DefineMcpToolOptions {
    * intent for generative builders). */
   readonly intent?: McpUiIntent
   readonly handler: (
-    args: Record<string, unknown>,
+    args: InferOutput<S>,
     context: McpToolContext,
   ) => McpToolHandlerResult | Promise<McpToolHandlerResult>
 }
@@ -63,10 +79,7 @@ function toolMeta(widget?: McpWidget, intent?: string): Record<string, unknown>
   const ui: Record<string, unknown> = {}
   if (widget !== undefined) ui.resourceUri = widget.uri
   if (intent !== undefined) ui.intent = intent
-  const meta: Record<string, unknown> = { ui }
-  // Deprecated-flat alias for hosts that still read it.
-  if (widget !== undefined) meta["ui/resourceUri"] = widget.uri
-  return meta
+  return { ui }
 }
 
 const EMPTY_OBJECT_SCHEMA: Record<string, unknown> = {
@@ -90,13 +103,33 @@ function coerce(result: McpToolHandlerResult): string | McpToolResult {
   }
 }
 
-export function defineMcpTool(opts: DefineMcpToolOptions): McpTool {
+export function defineMcpTool<S extends StandardSchemaV1 = UntypedArgs>(
+  opts: DefineMcpToolOptions<S>,
+): McpTool {
   const meta = toolMeta(opts.widget, opts.intent)
+  const input = opts.input
   return {
     name: opts.name,
     description: opts.description,
-    inputSchema: opts.inputSchema ?? EMPTY_OBJECT_SCHEMA,
+    inputSchema:
+      opts.inputSchema ??
+      (input !== undefined ? jsonSchemaOf(input) : undefined) ??
+      EMPTY_OBJECT_SCHEMA,
     ...(meta !== undefined ? { _meta: meta } : {}),
-    handler: async (args, context) => coerce(await opts.handler(args, context)),
+    handler: async (args, context) => {
+      let validated = args as InferOutput<S>
+      if (input !== undefined) {
+        const result = await input["~standard"].validate(args)
+        if (result.issues !== undefined) {
+          // In-band failure (not a protocol error): the agent reads the issues and retries corrected.
+          return {
+            content: [{ type: "text", text: `Invalid arguments: ${formatIssues(result.issues)}` }],
+            isError: true,
+          }
+        }
+        validated = result.value as InferOutput<S>
+      }
+      return coerce(await opts.handler(validated, context))
+    },
   }
 }

package/src/widget.ts

@@ -31,10 +31,9 @@ export interface DefineMcpWidgetOptions {
   readonly html: string
 }
 
-/** The MCP Apps `_meta.ui.resourceUri` link, emitted nested (current spec) AND flat (the deprecated
- * `ui/resourceUri`, still read by some hosts) so a tool renders across the transition. */
+/** The MCP Apps `_meta.ui.resourceUri` link. */
 export function uiResourceMeta(uri: string): Record<string, unknown> {
-  return { ui: { resourceUri: uri }, "ui/resourceUri": uri }
+  return { ui: { resourceUri: uri } }
 }
 
 /** A widget: the resource to register on the server, its `ui://` URI, and the `_meta` link for its tool. */