mcp-native 0.9.3 → 1.0.0-beta.1

package/README.md

@@ -2,7 +2,7 @@
 
 # mcp-native
 
-### One entry point for the MCP Native React Native host runtime
+### One entry point for the low-level MCP Native runtime and UI layers
 
 [![npm](https://img.shields.io/npm/v/mcp-native)](https://www.npmjs.com/package/mcp-native)
 [![downloads](https://img.shields.io/npm/dm/mcp-native)](https://www.npmjs.com/package/mcp-native)
@@ -13,28 +13,42 @@
 
 </div>
 
-`mcp-native` is the current convenient way to use the runtime, A2UI, React Native, mixed-surface,
-and WebView APIs from one package. It re-exports the focused `@mcp-native/*` layers while leaving
-transport adapters as a separate installation choice. The `1.0.0` roadmap adds
-`@mcp-native/host` as an optional high-level connect-call-render package; these low-level APIs remain
-available for applications that need manual composition.
+`mcp-native` is the convenience entry point for the core, A2UI, React Native, mixed-surface, and
+WebView APIs. It does not include the official MCP SDK adapter or the high-level host. Install
+[`@mcp-native/mcp`](https://www.npmjs.com/package/@mcp-native/mcp) for the adapter or
+[`@mcp-native/host`](https://www.npmjs.com/package/@mcp-native/host) for the connect-call-render
+workflow. Use this package when the application wants to compose the low-level layers itself.
 
-The current 0.9 line contains the validated low-level React Native feature set and is ready to try in
-an integration. New work should use A2UI v1 Candidate or the stable MCP Apps `2026-01-26` host flow;
-the custom A2UI 0.1 APIs live under `/legacy` for migration. Public standard-contract registration
-and application-defined custom input adapters are explicitly deferred until after `1.0.0`.
+This package contains the validated low-level React Native feature set: A2UI v1 Candidate and the
+stable MCP Apps `2026-01-26` host flow. Public standard-contract registration and
+application-defined custom input adapters remain post-1.0 work. Negotiated, locally compiled
+semantic host extensions are already supported.
 
 For the big picture, start with the [product guide](https://github.com/pablospaniard/mcp-native/blob/main/docs/product-guide.md).
 
 ## Install
 
+Until the stable `1.0.0` release, select the beta package explicitly:
+
 ```bash
-npm install mcp-native react
+npm install mcp-native@beta react
 ```
 
 React `>=18.1.0` is the only peer dependency. Native components and platform integrations are
 supplied by the host application. The package is ESM-only and includes TypeScript declarations.
 
+Run the bundled local diagnostics or generate safe starting points without network access:
+
+```bash
+npx mcp-native doctor
+npx mcp-native scaffold-catalog src/mcp
+npx mcp-native scaffold-extension com.example/data-grid DataGrid src/mcp
+```
+
+Scaffolds refuse to overwrite existing files. The extension command emits a closed, bounded
+manifest and a local React Native registration skeleton; the application must still negotiate it
+and supply explicit policy.
+
 ## A2UI v1 Candidate path
 
 The package re-exports the APIs needed to negotiate the project-owned binding, resolve official
@@ -42,78 +56,15 @@ v1 JSONL lifecycle envelopes, maintain bounded ordered surface state, apply expl
 component/event/function policies, and mount the supported native subset through
 `A2uiV1NativeSurface`. The mounted surface keeps typed input edits renderer-local and returns validated
 official action envelopes to a host callback; it never selects a return transport. See the
-[complete v1 host-flow example](https://github.com/pablospaniard/mcp-native#a2ui-v1-candidate-host-flow)
+[A2UI package guide](https://github.com/pablospaniard/mcp-native/tree/main/packages/a2ui)
 and the [`@mcp-native/react-native` adapter documentation](https://github.com/pablospaniard/mcp-native/tree/main/packages/react-native#a2ui-v1-render-plan-adapter).
 
-## Legacy custom `0.1` migration
-
-For `0.9.x`, migrate these imports to `mcp-native/legacy`. Root aliases are removed at `1.0.0`;
-the explicit legacy subpath stays frozen for migration and security fixes.
-
-```tsx
-import { McpNativeRuntime, createAllowlistActionPolicy, type McpClient } from "mcp-native";
-import {
-  McpNativeSurface,
-  parseA2uiSurface,
-  useMcpNativeActionDispatcher,
-} from "mcp-native/legacy";
-import { Button, Text, TextInput, View } from "react-native";
-
-const components = { Button, Text, TextInput, View };
-
-const client: McpClient = {
-  async listTools() {
-    return { tools: [] };
-  },
-  async callTool(name, arguments_) {
-    return {
-      content: [{ type: "text", text: `Called ${name}` }],
-      structuredContent: { name, arguments: arguments_ },
-    };
-  },
-  async readResource(uri) {
-    return { contents: [{ uri, text: "" }] };
-  },
-};
-
-const runtime = new McpNativeRuntime(client, {
-  actionPolicy: createAllowlistActionPolicy([{ name: "continue_flow" }]),
-});
-
-const surface = parseA2uiSurface({
-  version: "0.1",
-  root: {
-    id: "welcome",
-    type: "container",
-    children: [
-      { id: "title", type: "text", text: "Hello from MCP" },
-      {
-        id: "continue",
-        type: "button",
-        label: "Continue",
-        action: { type: "tool", name: "continue_flow" },
-      },
-    ],
-  },
-});
-
-function NativeScreen() {
-  const onAction = useMcpNativeActionDispatcher(runtime, {
-    onError: (error) => console.error("MCP action failed", error),
-  });
-
-  return <McpNativeSurface surface={surface} components={components} onAction={onAction} />;
-}
-```
-
-The host supplies the locally bundled native components and explicitly allows the tools a surface may dispatch, including their arguments. Without an `actionPolicy`, surface action dispatch is denied; trusted host code can still call `callTool()` directly after JSON validation. MCP Native never downloads and executes server-provided React Native JavaScript.
-
 ## Included packages
 
 | Package                                                                              | What it provides                                                                  |
 | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
 | [`@mcp-native/core`](https://www.npmjs.com/package/@mcp-native/core)                 | MCP client contracts, runtime delegation, JSON types, and declared tool actions.  |
-| [`@mcp-native/a2ui`](https://www.npmjs.com/package/@mcp-native/a2ui)                 | Feature-scoped v1 Candidate adapter plus deprecated `0.1` migration APIs.         |
+| [`@mcp-native/a2ui`](https://www.npmjs.com/package/@mcp-native/a2ui)                 | Feature-scoped v1 Candidate negotiation, parsing, and surface state.              |
 | [`@mcp-native/react-native`](https://www.npmjs.com/package/@mcp-native/react-native) | Trusted plans, local v1 state/actions, hooks, and a host-owned component catalog. |
 | [`@mcp-native/webview`](https://www.npmjs.com/package/@mcp-native/webview)           | Stable Apps discovery, sandbox, native adapter, and JSON-RPC bridge.              |
 
@@ -121,10 +72,9 @@ Install an individual package instead when you only need one layer.
 
 Use the separately installable [`@mcp-native/mcp`](https://github.com/pablospaniard/mcp-native/tree/main/packages/mcp) package to connect these APIs to the official MCP TypeScript SDK without forcing that SDK dependency on every `mcp-native` consumer.
 
-## Included in the current 0.9 line
+## Available across the package line
 
 - transport-independent MCP runtime contracts;
-- isolated migration support for the deprecated custom `0.1` surface;
 - declared tool-action dispatch;
 - strict A2UI resource-link resolution from tool results;
 - schema-validated A2UI v1 JSONL lifecycle state and explicit host policies;
@@ -151,8 +101,8 @@ Use the separately installable [`@mcp-native/mcp`](https://github.com/pablospani
 
 For the release-by-release history, see the
 [changelog](https://github.com/pablospaniard/mcp-native/blob/main/CHANGELOG.md). The runnable
-[Expo Go todo app](../../examples/expo-go-todolist/README.md) shows the main A2UI and React Native
-pieces working together.
+[Expo Go todo app](https://github.com/pablospaniard/mcp-native/tree/main/examples/expo-go-todolist)
+shows the main A2UI and React Native pieces working together.
 
 ## Security model
 

package/bin/mcp-native.mjs

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+
+const [, , command = "doctor", ...arguments_] = process.argv;
+
+try {
+  if (command === "doctor") {
+    runDoctor(arguments_);
+  } else if (command === "scaffold-catalog") {
+    scaffoldCatalog(arguments_);
+  } else if (command === "scaffold-extension") {
+    scaffoldExtension(arguments_);
+  } else if (command === "help" || command === "--help" || command === "-h") {
+    printHelp();
+  } else {
+    fail(`Unknown command ${JSON.stringify(command)}. Run mcp-native help.`);
+  }
+} catch (error) {
+  fail(error instanceof Error ? error.message : "MCP Native CLI failed.");
+}
+
+function runDoctor(commandArguments) {
+  const json = commandArguments.includes("--json");
+  const directoryArgument = commandArguments.find((value) => value !== "--json") ?? ".";
+  const directory = resolve(directoryArgument);
+  const manifestPath = join(directory, "package.json");
+  if (!existsSync(manifestPath)) {
+    throw new Error(`No package.json found in ${directory}`);
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const dependencyMaps = [
+    manifest.dependencies ?? {},
+    manifest.devDependencies ?? {},
+    manifest.peerDependencies ?? {},
+  ];
+  const dependencies = Object.assign({}, ...dependencyMaps);
+  const hasWorkspaces = manifest.workspaces !== undefined;
+  const mcpNativeEntries = Object.entries(dependencies).filter(
+    ([name]) => name === "mcp-native" || name.startsWith("@mcp-native/"),
+  );
+  const findings = [];
+  if (mcpNativeEntries.length === 0) {
+    findings.push(
+      finding(
+        hasWorkspaces ? "warning" : "error",
+        hasWorkspaces ? "packages-not-at-workspace-root" : "packages-missing",
+        hasWorkspaces
+          ? "No MCP Native package is declared at the workspace root; run doctor in the consuming workspace too."
+          : "No MCP Native package is declared.",
+      ),
+    );
+  }
+  const ranges = new Set(mcpNativeEntries.map(([, range]) => String(range)));
+  if (ranges.size > 1) {
+    findings.push(
+      finding(
+        "error",
+        "version-ranges-mixed",
+        "MCP Native packages use different version ranges; align them before installation.",
+      ),
+    );
+  }
+  const usesNative = mcpNativeEntries.some(
+    ([name]) =>
+      name === "mcp-native" || name === "@mcp-native/react-native" || name === "@mcp-native/host",
+  );
+  if (usesNative && dependencies.react === undefined) {
+    findings.push(
+      finding("error", "react-missing", "A React dependency is required by the native renderer."),
+    );
+  }
+  if (usesNative && dependencies["react-native"] === undefined) {
+    findings.push(
+      finding(
+        "warning",
+        "react-native-not-declared",
+        "No React Native dependency is declared; ignore this only when the package is supplied by the application platform.",
+      ),
+    );
+  }
+  const metroPaths = ["metro.config.js", "metro.config.cjs", "metro.config.mjs"].map((name) =>
+    join(directory, name),
+  );
+  if (usesNative && hasWorkspaces && !metroPaths.some(existsSync)) {
+    findings.push(
+      finding(
+        "warning",
+        "metro-workspace-config-missing",
+        "This workspace has no Metro configuration; verify watchFolders, resolver paths, and duplicate React exclusion.",
+      ),
+    );
+  }
+  if (usesNative && !existsSync(join(directory, "tsconfig.json"))) {
+    findings.push(
+      finding(
+        "warning",
+        "typescript-config-missing",
+        "No tsconfig.json was found, so typed catalog adapters cannot be checked here.",
+      ),
+    );
+  }
+  if (findings.length === 0) {
+    findings.push(
+      finding("ok", "configuration-ready", "No common package or workspace issue found."),
+    );
+  }
+  const report = { directory, packageName: manifest.name ?? basename(directory), findings };
+  if (json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } else {
+    process.stdout.write(`MCP Native doctor: ${report.packageName}\n`);
+    for (const item of findings) {
+      process.stdout.write(`${item.level.toUpperCase()} ${item.code}: ${item.message}\n`);
+    }
+  }
+  if (findings.some((item) => item.level === "error")) process.exitCode = 1;
+}
+
+function scaffoldCatalog(commandArguments) {
+  const outputDirectory = resolve(commandArguments[0] ?? ".");
+  const outputPath = join(outputDirectory, "mcpNativeCatalog.tsx");
+  writeNewFile(outputPath, catalogTemplate());
+  process.stdout.write(`Created ${outputPath}\n`);
+}
+
+function scaffoldExtension(commandArguments) {
+  const [extensionId, componentName, directoryArgument = "."] = commandArguments;
+  if (
+    extensionId === undefined ||
+    !/^[a-z0-9]+(?:[._-][a-z0-9]+)+(?:\/[a-z0-9]+(?:[._-][a-z0-9]+)*)?$/u.test(extensionId)
+  ) {
+    throw new Error("scaffold-extension requires a namespaced extension ID");
+  }
+  if (componentName === undefined || !/^[A-Z][A-Za-z0-9]*$/u.test(componentName)) {
+    throw new Error("scaffold-extension requires a PascalCase component name");
+  }
+  const outputDirectory = resolve(directoryArgument);
+  const manifestPath = join(outputDirectory, `${componentName}.manifest.json`);
+  const componentPath = join(outputDirectory, `${componentName}.tsx`);
+  assertNewFiles([manifestPath, componentPath]);
+  writeNewFile(
+    manifestPath,
+    `${JSON.stringify(extensionManifest(extensionId, componentName), null, 2)}\n`,
+  );
+  writeNewFile(componentPath, extensionComponentTemplate(componentName));
+  process.stdout.write(`Created ${manifestPath}\nCreated ${componentPath}\n`);
+}
+
+function assertNewFiles(paths) {
+  const existingPath = paths.find(existsSync);
+  if (existingPath !== undefined) {
+    throw new Error(`Refusing to overwrite existing file ${existingPath}`);
+  }
+}
+
+function writeNewFile(path, content) {
+  if (existsSync(path)) throw new Error(`Refusing to overwrite existing file ${path}`);
+  mkdirSync(resolve(path, ".."), { recursive: true });
+  writeFileSync(path, content, { encoding: "utf8", flag: "wx" });
+}
+
+function extensionManifest(extensionId, componentName) {
+  return {
+    profileVersion: "1",
+    extensionId,
+    catalogId: `${extensionId}@1`,
+    catalogVersion: "1",
+    schemaVersion: "1.0.0",
+    componentName: `${extensionId}:${componentName}`,
+    propsSchema: {
+      type: "object",
+      properties: { label: { type: "string", minLength: 1, maxLength: 128 } },
+      required: ["label"],
+      additionalProperties: false,
+    },
+    events: [],
+    platforms: ["android", "ios"],
+    accessibility: {
+      ownership: "host",
+      requiresLabel: true,
+      behavior: "Expose one host-rendered labeled value.",
+    },
+    resourceNeeds: [],
+    permissionNeeds: [],
+    limits: {
+      maximumInstances: 16,
+      maximumEventPayloadValues: 8,
+      maximumEventPayloadStringCodeUnits: 512,
+      maximumPropsValues: 16,
+      maximumPropsStringCodeUnits: 2048,
+      maximumUpdatesPerSurface: 32,
+    },
+    fallback: { kind: "reject" },
+    compatibility: { owner: "Replace with the responsible application team" },
+  };
+}
+
+function catalogTemplate() {
+  return `import { createA2uiV1NativeHost } from "@mcp-native/react-native";
+import { Button, Text, TextInput, View } from "react-native";
+
+// Keep this registration at module scope so component identity and local state remain stable.
+export const mcpNativeHost = createA2uiV1NativeHost({
+  components: { Button, Text, TextInput, View },
+  allowedEventNames: [],
+  allowedFunctionNames: [],
+  layoutContracts: {
+    View: {
+      allowedParents: ["bounded", "scroll", "unbounded"],
+      sizing: "intrinsic",
+    },
+  },
+});
+`;
+}
+
+function extensionComponentTemplate(componentName) {
+  return `import manifestJson from "./${componentName}.manifest.json";
+import { createNativeHostExtensionRegistration } from "@mcp-native/react-native";
+import { Text } from "react-native";
+
+function ${componentName}({ label, accessibilityLabel }: { label: string; accessibilityLabel?: string }) {
+  return <Text accessibilityLabel={accessibilityLabel}>{label}</Text>;
+}
+
+export const ${componentName[0].toLowerCase()}${componentName.slice(1)}Registration =
+  createNativeHostExtensionRegistration(
+    manifestJson,
+    ${componentName},
+    ({ accessibilityLabel, semanticProps }) => {
+      if (typeof semanticProps.label !== "string") {
+        throw new Error("Validated extension props do not match the local component");
+      }
+      return {
+        label: semanticProps.label,
+        ...(accessibilityLabel === undefined ? {} : { accessibilityLabel }),
+      };
+    },
+  );
+`;
+}
+
+function finding(level, code, message) {
+  return { level, code, message };
+}
+
+function printHelp() {
+  process.stdout.write(`Usage:
+  mcp-native doctor [directory] [--json]
+  mcp-native scaffold-catalog [output-directory]
+  mcp-native scaffold-extension <extension-id> <PascalCaseName> [output-directory]
+`);
+}
+
+function fail(message) {
+  process.stderr.write(`mcp-native: ${message}\n`);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-native",
-  "version": "0.9.3",
+  "version": "1.0.0-beta.1",
   "description": "Convenience package for the MCP Native runtime.",
   "keywords": [
     "a2ui",
@@ -19,7 +19,11 @@
     "url": "git+https://github.com/pablospaniard/mcp-native.git",
     "directory": "packages/mcp-native"
   },
+  "bin": {
+    "mcp-native": "./bin/mcp-native.mjs"
+  },
   "files": [
+    "bin",
     "dist",
     "LICENSE",
     "README.md"
@@ -44,10 +48,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@mcp-native/a2ui": "^0.9.3",
-    "@mcp-native/core": "^0.9.3",
-    "@mcp-native/react-native": "^0.9.3",
-    "@mcp-native/webview": "^0.9.3"
+    "@mcp-native/a2ui": "^1.0.0-beta.1",
+    "@mcp-native/core": "^1.0.0-beta.1",
+    "@mcp-native/react-native": "^1.0.0-beta.1",
+    "@mcp-native/webview": "^1.0.0-beta.1"
   },
   "peerDependencies": {
     "react": ">=18.1.0"