@mcp-native/core 0.0.1 → 0.0.3

package/README.md

@@ -1,5 +1,90 @@
+<div align="center">
+
 # @mcp-native/core
 
-Part of MCP Native — a native UI runtime for Model Context Protocol applications.
+### Transport-neutral MCP runtime contracts and safe action routing
+
+[![npm](https://img.shields.io/npm/v/@mcp-native/core)](https://www.npmjs.com/package/@mcp-native/core)
+[![downloads](https://img.shields.io/npm/dm/@mcp-native/core)](https://www.npmjs.com/package/@mcp-native/core)
+[![license](https://img.shields.io/npm/l/@mcp-native/core)](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 is an early proof of concept. Its public API may change before `1.0.0`.
+
+`@mcp-native/core` is the protocol- and renderer-independent foundation of MCP Native. It defines the small MCP client boundary consumed by the runtime and routes declared actions without depending on A2UI, React Native, WebViews, or a specific MCP SDK transport.
+
+## Install
+
+```bash
+npm install @mcp-native/core
+```
+
+The package is ESM-only and includes TypeScript declarations.
+
+## Quick start
+
+Adapt any MCP client to the `McpClient` interface, then use `McpNativeRuntime` to coordinate operations:
+
+```ts
+import { McpNativeRuntime, type McpClient } from "@mcp-native/core";
+
+const client: McpClient = {
+  async listTools() {
+    return [
+      {
+        name: "save_profile",
+        description: "Save profile details",
+        inputSchema: { type: "object" },
+      },
+    ];
+  },
+  async callTool(name, arguments_) {
+    return {
+      content: [{ type: "json", data: { name, arguments: arguments_ } }],
+    };
+  },
+  async readResource(uri) {
+    return { uri, mimeType: "text/plain", text: "Hello from MCP" };
+  },
+};
+
+const runtime = new McpNativeRuntime(client);
+
+await runtime.dispatch({
+  type: "tool",
+  name: "save_profile",
+  arguments: { displayName: "Ada" },
+});
+```
+
+## Public API
+
+| Export                                        | Purpose                                                                                     |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `McpNativeRuntime`                            | Delegates tool listing, tool calls, resource reads, and declared actions to an `McpClient`. |
+| `McpClient`                                   | Minimal interface implemented by an SDK- or transport-specific adapter.                     |
+| `McpTool`, `McpResource`, `McpToolCallResult` | Transport-neutral MCP data contracts used by the runtime.                                   |
+| `ToolAction`, `McpNativeAction`               | Declarative actions that can be dispatched through the runtime.                             |
+| `JsonPrimitive`, `JsonValue`, `JsonObject`    | JSON-safe value types for untrusted protocol data.                                          |
+
+## Design boundaries
+
+- No React Native dependency.
+- No A2UI or WebView dependency.
+- No transport or official MCP SDK dependency yet.
+- No remote code loading or execution.
+- Host applications remain responsible for authentication, permissions, transport security, and user approval.
+
+## Related packages
+
+- [`@mcp-native/a2ui`](https://www.npmjs.com/package/@mcp-native/a2ui) validates declarative surfaces and actions.
+- [`@mcp-native/react-native`](https://www.npmjs.com/package/@mcp-native/react-native) converts validated surfaces into trusted native render plans.
+- [`@mcp-native/webview`](https://www.npmjs.com/package/@mcp-native/webview) defines the HTML compatibility policy boundary.
+- [`mcp-native`](https://www.npmjs.com/package/mcp-native) re-exports 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,53 @@
+export type JsonPrimitive = boolean | null | number | string;
+export type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+export interface McpTool {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema: JsonObject;
+}
+export interface McpContent {
+    readonly type: string;
+    readonly data: JsonObject;
+}
+export interface McpToolCallResult {
+    readonly content: readonly McpContent[];
+    readonly isError?: boolean;
+}
+export interface McpResource {
+    readonly uri: string;
+    readonly mimeType?: string;
+    readonly text?: string;
+    readonly blob?: string;
+}
+/**
+ * The small client boundary consumed by the runtime. SDK-specific clients can
+ * implement this interface without coupling the core package to a transport.
+ */
+export interface McpClient {
+    listTools(): Promise<readonly McpTool[]>;
+    callTool(name: string, arguments_: JsonObject): Promise<McpToolCallResult>;
+    readResource(uri: string): Promise<McpResource>;
+}
+export interface ToolAction {
+    readonly type: "tool";
+    readonly name: string;
+    readonly arguments?: JsonObject;
+}
+export type McpNativeAction = ToolAction;
+/**
+ * Coordinates MCP operations without knowing about A2UI, React Native, or any
+ * other renderer. It deliberately routes declared actions instead of loading
+ * executable code from a server.
+ */
+export declare class McpNativeRuntime {
+    #private;
+    constructor(client: McpClient);
+    listTools(): Promise<readonly McpTool[]>;
+    callTool(name: string, arguments_?: JsonObject): Promise<McpToolCallResult>;
+    readResource(uri: string): Promise<McpResource>;
+    dispatch(action: McpNativeAction): Promise<McpToolCallResult>;
+}
+//# 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,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7D,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,UAAU,GAAG,SAAS,SAAS,EAAE,CAAC;AAE1E,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;CAClC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,IAAI,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC3E,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC;CACjC;AAED,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC;AAEzC;;;;GAIG;AACH,qBAAa,gBAAgB;;IAG3B,YAAY,MAAM,EAAE,SAAS,EAE5B;IAED,SAAS,IAAI,OAAO,CAAC,SAAS,OAAO,EAAE,CAAC,CAEvC;IAED,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,GAAE,UAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAE9E;IAED,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAE9C;IAED,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAE5D;CACF"}

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * Coordinates MCP operations without knowing about A2UI, React Native, or any
+ * other renderer. It deliberately routes declared actions instead of loading
+ * executable code from a server.
+ */
+export class McpNativeRuntime {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    listTools() {
+        return this.#client.listTools();
+    }
+    callTool(name, arguments_ = {}) {
+        return this.#client.callTool(name, arguments_);
+    }
+    readResource(uri) {
+        return this.#client.readResource(uri);
+    }
+    dispatch(action) {
+        return this.callTool(action.name, action.arguments ?? {});
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiDA;;;;GAIG;AACH,MAAM,OAAO,gBAAgB;IAClB,OAAO,CAAY;IAE5B,YAAY,MAAiB;QAC3B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;IAClC,CAAC;IAED,QAAQ,CAAC,IAAY,EAAE,UAAU,GAAe,EAAE;QAChD,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACjD,CAAC;IAED,YAAY,CAAC,GAAW;QACtB,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IACxC,CAAC;IAED,QAAQ,CAAC,MAAuB;QAC9B,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;CACF"}

package/package.json

@@ -1,12 +1,38 @@
 {
   "name": "@mcp-native/core",
-  "version": "0.0.1",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "0.0.3",
+  "description": "Protocol-independent runtime primitives for MCP Native.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "runtime",
+    "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 - core package"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pablospaniard/mcp-native.git",
+    "directory": "packages/core"
+  },
+  "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"
+  }
 }

package/index.js

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