@modern-js/mcp-apps 3.11.1 → 3.11.2

package/README.md

@@ -25,7 +25,7 @@ Declare React cards in `mcp-views.json` and enable `mcpAppsPlugin({ views: './mc
 }
 ```
 
-Component paths resolve relative to the JSON file. Components must have a default export. MF exposes refer to this application's MF manifest output and must also have a default component export. Local cards are added as application entries and reuse the framework's multi-entry compilation, including its loaders, styles and build plugins. Only the MF shell uses a separate Rsbuild compilation with the application's React dependencies, with its startup scripts and styles inlined. The plugin emits `dist/mcp-apps/ui-manifest.json` and never registers HTTP routes.
+Component paths resolve relative to the JSON file. Components must have a default export. MF exposes refer to this application's MF manifest output and must also have a default component export. `{ "remote": "https://host/mf-manifest.json", "expose": "./Name" }` refers to a deployed remote instead. Set `remote` at the top level alongside `csp` to share it across all expose views, for example `{ "remote": "https://host/mf-manifest.json", "views": { "todos": { "expose": "./Todos" }, "stats": { "expose": "./Stats" } } }`. A view-level `remote` overrides this default. Component paths remain local. Without either remote setting, exposes refer to this application. With a top-level `remote`, expose views in the same config cannot refer to this application's exposes, so set `remote` per view to mix both. The URL must point to the remote's manifest, with a path ending in `.json`, and the runtime reads the remote's name from it. The shell loads the remote manifest when the card opens, so republishing the remote needs no MCP server rebuild. Its exposes are not checked at build time, and the application needs no MF plugin. The manifest origin is added to CSP. Declare other origins serving the remote's chunks in `csp`. Local cards are added as application entries and reuse the framework's multi-entry compilation, including its loaders, styles and build plugins. Only the MF shell uses a separate Rsbuild compilation with the application's React dependencies, with its startup scripts and styles inlined. The plugin emits `dist/mcp-apps/ui-manifest.json` and never registers HTTP routes.
 
 - `mf.manifestFile` is the MF manifest filename in the web build output. It defaults to `mf-manifest.json` and must match exactly one emitted file.
 - `mf.runtime` is the module, resolved from the application, that the MF shell imports `createInstance` from. It defaults to `@module-federation/enhanced/runtime`.

package/dist/cjs/cli.cjs

@@ -71,8 +71,13 @@ function validateUiMetadata(value) {
 function validateViewsConfig(value) {
     if (!isRecord(value) || !isRecord(value.views)) throw new Error('mcp-views.json requires a views object');
     validateUiMetadata(value);
+    if (void 0 !== value.remote) {
+        if ('string' != typeof value.remote) throw new Error('remote must be a string');
+        assertRemoteManifest(value.remote);
+    }
     for (const key of Object.keys(value))if (![
         'views',
+        'remote',
         'csp',
         'prefersBorder',
         'permissions',
@@ -81,10 +86,28 @@ function validateViewsConfig(value) {
     for (const [name, view] of Object.entries(value.views)){
         if (!name.trim()) throw new Error('View names must be non-empty');
         if (!('string' == typeof view && view.trim())) {
-            if (!(isRecord(view) && 'string' == typeof view.expose && view.expose.startsWith('./')) || 1 !== Object.keys(view).length) throw new Error(`Invalid view: ${name}. Use a component path or { expose: './Name' }`);
+            if (isRecord(view) && 'string' == typeof view.expose && view.expose.startsWith('./') && Object.keys(view).every((key)=>'expose' === key || 'remote' === key)) {
+                if (!('remote' in view)) continue;
+                if ('string' == typeof view.remote) {
+                    assertRemoteManifest(view.remote);
+                    continue;
+                }
+            }
+            throw new Error(`Invalid view: ${name}. Use a component path, { expose: './Name' } or { remote: 'https://host/mf-manifest.json', expose: './Name' }`);
         }
     }
 }
+function assertRemoteManifest(remote) {
+    if (!/^https?:\/\//.test(remote) || !assertHttpUrl(remote).pathname.endsWith('.json')) throw new Error(`Invalid MF remote: ${remote}. Use https://host/mf-manifest.json`);
+}
+function assertHttpUrl(source) {
+    const url = new URL(source);
+    if (![
+        'http:',
+        'https:'
+    ].includes(url.protocol) || url.username || url.password) throw new Error(`Invalid UI URL: ${source}`);
+    return url;
+}
 const external_node_crypto_namespaceObject = require("node:crypto");
 function assetPrefixOrigin(prefix) {
     if ('string' != typeof prefix) return;
@@ -122,7 +145,7 @@ function createUiManifest(config, prefix, mf, csp) {
     if (void 0 !== csp) validateUiMetadata({
         csp
     });
-    const { views, ...metadata } = config;
+    const { views, remote: defaultRemote, ...metadata } = config;
     const assetOrigin = assetPrefixOrigin(prefix);
     const mergedCsp = mergeCsp(metadata.csp, csp, assetOrigin ? {
         resourceDomains: [
@@ -145,23 +168,36 @@ function createUiManifest(config, prefix, mf, csp) {
         remotes: Object.create(null),
         views: Object.create(null)
     };
-    for (const [name, source] of Object.entries(views))if ('string' == typeof source) manifest.views[name] = {
-        html: `./ui/${viewEntryName(name)}.html`,
-        ui
-    };
-    else {
-        if (!mf) throw new Error(`View ${name} requires a Module Federation manifest. Enable the MF plugin and manifest output`);
-        if (!mf.manifest.exposes.some((item)=>item.name.replace(/^\.\//, '') === source.expose.slice(2))) throw new Error(`View ${name} references missing MF expose: ${source.expose}`);
-        const assetPath = 'string' == typeof prefix && prefix.startsWith('/') && !prefix.startsWith('//') ? prefix.replace(/^\/+|\/+$/g, '') : '';
-        manifest.remotes[mf.manifest.name] = {
-            entry: [
+    for (const [name, source] of Object.entries(views)){
+        if ('string' == typeof source) {
+            manifest.views[name] = {
+                html: `./ui/${viewEntryName(name)}.html`,
+                ui
+            };
+            continue;
+        }
+        let remote;
+        let entry;
+        const deployedRemote = source.remote ?? defaultRemote;
+        if (void 0 !== deployedRemote) {
+            entry = deployedRemote;
+            remote = `mcp-remote-${(0, external_node_crypto_namespaceObject.createHash)('sha256').update(entry).digest('hex').slice(0, 12)}`;
+        } else {
+            if (!mf) throw new Error(`View ${name} requires a Module Federation manifest. Enable the MF plugin and manifest output`);
+            if (!mf.manifest.exposes.some((item)=>item.name.replace(/^\.\//, '') === source.expose.slice(2))) throw new Error(`View ${name} references missing MF expose: ${source.expose}`);
+            const assetPath = 'string' == typeof prefix && prefix.startsWith('/') && !prefix.startsWith('//') ? prefix.replace(/^\/+|\/+$/g, '') : '';
+            entry = [
                 assetPath,
                 mf.filename
-            ].filter(Boolean).join('/'),
+            ].filter(Boolean).join('/');
+            remote = mf.manifest.name;
+        }
+        manifest.remotes[remote] = {
+            entry,
             shell: './ui/mcp-shell.html'
         };
         manifest.views[name] = {
-            remote: mf.manifest.name,
+            remote,
             expose: source.expose,
             ui
         };
@@ -406,7 +442,7 @@ const mcpAppsPlugin = (options = {})=>({
                             ].includes(ctx.command);
                             const output = external_node_path_default().join(development ? ctx.internalDirectory : ctx.distDirectory, 'mcp-apps');
                             let mf;
-                            if (Object.values(definition.views).some((view)=>'string' != typeof view)) mf = findMfManifest(compilation.getAssets(), options.mf?.manifestFile ?? 'mf-manifest.json');
+                            if (Object.values(definition.views).some((view)=>'string' != typeof view && void 0 === view.remote && void 0 === definition.remote)) mf = findMfManifest(compilation.getAssets(), options.mf?.manifestFile ?? 'mf-manifest.json');
                             const config = api.getNormalizedConfig();
                             const manifest = createUiManifest(definition, development ? config.dev.assetPrefix : config.output.assetPrefix, mf, options.csp);
                             for (const name of localEntries){

package/dist/cjs/server.cjs

@@ -231,7 +231,8 @@ async function registerUiResources(server, options = {}) {
             const config = remote && 'expose' in view ? `<script type="application/json" id="modern-mcp-config">${JSON.stringify({
                 name: view.remote,
                 entry,
-                expose: view.expose
+                expose: view.expose,
+                view: name
             }).replace(/</g, '\\u003c')}</script>` : '';
             html = html.replace(/<head\b[^>]*>/i, (head)=>`${head}<base href="${escapeAttribute(base.href)}">${config}`);
             return {

package/dist/esm/mf-entry.mjs

@@ -41,7 +41,7 @@ function createMfView(config) {
         if (!mod?.default) throw new Error(`Missing default export for ${config.expose}`);
         return {
             default: createMcpView(mod.default, {
-                name: config.name,
+                name: config.view,
                 version: '1.0.0'
             }, mod.mcpCapabilities)
         };

package/dist/esm-node/3~0.mjs

@@ -19,8 +19,13 @@ function validateUiMetadata(value) {
 function validateViewsConfig(value) {
     if (!isRecord(value) || !isRecord(value.views)) throw new Error('mcp-views.json requires a views object');
     validateUiMetadata(value);
+    if (void 0 !== value.remote) {
+        if ('string' != typeof value.remote) throw new Error('remote must be a string');
+        assertRemoteManifest(value.remote);
+    }
     for (const key of Object.keys(value))if (![
         'views',
+        'remote',
         'csp',
         'prefersBorder',
         'permissions',
@@ -29,10 +34,20 @@ function validateViewsConfig(value) {
     for (const [name, view] of Object.entries(value.views)){
         if (!name.trim()) throw new Error('View names must be non-empty');
         if (!('string' == typeof view && view.trim())) {
-            if (!(isRecord(view) && 'string' == typeof view.expose && view.expose.startsWith('./')) || 1 !== Object.keys(view).length) throw new Error(`Invalid view: ${name}. Use a component path or { expose: './Name' }`);
+            if (isRecord(view) && 'string' == typeof view.expose && view.expose.startsWith('./') && Object.keys(view).every((key)=>'expose' === key || 'remote' === key)) {
+                if (!('remote' in view)) continue;
+                if ('string' == typeof view.remote) {
+                    assertRemoteManifest(view.remote);
+                    continue;
+                }
+            }
+            throw new Error(`Invalid view: ${name}. Use a component path, { expose: './Name' } or { remote: 'https://host/mf-manifest.json', expose: './Name' }`);
         }
     }
 }
+function assertRemoteManifest(remote) {
+    if (!/^https?:\/\//.test(remote) || !assertHttpUrl(remote).pathname.endsWith('.json')) throw new Error(`Invalid MF remote: ${remote}. Use https://host/mf-manifest.json`);
+}
 function assertHttpUrl(source) {
     const url = new URL(source);
     if (![

package/dist/esm-node/cli.mjs

@@ -41,7 +41,7 @@ function createUiManifest(config, prefix, mf, csp) {
     if (void 0 !== csp) validateUiMetadata({
         csp
     });
-    const { views, ...metadata } = config;
+    const { views, remote: defaultRemote, ...metadata } = config;
     const assetOrigin = assetPrefixOrigin(prefix);
     const mergedCsp = mergeCsp(metadata.csp, csp, assetOrigin ? {
         resourceDomains: [
@@ -64,23 +64,36 @@ function createUiManifest(config, prefix, mf, csp) {
         remotes: Object.create(null),
         views: Object.create(null)
     };
-    for (const [name, source] of Object.entries(views))if ('string' == typeof source) manifest.views[name] = {
-        html: `./ui/${viewEntryName(name)}.html`,
-        ui
-    };
-    else {
-        if (!mf) throw new Error(`View ${name} requires a Module Federation manifest. Enable the MF plugin and manifest output`);
-        if (!mf.manifest.exposes.some((item)=>item.name.replace(/^\.\//, '') === source.expose.slice(2))) throw new Error(`View ${name} references missing MF expose: ${source.expose}`);
-        const assetPath = 'string' == typeof prefix && prefix.startsWith('/') && !prefix.startsWith('//') ? prefix.replace(/^\/+|\/+$/g, '') : '';
-        manifest.remotes[mf.manifest.name] = {
-            entry: [
+    for (const [name, source] of Object.entries(views)){
+        if ('string' == typeof source) {
+            manifest.views[name] = {
+                html: `./ui/${viewEntryName(name)}.html`,
+                ui
+            };
+            continue;
+        }
+        let remote;
+        let entry;
+        const deployedRemote = source.remote ?? defaultRemote;
+        if (void 0 !== deployedRemote) {
+            entry = deployedRemote;
+            remote = `mcp-remote-${createHash('sha256').update(entry).digest('hex').slice(0, 12)}`;
+        } else {
+            if (!mf) throw new Error(`View ${name} requires a Module Federation manifest. Enable the MF plugin and manifest output`);
+            if (!mf.manifest.exposes.some((item)=>item.name.replace(/^\.\//, '') === source.expose.slice(2))) throw new Error(`View ${name} references missing MF expose: ${source.expose}`);
+            const assetPath = 'string' == typeof prefix && prefix.startsWith('/') && !prefix.startsWith('//') ? prefix.replace(/^\/+|\/+$/g, '') : '';
+            entry = [
                 assetPath,
                 mf.filename
-            ].filter(Boolean).join('/'),
+            ].filter(Boolean).join('/');
+            remote = mf.manifest.name;
+        }
+        manifest.remotes[remote] = {
+            entry,
             shell: './ui/mcp-shell.html'
         };
         manifest.views[name] = {
-            remote: mf.manifest.name,
+            remote,
             expose: source.expose,
             ui
         };
@@ -325,7 +338,7 @@ const mcpAppsPlugin = (options = {})=>({
                             ].includes(ctx.command);
                             const output = node_path.join(development ? ctx.internalDirectory : ctx.distDirectory, 'mcp-apps');
                             let mf;
-                            if (Object.values(definition.views).some((view)=>'string' != typeof view)) mf = findMfManifest(compilation.getAssets(), options.mf?.manifestFile ?? 'mf-manifest.json');
+                            if (Object.values(definition.views).some((view)=>'string' != typeof view && void 0 === view.remote && void 0 === definition.remote)) mf = findMfManifest(compilation.getAssets(), options.mf?.manifestFile ?? 'mf-manifest.json');
                             const config = api.getNormalizedConfig();
                             const manifest = createUiManifest(definition, development ? config.dev.assetPrefix : config.output.assetPrefix, mf, options.csp);
                             for (const name of localEntries){

package/dist/esm-node/server.mjs

@@ -140,7 +140,8 @@ async function registerUiResources(server, options = {}) {
             const config = remote && 'expose' in view ? `<script type="application/json" id="modern-mcp-config">${JSON.stringify({
                 name: view.remote,
                 entry,
-                expose: view.expose
+                expose: view.expose,
+                view: name
             }).replace(/</g, '\\u003c')}</script>` : '';
             html = html.replace(/<head\b[^>]*>/i, (head)=>`${head}<base href="${escapeAttribute(base.href)}">${config}`);
             return {

package/dist/types/manifest.d.ts

@@ -1,8 +1,12 @@
 import type { McpUiResourceMeta } from '@modelcontextprotocol/ext-apps';
 export type UiMetadata = McpUiResourceMeta;
 export interface McpViewsConfig extends UiMetadata {
+    /** Default deployed MF remote for expose views. Individual views may override it. */
+    remote?: string;
+    /** A component path, an expose of this application, or an expose of a deployed remote. */
     views: Record<string, string | {
         expose: string;
+        remote?: string;
     }>;
 }
 export interface UiManifest {
@@ -24,5 +28,11 @@ export interface UiManifest {
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
 export declare function validateUiMetadata(value: unknown): asserts value is UiMetadata;
 export declare function validateViewsConfig(value: unknown): asserts value is McpViewsConfig;
+/**
+ * A deployed MF remote must be a manifest URL. The MF runtime finds the
+ * container through the manifest only for `.json` entries. Any other entry
+ * would need the remote's real MF name.
+ */
+export declare function assertRemoteManifest(remote: string): void;
 export declare function assertHttpUrl(source: string): URL;
 export declare function validateUiManifest(value: unknown): asserts value is UiManifest;

package/dist/types/ui/mf.d.ts

@@ -3,6 +3,8 @@ export interface MfViewConfig {
     name: string;
     entry: string;
     expose: string;
+    /** The view name, reported to the host as the app name like local cards. */
+    view: string;
 }
 /** Executed in the application build, so the shell and exposes share its React. */
 export declare function createMfView(config: MfViewConfig): () => JsxRuntime.JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modern-js/mcp-apps",
-  "version": "3.11.1",
+  "version": "3.11.2",
   "description": "Build, serve and render MCP Apps in Modern.js applications",
   "license": "MIT",
   "homepage": "https://modernjs.dev",
@@ -51,7 +51,7 @@
     "@module-federation/enhanced": "^2.0.0",
     "@modelcontextprotocol/server": "^2.3.1",
     "@modelcontextprotocol/ext-apps": "^2.0.4",
-    "@modern-js/server-runtime": "^3.11.1"
+    "@modern-js/server-runtime": "^3.11.2"
   },
   "peerDependenciesMeta": {
     "@module-federation/enhanced": {
@@ -74,9 +74,9 @@
     "zod": "^4.2.0",
     "@modelcontextprotocol/server": "2.3.1",
     "@modelcontextprotocol/ext-apps": "2.0.4",
-    "@scripts/rstest-config": "2.66.5",
-    "@modern-js/app-tools": "3.11.1",
-    "@modern-js/server-runtime": "3.11.1"
+    "@scripts/rstest-config": "2.66.6",
+    "@modern-js/server-runtime": "3.11.2",
+    "@modern-js/app-tools": "3.11.2"
   },
   "publishConfig": {
     "access": "public",