@mcp-native/a2ui 0.0.1 → 0.0.3

package/README.md

@@ -1,5 +1,103 @@
+<div align="center">
+
 # @mcp-native/a2ui
 
-Part of MCP Native — a native UI runtime for Model Context Protocol applications.
+### Strict parsing for declarative MCP Native surfaces
+
+[![npm](https://img.shields.io/npm/v/@mcp-native/a2ui)](https://www.npmjs.com/package/@mcp-native/a2ui)
+[![downloads](https://img.shields.io/npm/dm/@mcp-native/a2ui)](https://www.npmjs.com/package/@mcp-native/a2ui)
+[![license](https://img.shields.io/npm/l/@mcp-native/a2ui)](https://github.com/pablospaniard/mcp-native/blob/main/LICENSE)
+
+[GitHub](https://github.com/pablospaniard/mcp-native) · [Architecture](https://github.com/pablospaniard/mcp-native/blob/main/docs/RFC-0001-architecture.md) · [Security](https://github.com/pablospaniard/mcp-native/blob/main/SECURITY.md)
+
+</div>
+
+> **Experimental:** this package implements MCP Native's deliberately small `0.1` proof-of-concept surface. It is not a claim of complete A2UI specification compatibility.
+
+`@mcp-native/a2ui` parses untrusted JSON or JavaScript values into a validated, typed surface before a host renders anything. Unknown versions, node types, action types, and invalid JSON values fail closed with an `A2uiParseError`.
+
+## Install
+
+```bash
+npm install @mcp-native/a2ui
+```
+
+`@mcp-native/core` is installed as a dependency. The package is ESM-only and includes TypeScript declarations.
+
+## Quick start
+
+```ts
+import { parseA2uiSurface } from "@mcp-native/a2ui";
+
+const surface = parseA2uiSurface({
+  version: "0.1",
+  root: {
+    id: "welcome",
+    type: "container",
+    children: [
+      { id: "title", type: "text", text: "Welcome" },
+      {
+        id: "name",
+        type: "text-input",
+        label: "Display name",
+        binding: "profile.displayName",
+      },
+      {
+        id: "save",
+        type: "button",
+        label: "Save",
+        action: {
+          type: "tool",
+          name: "save_profile",
+          arguments: { source: "onboarding" },
+        },
+      },
+    ],
+  },
+});
+```
+
+The parser also accepts a JSON string:
+
+```ts
+const surface = parseA2uiSurface(
+  '{"version":"0.1","root":{"id":"title","type":"text","text":"Hello"}}',
+);
+```
+
+## Supported surface
+
+| Node         | Required fields         | Purpose                                                |
+| ------------ | ----------------------- | ------------------------------------------------------ |
+| `container`  | `id`, `children`        | Groups nested surface nodes.                           |
+| `text`       | `id`, `text`            | Declares trusted text content.                         |
+| `button`     | `id`, `label`, `action` | Declares a tool action for host-controlled dispatch.   |
+| `text-input` | `id`, `label`           | Declares an input with optional `value` and `binding`. |
+
+The only supported action is `{ type: "tool", name, arguments? }`. Arguments must contain JSON-safe values.
+
+## Public API
+
+| Export                    | Purpose                                              |
+| ------------------------- | ---------------------------------------------------- |
+| `parseA2uiSurface`        | Validates input and returns a typed `A2uiSurface`.   |
+| `A2uiParseError`          | Error thrown for malformed or unsupported input.     |
+| `A2UI_VERSION`            | Current proof-of-concept wire version, `"0.1"`.      |
+| `A2uiSurface`, `A2uiNode` | Validated surface and node unions.                   |
+| Node interfaces           | Typed container, text, button, and text-input nodes. |
+
+## Security behavior
+
+- Input is treated as untrusted at the parser boundary.
+- Unknown surface versions, nodes, and actions are rejected.
+- Tool arguments are recursively constrained to JSON values.
+- Parsing never resolves components or executes server-provided code.
+- Successful parsing does not grant device capabilities or permission to call a tool; the host still owns those decisions.
+
+## Next layer
+
+Use [`@mcp-native/react-native`](https://www.npmjs.com/package/@mcp-native/react-native) to convert a validated surface into a trusted native render plan, or install [`mcp-native`](https://www.npmjs.com/package/mcp-native) for the complete public API.
+
+## License
 
-Early development.
+[MIT](https://github.com/pablospaniard/mcp-native/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import type { ToolAction } from "@mcp-native/core";
+export declare const A2UI_VERSION: "0.1";
+interface A2uiNodeBase {
+    readonly id: string;
+}
+export interface A2uiContainerNode extends A2uiNodeBase {
+    readonly type: "container";
+    readonly children: readonly A2uiNode[];
+}
+export interface A2uiTextNode extends A2uiNodeBase {
+    readonly type: "text";
+    readonly text: string;
+}
+export interface A2uiButtonNode extends A2uiNodeBase {
+    readonly type: "button";
+    readonly label: string;
+    readonly action: ToolAction;
+}
+export interface A2uiTextInputNode extends A2uiNodeBase {
+    readonly type: "text-input";
+    readonly label: string;
+    readonly value?: string;
+    readonly binding?: string;
+}
+export type A2uiNode = A2uiButtonNode | A2uiContainerNode | A2uiTextInputNode | A2uiTextNode;
+export interface A2uiSurface {
+    readonly version: typeof A2UI_VERSION;
+    readonly root: A2uiNode;
+}
+export declare class A2uiParseError extends Error {
+    constructor(message: string);
+}
+export declare function parseA2uiSurface(input: string | unknown): A2uiSurface;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAyB,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE1E,eAAO,MAAM,YAAY,EAAG,KAAc,CAAC;AAE3C,UAAU,YAAY;IACpB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAe,SAAQ,YAAY;IAClD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,YAAY,CAAC;AAE7F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,YAAY,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,WAAW,CAsBrE"}

package/dist/index.js

@@ -0,0 +1,121 @@
+export const A2UI_VERSION = "0.1";
+export class A2uiParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "A2uiParseError";
+    }
+}
+export function parseA2uiSurface(input) {
+    let value = input;
+    if (typeof input === "string") {
+        try {
+            value = JSON.parse(input);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "unknown JSON error";
+            throw new A2uiParseError(`Invalid JSON: ${message}`);
+        }
+    }
+    const surface = expectObject(value, "surface");
+    const version = expectString(surface.version, "surface.version");
+    if (version !== A2UI_VERSION) {
+        throw new A2uiParseError(`Unsupported A2UI version: ${version}`);
+    }
+    return {
+        version: A2UI_VERSION,
+        root: parseNode(surface.root, "surface.root"),
+    };
+}
+function parseNode(value, path) {
+    const node = expectObject(value, path);
+    const id = expectString(node.id, `${path}.id`);
+    const type = expectString(node.type, `${path}.type`);
+    switch (type) {
+        case "container":
+            return {
+                id,
+                type,
+                children: expectArray(node.children, `${path}.children`).map((child, index) => parseNode(child, `${path}.children[${index}]`)),
+            };
+        case "text":
+            return { id, type, text: expectString(node.text, `${path}.text`) };
+        case "button":
+            return {
+                id,
+                type,
+                label: expectString(node.label, `${path}.label`),
+                action: parseToolAction(node.action, `${path}.action`),
+            };
+        case "text-input": {
+            const label = expectString(node.label, `${path}.label`);
+            const valueField = optionalString(node.value, `${path}.value`);
+            const binding = optionalString(node.binding, `${path}.binding`);
+            return {
+                id,
+                type,
+                label,
+                ...(valueField === undefined ? {} : { value: valueField }),
+                ...(binding === undefined ? {} : { binding }),
+            };
+        }
+        default:
+            throw new A2uiParseError(`Unsupported node type at ${path}: ${type}`);
+    }
+}
+function parseToolAction(value, path) {
+    const action = expectObject(value, path);
+    const type = expectString(action.type, `${path}.type`);
+    if (type !== "tool") {
+        throw new A2uiParseError(`Unsupported action type at ${path}: ${type}`);
+    }
+    const arguments_ = action.arguments;
+    return {
+        type,
+        name: expectString(action.name, `${path}.name`),
+        ...(arguments_ === undefined
+            ? {}
+            : { arguments: expectJsonObject(arguments_, `${path}.arguments`) }),
+    };
+}
+function expectObject(value, path) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new A2uiParseError(`Expected an object at ${path}`);
+    }
+    return value;
+}
+function expectArray(value, path) {
+    if (!Array.isArray(value)) {
+        throw new A2uiParseError(`Expected an array at ${path}`);
+    }
+    return value;
+}
+function expectString(value, path) {
+    if (typeof value !== "string") {
+        throw new A2uiParseError(`Expected a string at ${path}`);
+    }
+    return value;
+}
+function optionalString(value, path) {
+    return value === undefined ? undefined : expectString(value, path);
+}
+function expectJsonObject(value, path) {
+    const object = expectObject(value, path);
+    const result = {};
+    for (const [key, child] of Object.entries(object)) {
+        result[key] = expectJsonValue(child, `${path}.${key}`);
+    }
+    return result;
+}
+function expectJsonValue(value, path) {
+    if (value === null ||
+        typeof value === "boolean" ||
+        typeof value === "number" ||
+        typeof value === "string") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((child, index) => expectJsonValue(child, `${path}[${index}]`));
+    }
+    return expectJsonObject(value, path);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,12 +1,42 @@
 {
   "name": "@mcp-native/a2ui",
-  "version": "0.0.1",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "0.0.3",
+  "description": "A2UI parsing and bindings for MCP Native.",
+  "keywords": [
+    "a2ui",
+    "declarative-ui",
+    "mcp",
+    "model-context-protocol",
+    "typescript"
+  ],
+  "homepage": "https://github.com/pablospaniard/mcp-native#readme",
+  "bugs": {
+    "url": "https://github.com/pablospaniard/mcp-native/issues"
   },
-  "keywords": [],
-  "author": "",
   "license": "MIT",
-  "description": "MCP Native - a2ui package"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pablospaniard/mcp-native.git",
+    "directory": "packages/a2ui"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mcp-native/core": "^0.0.3"
+  }
 }

package/index.js

@@ -1 +0,0 @@
-module.exports = {};