mcp-native 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +119 -11
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -7,9 +7,8 @@
7
7
  [![npm](https://img.shields.io/npm/v/mcp-native)](https://www.npmjs.com/package/mcp-native)
8
8
  [![downloads](https://img.shields.io/npm/dm/mcp-native)](https://www.npmjs.com/package/mcp-native)
9
9
  [![license](https://img.shields.io/npm/l/mcp-native)](https://github.com/pablospaniard/mcp-native/blob/main/LICENSE)
10
- [![CI](https://github.com/pablospaniard/mcp-native/actions/workflows/ci.yml/badge.svg)](https://github.com/pablospaniard/mcp-native/actions/workflows/ci.yml)
11
10
 
12
- [GitHub](https://github.com/pablospaniard/mcp-native) · [Architecture](https://github.com/pablospaniard/mcp-native/blob/main/docs/RFC-0001-architecture.md) · [Standards status](https://github.com/pablospaniard/mcp-native/blob/main/docs/standards-compatibility.md) · [Contributing](https://github.com/pablospaniard/mcp-native/blob/main/CONTRIBUTING.md) · [Security](https://github.com/pablospaniard/mcp-native/blob/main/SECURITY.md)
11
+ [GitHub](https://github.com/pablospaniard/mcp-native) · [Architecture](https://github.com/pablospaniard/mcp-native/blob/main/docs/RFC-0001-architecture.md) · [Standards status](https://github.com/pablospaniard/mcp-native/blob/main/docs/standards-compatibility.md) · [Security](https://github.com/pablospaniard/mcp-native/blob/main/SECURITY.md)
13
12
 
14
13
  </div>
15
14
 
@@ -19,10 +18,18 @@ WebView APIs. It does not include the official MCP SDK adapter or the high-level
19
18
  [`@mcp-native/host`](https://www.npmjs.com/package/@mcp-native/host) for the connect-call-render
20
19
  workflow. Use this package when the application wants to compose the low-level layers itself.
21
20
 
22
- This package contains the validated low-level React Native feature set: A2UI v1 Candidate and the
23
- stable MCP Apps `2026-01-26` host flow. Public standard-contract registration and
24
- application-defined custom input adapters remain post-1.0 work. Negotiated, locally compiled
25
- semantic host extensions are already supported.
21
+ This package contains the validated low-level React Native feature set: a pinned, feature-scoped A2UI v1.0 Candidate profile and the
22
+ stable MCP Apps `2026-01-26` host flow. Negotiated, locally compiled semantic host extensions are
23
+ supported here. Version `1.1.0` adds standard-contract selection and application-defined inline JSON
24
+ adapters through the separate `@mcp-native/host/contracts` subpaths; install the host package directly
25
+ for those APIs. See the [1.1 migration guide](https://github.com/pablospaniard/mcp-native/blob/main/docs/migration-to-1.1.md)
26
+ and [publication status](https://github.com/pablospaniard/mcp-native/blob/main/docs/releasing.md#110-release-preparation).
27
+
28
+ As of 2026-09-07, [upstream A2UI versions](https://a2ui.org/#specification-versions) identify
29
+ v1.0 as Candidate and v0.9.1 as the current production release. See the
30
+ [implemented A2UI profile](https://github.com/pablospaniard/mcp-native/blob/main/docs/a2ui-v1-conformance.md)
31
+ for exact coverage and exclusions; this package does not claim v0.9.1 compatibility or automatic
32
+ compatibility with later upstream revisions.
26
33
 
27
34
  For the big picture, start with the [product guide](https://github.com/pablospaniard/mcp-native/blob/main/docs/product-guide.md).
28
35
 
@@ -40,6 +47,8 @@ npm install mcp-native@1 react
40
47
  React `>=18.1.0` is the only peer dependency. Native components and platform integrations are
41
48
  supplied by the host application. The package is ESM-only and includes TypeScript declarations.
42
49
 
50
+ ## Quick start
51
+
43
52
  Use the `a2ui` and `reactNative` namespaces when composing both concise package APIs from this entry
44
53
  point:
45
54
 
@@ -52,17 +61,114 @@ const Surface = reactNative.HostSurface;
52
61
 
53
62
  Direct named re-exports and the previous prefixed compatibility aliases remain available.
54
63
 
55
- Run the bundled local diagnostics or generate safe starting points without network access:
64
+ ## CLI
65
+
66
+ The bundled CLI checks local configuration and generates starter files. Running `npx mcp-native`
67
+ without a command runs `doctor` in the current directory.
56
68
 
57
69
  ```bash
58
70
  npx mcp-native doctor
59
71
  npx mcp-native scaffold-catalog src/mcp
60
72
  npx mcp-native scaffold-extension com.example/data-grid DataGrid src/mcp
73
+ npx mcp-native help
74
+ ```
75
+
76
+ ### doctor
77
+
78
+ Checks a local `package.json` for common setup issues without changing files.
79
+
80
+ ```text
81
+ doctor [directory] [--json]
82
+ ```
83
+
84
+ | Argument or option | Required | Meaning |
85
+ | ------------------ | -------- | -------------------------------------------------------------------- |
86
+ | `directory` | No | Folder containing `package.json`; defaults to the current directory. |
87
+ | `--json` | No | Print a JSON report instead of readable text. |
88
+
89
+ For example, `npx mcp-native doctor examples/expo-go-todolist --json` reports the resolved
90
+ `directory`, `packageName`, and `findings`, each with a `level`, `code`, and `message`.
91
+
92
+ The checks cover missing MCP Native packages and mismatched declared version ranges. For native
93
+ consumers, they also check React and React Native declarations, a workspace's Metro configuration
94
+ file, and `tsconfig.json`. At a workspace root, missing MCP Native packages produce a warning;
95
+ run the command in the consuming workspace too. These checks inspect declarations and file
96
+ presence, so they do not prove that the application builds or runs.
97
+
98
+ Errors produce exit status `1`; warnings alone leave status `0`. A missing or unreadable
99
+ `package.json`, or invalid JSON, also fails with status `1` and an error on stderr.
100
+
101
+ ### scaffold-catalog
102
+
103
+ Generates a starter local React Native host catalog.
104
+
105
+ ```text
106
+ scaffold-catalog [output-directory]
107
+ ```
108
+
109
+ | Argument | Required | Meaning |
110
+ | ------------------ | -------- | ----------------------------------------------------------------------------------- |
111
+ | `output-directory` | No | Destination folder; defaults to the current directory. Missing folders are created. |
112
+
113
+ For example, `npx mcp-native scaffold-catalog src/mcp` creates `src/mcp/mcpNativeCatalog.tsx`
114
+ and prints its path. Existing files are never overwritten.
115
+
116
+ The file exports `mcpNativeHost`, created with `createA2uiV1NativeHost`, and registers React
117
+ Native `Button`, `Text`, `TextInput`, and `View`. It starts with empty event and function
118
+ allowlists and an intrinsic `View` layout contract. Adapt the components, allowlists, and layout
119
+ contracts to your application, then wire the exported host into your rendering flow. Keep the
120
+ registration at module scope so component identity and local state remain stable.
121
+
122
+ ### scaffold-extension
123
+
124
+ `scaffold-extension` generates starter files for a custom UI component's contract and local
125
+ registration. It does not build a working data grid.
126
+
127
+ ```text
128
+ scaffold-extension <extension-id> <PascalCaseName> [output-directory]
129
+ ```
130
+
131
+ | Argument | Required | Meaning |
132
+ | ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
133
+ | `extension-id` | Yes | Namespaced ID, such as `com.aily/data-grid`; see naming rules below. |
134
+ | `PascalCaseName` | Yes | Component name, such as `DataGrid`: start with an uppercase ASCII letter, then use only ASCII letters or digits. |
135
+ | `output-directory` | No | Destination folder; defaults to the current directory. Missing folders are created. |
136
+
137
+ The extension ID uses lowercase ASCII letters and digits in non-empty groups separated by `.`,
138
+ `_`, or `-`. It must have at least two groups before an optional `/` suffix; the suffix uses the
139
+ same characters and separators and must be non-empty. Spaces, uppercase letters, and extra
140
+ slashes are not allowed.
141
+
142
+ For example:
143
+
144
+ ```bash
145
+ npx mcp-native scaffold-extension com.aily/data-grid DataGrid src/mcp
61
146
  ```
62
147
 
63
- Scaffolds refuse to overwrite existing files. The extension command emits a closed, bounded
64
- manifest and a local React Native registration skeleton; the application must still negotiate it
65
- and supply explicit policy.
148
+ This creates:
149
+
150
+ - `src/mcp/DataGrid.manifest.json`: the component contract, initially allowing a bounded `label`
151
+ prop and no events, with platform, accessibility, resource, permission, and limit declarations.
152
+ - `src/mcp/DataGrid.tsx`: a placeholder that displays the label with React Native `Text`, plus a
153
+ local registration and an explicit mapper from semantic props to component props.
154
+
155
+ Existing files are never overwritten. If either target file already exists, the command refuses
156
+ to generate the pair.
157
+
158
+ Next, implement the component, define its allowed props and events in the manifest, register it
159
+ with the host, negotiate support with the MCP server, and configure host policy. Follow the
160
+ [full host-extension integration flow](https://github.com/pablospaniard/mcp-native/blob/main/docs/media-and-host-extensions.md#host-extension-flow).
161
+
162
+ ### help
163
+
164
+ Prints the command syntax without changing files. No arguments are required:
165
+
166
+ ```bash
167
+ npx mcp-native help
168
+ ```
169
+
170
+ `npx mcp-native --help` and `npx mcp-native -h` are equivalent. Use these at the command level;
171
+ individual subcommands do not implement their own `--help` option.
66
172
 
67
173
  ## Native A2UI path
68
174
 
@@ -79,7 +185,7 @@ and the [`@mcp-native/react-native` adapter documentation](https://github.com/pa
79
185
  | Package | What it provides |
80
186
  | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
81
187
  | [`@mcp-native/core`](https://www.npmjs.com/package/@mcp-native/core) | MCP client contracts, runtime delegation, JSON types, and declared tool actions. |
82
- | [`@mcp-native/a2ui`](https://www.npmjs.com/package/@mcp-native/a2ui) | Feature-scoped v1 Candidate negotiation, parsing, and surface state. |
188
+ | [`@mcp-native/a2ui`](https://www.npmjs.com/package/@mcp-native/a2ui) | Feature-scoped v1.0 Candidate negotiation, parsing, and surface state. |
83
189
  | [`@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. |
84
190
  | [`@mcp-native/webview`](https://www.npmjs.com/package/@mcp-native/webview) | Stable Apps discovery, sandbox, native adapter, and JSON-RPC bridge. |
85
191
 
@@ -125,6 +231,8 @@ Remote servers may provide declarative UI and actions, but the host owns compone
125
231
 
126
232
  Read the full [architecture](https://github.com/pablospaniard/mcp-native/blob/main/docs/RFC-0001-architecture.md) and [security policy](https://github.com/pablospaniard/mcp-native/blob/main/SECURITY.md) before integrating or extending the runtime.
127
233
 
234
+ See the [contributing guide](https://github.com/pablospaniard/mcp-native/blob/main/CONTRIBUTING.md) to contribute to MCP Native.
235
+
128
236
  ## License
129
237
 
130
238
  [MIT](https://github.com/pablospaniard/mcp-native/blob/main/LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mcp-native",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "Convenience package for the MCP Native runtime.",
5
5
  "keywords": [
6
6
  "a2ui",
@@ -48,10 +48,10 @@
48
48
  "access": "public"
49
49
  },
50
50
  "dependencies": {
51
- "@mcp-native/a2ui": "^1.0.0",
52
- "@mcp-native/core": "^1.0.0",
53
- "@mcp-native/react-native": "^1.0.0",
54
- "@mcp-native/webview": "^1.0.0"
51
+ "@mcp-native/a2ui": "^1.1.0",
52
+ "@mcp-native/core": "^1.1.0",
53
+ "@mcp-native/react-native": "^1.1.0",
54
+ "@mcp-native/webview": "^1.1.0"
55
55
  },
56
56
  "peerDependencies": {
57
57
  "react": ">=18.1.0"