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