@modern-js/plugin-mcp-apps 0.0.0-canary-20260924035651

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-present Modern.js
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# Modern.js MCP Apps plugin (experimental)
+
+场景化接入与调试见 [MCP Apps 使用指南](../../../docs/guides/mcp-apps-usage.md)，包含独立 Hono、可选 MF 和 ngrok。
+
+```ts
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { bffPlugin } from '@modern-js/plugin-bff';
+import { mcpAppsPlugin } from '@modern-js/plugin-mcp-apps';
+
+export default defineConfig({
+  bff: { prefix: '/mcp' },
+  plugins: [appTools(), bffPlugin(), mcpAppsPlugin()],
+});
+```
+
+The plugin compiles MCP definitions and handlers and binds artifacts during BFF
+initialization. HTTP routing belongs to BFF; add the following API entry and install `@modern-js/plugin-bff` and
+`@modern-js/mcp-apps` in dependencies.
+
+```ts
+// api/lambda/index.ts
+import { mcpApps } from '@modern-js/plugin-mcp-apps/bff';
+
+export const { POST, GET, DELETE, PUT, PATCH, OPTIONS } = mcpApps();
+```
+
+For an existing BFF application, keep its prefix and put the route in
+`api/lambda/mcp.ts` (for example `/api/mcp`). Do not register BFF twice.
+Pass `serverInfo` or `onError` to `mcpApps()`. The integration binds the artifact
+using the BFF runtime context; route depth, custom output directories and CJS/ESM
+API modules do not require application-level path resolution. Export the returned
+functions directly so BFF can recognize them; apply authentication in BFF middleware.
+For manually hosted artifacts, the lower-level `@modern-js/mcp-apps/bff` adapter
+remains available with explicit root/entry options.
+
+## Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `config` | `mcp_apps.ts` | Trusted definition path, relative to project root |
+| `tsconfig` | esbuild's nearest tsconfig | Config/handler compilation settings |
+| `alias` | None | Explicit static server import aliases; tsconfig paths also work |
+
+`modern dev` bundles the definition and local handlers into the framework internal MCP directory (normally `node_modules/.modern-js/mcp-apps/`). Config, handler and imported source changes trigger debounced
+recompilation. A new module generation is published atomically after successful
+compilation; invalid changes log an error and retain the last working generation.
+Development uses a development React renderer; production uses a production
+renderer, so dev-compiled remote JSX runs against a matching React dispatcher.
+The watcher is disposed on CLI exit/restart. Artifact revisions cancel obsolete
+requests when a new generation is loaded. BFF owns API runtime reloads.
+
+`modern build` emits `dist/mcp-apps/`, including compiled handler dependencies,
+the definition entry, and packaged resource HTML. `modern serve` uses those files,
+not source modules. `modern deploy` includes the same artifacts in `.output/`.
+Both CJS and ESM application configurations are supported by the package exports;
+the generated MCP server modules are ESM on Node 20+.
+
+Configuration is evaluated at runtime so remote URLs can depend on environment
+variables. Local handler module references must be unchanged between build and
+runtime; changing that set requires rebuilding. The compiler bundles imported
+local code/JSON; separately read files, native addons and other runtime assets
+still need application deployment handling.
+
+## UI and server separation
+
+UI continues to use existing MF/Vmok exposes and manifests. The integrated endpoint uses BFF and does not require a UI entry or React rendering. The `mcp-server`
+template uses an `api/` directory with no `src/` to select Modern.js API-only mode.
+For UI integration, use the `mcp-apps` template or an existing federation setup.
+
+The underlying core is also usable without app-tools: see
+`examples/mcp-apps-modern` and the [Hono adapter documentation](../../toolkit/mcp-apps/README.md#default-local-view-and-hono). For a local integrated app,
+run `pnpm --filter @examples/mcp-apps-modern dev` in this repository after building
+the core and this plugin.
+
+## HTTP behavior
+
+The MCP endpoint is a BFF API route. Register authentication/origin policy before
+BFF dispatch. The adapter rebuilds the HTTP request from the already parsed BFF
+input and returns the SDK Response directly, including notification status 202.
+Handler `context.context` is the request's Hono Context, allowing access to
+middleware-provided identity; contexts are isolated between concurrent requests.
+The transport remains stateless and POST-only; GET/DELETE return 405.
+
+No server plugin `onClose` hook is assumed. Per-request transports are released
+by the core, request disconnects abort handlers, and compiler watchers belong to
+the CLI lifecycle. Custom `server/modern.server.ts` middleware and ordinary pages
+remain independent of MCP registration.
+
+## Tests
+
+```sh
+pnpm --filter @modern-js/mcp-apps build
+pnpm --filter @modern-js/plugin-mcp-apps build
+pnpm --filter @modern-js/plugin-mcp-apps test
+pnpm --filter tests test:framework integration/mcp-apps/tests/index.test.ts --retry=0
+```
+
+## Local views and Hono
+
+The default template uses local `view.module` components, compiled into standalone
+HTML in `dist/mcp-apps/`. MF is selected explicitly with `--template mcp-apps --mf`.
+The BFF runtime uses `@modern-js/mcp-apps/bff` internally; standalone Hono uses
+`@modern-js/mcp-apps/hono`. Both share the artifact loader and SDK transport. UI source changes participate in MCP development recompilation.
+
+The legacy `server-plugin` export remains available for explicit Web Server
+integration, but `mcpAppsPlugin()` no longer installs it or registers HTTP routes.
+
+Include `ts-node` (`^10.9.2`) in devDependencies for BFF TypeScript loading and
+API module hot reload on Node 20+. For ESM projects, use `"type": "module"` and
+TypeScript `module: "esnext"`, `moduleResolution: "bundler"` together.

package/dist/cjs/bff-runtime.cjs

@@ -0,0 +1,92 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, getters, values)=>{
+        var define = (defs, kind)=>{
+            for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+                enumerable: true,
+                [kind]: defs[key]
+            });
+        };
+        define(getters, "get");
+        define(values, "value");
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    default: ()=>mcpBffRuntime
+});
+const bff_namespaceObject = require("@modern-js/mcp-apps/bff");
+const server_core_namespaceObject = require("@modern-js/server-core");
+const MCP_BFF_ENDPOINT = Symbol.for('@modern-js/plugin-mcp-apps/bff');
+function mcpBffRuntime(options) {
+    return {
+        name: '@modern-js/plugin-mcp-apps/bff-runtime',
+        pre: [
+            '@modern-js/plugin-bff'
+        ],
+        required: [
+            '@modern-js/plugin-bff'
+        ],
+        setup (api) {
+            const bind = ()=>{
+                const ctx = api.getServerContext();
+                const root = options.development ? ctx.appDirectory : ctx.distDirectory;
+                if (!root) throw new Error('MCP Apps requires a BFF application directory');
+                const handlers = new Map();
+                const infos = ctx.apiHandlerInfos ?? [];
+                const apiHandlerInfos = infos.map((info)=>{
+                    const endpointOptions = Reflect.get(info.handler, MCP_BFF_ENDPOINT);
+                    if (!endpointOptions) return info;
+                    let handler = handlers.get(info.handler);
+                    if (!handler) {
+                        const handle = (0, bff_namespaceObject.createMcpBffHandler)({
+                            ...endpointOptions,
+                            root,
+                            development: options.development,
+                            entry: options.development ? options.devEntry : options.entry
+                        });
+                        handler = (input)=>handle(input, (0, server_core_namespaceObject.useHonoContext)());
+                        handlers.set(info.handler, handler);
+                    }
+                    return {
+                        ...info,
+                        handler
+                    };
+                });
+                api.updateServerContext({
+                    ...ctx,
+                    apiHandlerInfos
+                });
+            };
+            api.prepareApiServer((input, next)=>{
+                bind();
+                next(input);
+            });
+            api.onReset(({ event })=>{
+                if ('file-change' === event.type) bind();
+            });
+        }
+    };
+}
+exports["default"] = __webpack_exports__["default"];
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "default"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/cjs/bff.cjs

@@ -0,0 +1,56 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, getters, values)=>{
+        var define = (defs, kind)=>{
+            for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+                enumerable: true,
+                [kind]: defs[key]
+            });
+        };
+        define(getters, "get");
+        define(values, "value");
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    mcpApps: ()=>mcpApps
+});
+const MCP_BFF_ENDPOINT = Symbol.for('@modern-js/plugin-mcp-apps/bff');
+function mcpApps(options = {}) {
+    const endpoint = (_input)=>{
+        throw new Error('MCP endpoint is not initialized. Enable bffPlugin() and mcpAppsPlugin(), and export the handlers returned by mcpApps() from an API route.');
+    };
+    Object.defineProperty(endpoint, MCP_BFF_ENDPOINT, {
+        value: options
+    });
+    return {
+        POST: endpoint,
+        GET: endpoint,
+        DELETE: endpoint,
+        PUT: endpoint,
+        PATCH: endpoint,
+        OPTIONS: endpoint
+    };
+}
+exports.mcpApps = __webpack_exports__.mcpApps;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "mcpApps"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/cjs/cli.cjs

@@ -0,0 +1,154 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.n = (module)=>{
+        var getter = module && module.__esModule ? ()=>module['default'] : ()=>module;
+        __webpack_require__.d(getter, {
+            a: getter
+        });
+        return getter;
+    };
+})();
+(()=>{
+    __webpack_require__.d = (exports1, getters, values)=>{
+        var define = (defs, kind)=>{
+            for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+                enumerable: true,
+                [kind]: defs[key]
+            });
+        };
+        define(getters, "get");
+        define(values, "value");
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    default: ()=>cli,
+    mcpAppsPlugin: ()=>mcpAppsPlugin
+});
+const external_node_path_namespaceObject = require("node:path");
+var external_node_path_default = /*#__PURE__*/ __webpack_require__.n(external_node_path_namespaceObject);
+const build_namespaceObject = require("@modern-js/mcp-apps/build");
+const utils_namespaceObject = require("@modern-js/utils");
+const mcpAppsPlugin = (options = {})=>({
+        name: '@modern-js/plugin-mcp-apps',
+        required: [
+            '@modern-js/plugin-bff'
+        ],
+        setup (api) {
+            let dependencies = new Set();
+            let watcher;
+            let timer;
+            let pending = Promise.resolve();
+            let closed = false;
+            let rebuildFailed = false;
+            const paths = ()=>{
+                const ctx = api.getAppContext();
+                return {
+                    root: ctx.appDirectory,
+                    source: external_node_path_default().resolve(ctx.appDirectory, options.config ?? 'mcp_apps.ts'),
+                    devOut: external_node_path_default().join(ctx.internalDirectory, 'mcp-apps'),
+                    prodOut: external_node_path_default().join(ctx.distDirectory, 'mcp-apps')
+                };
+            };
+            const compile = async (dev)=>{
+                const { root, source, devOut, prodOut } = paths();
+                const result = await (0, build_namespaceObject.compileMcpApps)({
+                    configPath: source,
+                    outDir: dev ? devOut : prodOut,
+                    tsconfig: options.tsconfig ? external_node_path_default().resolve(root, options.tsconfig) : void 0,
+                    alias: options.alias,
+                    development: dev
+                });
+                dependencies = new Set(result.dependencies.map((file)=>external_node_path_default().resolve(file)));
+                rebuildFailed = false;
+                if (dev) watcher?.add([
+                    ...dependencies
+                ]);
+                if (dev) utils_namespaceObject.logger.info('[MCP Apps] definition and handlers ready');
+            };
+            const close = async ()=>{
+                closed = true;
+                clearTimeout(timer);
+                await watcher?.close();
+                await pending;
+            };
+            api.onBeforeExit(close);
+            api.onBeforeRestart(close);
+            api.onBeforeDev(async ()=>{
+                closed = false;
+                await compile(true);
+                const { root, devOut, prodOut } = paths();
+                watcher = utils_namespaceObject.chokidar.watch([
+                    root,
+                    ...dependencies
+                ], {
+                    ignoreInitial: true,
+                    ignored: [
+                        /[\\/]node_modules(?:[\\/]|$)/,
+                        /[\\/]\.git(?:[\\/]|$)/,
+                        external_node_path_default().join(root, '.output'),
+                        devOut,
+                        prodOut,
+                        external_node_path_default().dirname(prodOut)
+                    ]
+                });
+                watcher.on('error', (error)=>utils_namespaceObject.logger.error('[MCP Apps] watcher failed', error));
+                watcher.on('all', (event, file)=>{
+                    if (closed || !dependencies.has(external_node_path_default().resolve(file)) && !(rebuildFailed && 'add' === event)) return;
+                    if (!dependencies.has(external_node_path_default().resolve(file)) && !/\.(?:[cm]?[jt]sx?|json)$/.test(file)) return;
+                    clearTimeout(timer);
+                    timer = setTimeout(()=>{
+                        pending = pending.then(async ()=>{
+                            if (!closed) await compile(true);
+                        }).catch((error)=>{
+                            rebuildFailed = true;
+                            utils_namespaceObject.logger.error('[MCP Apps] rebuild failed; keeping last successful build', error);
+                        });
+                    }, 60);
+                });
+            });
+            api.onAfterBuild(()=>compile(false));
+            api._internalServerPlugins(({ plugins })=>{
+                const { root, devOut } = paths();
+                plugins.push({
+                    name: '@modern-js/plugin-mcp-apps/bff-runtime',
+                    options: {
+                        development: [
+                            'dev',
+                            'start'
+                        ].includes(api.getAppContext().command),
+                        devEntry: external_node_path_default().relative(root, external_node_path_default().join(devOut, 'mcp_apps.mjs')).split(external_node_path_default().sep).join('/'),
+                        entry: 'mcp-apps/mcp_apps.mjs'
+                    }
+                });
+                return {
+                    plugins
+                };
+            });
+        }
+    });
+const cli = mcpAppsPlugin;
+exports["default"] = __webpack_exports__["default"];
+exports.mcpAppsPlugin = __webpack_exports__.mcpAppsPlugin;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "default",
+    "mcpAppsPlugin"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/cjs/server.cjs

@@ -0,0 +1,96 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.n = (module)=>{
+        var getter = module && module.__esModule ? ()=>module['default'] : ()=>module;
+        __webpack_require__.d(getter, {
+            a: getter
+        });
+        return getter;
+    };
+})();
+(()=>{
+    __webpack_require__.d = (exports1, getters, values)=>{
+        var define = (defs, kind)=>{
+            for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+                enumerable: true,
+                [kind]: defs[key]
+            });
+        };
+        define(getters, "get");
+        define(values, "value");
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    createArtifactHandler: ()=>server_namespaceObject.createArtifactHandler,
+    default: ()=>mcpAppsServerPlugin
+});
+const external_node_path_namespaceObject = require("node:path");
+var external_node_path_default = /*#__PURE__*/ __webpack_require__.n(external_node_path_namespaceObject);
+const hono_namespaceObject = require("@modern-js/mcp-apps/hono");
+const server_namespaceObject = require("@modern-js/mcp-apps/server");
+function endpointPath(endpoint = '/mcp') {
+    if (!/^\/(?:[a-zA-Z0-9_.~-]+\/?)+$/.test(endpoint) || endpoint.endsWith('/') || endpoint.split('/').some((part)=>'.' === part || '..' === part)) throw new Error('MCP endpoint must be an exact absolute path without wildcards, parameters or trailing slash');
+    return endpoint;
+}
+function mcpAppsServerPlugin(options = {}) {
+    const endpoint = endpointPath(options.endpoint);
+    return {
+        name: '@modern-js/plugin-mcp-apps/server-plugin',
+        setup (api) {
+            let handler;
+            api.onPrepare(()=>{
+                const ctx = api.getServerContext();
+                const development = options.development ?? 'development' === process.env.NODE_ENV;
+                const base = development ? ctx.appDirectory : ctx.distDirectory;
+                if (!base) throw new Error('MCP Apps requires a server application/artifact directory');
+                const entry = external_node_path_default().resolve(base, development && options.devEntry ? options.devEntry : options.entry ?? 'mcp-apps/mcp_apps.mjs');
+                handler = (0, server_namespaceObject.createArtifactHandler)(entry, {
+                    development,
+                    serverInfo: options.serverInfo
+                });
+                ctx.middlewares.push({
+                    name: 'mcp-apps',
+                    path: endpoint,
+                    method: 'all',
+                    order: 'post',
+                    before: [
+                        'bind-bff',
+                        'render'
+                    ],
+                    handler: (0, hono_namespaceObject.mcpApps)({
+                        handler,
+                        endpoint
+                    })
+                });
+            });
+            api.onReset(({ event })=>{
+                if ('file-change' === event.type) handler?.reset();
+            });
+        }
+    };
+}
+exports.createArtifactHandler = __webpack_exports__.createArtifactHandler;
+exports["default"] = __webpack_exports__["default"];
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "createArtifactHandler",
+    "default"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/esm-node/bff-runtime.mjs

@@ -0,0 +1,54 @@
+import { createMcpBffHandler } from "@modern-js/mcp-apps/bff";
+import { useHonoContext } from "@modern-js/server-core";
+import { MCP_BFF_ENDPOINT } from "./z~0.mjs";
+function mcpBffRuntime(options) {
+    return {
+        name: '@modern-js/plugin-mcp-apps/bff-runtime',
+        pre: [
+            '@modern-js/plugin-bff'
+        ],
+        required: [
+            '@modern-js/plugin-bff'
+        ],
+        setup (api) {
+            const bind = ()=>{
+                const ctx = api.getServerContext();
+                const root = options.development ? ctx.appDirectory : ctx.distDirectory;
+                if (!root) throw new Error('MCP Apps requires a BFF application directory');
+                const handlers = new Map();
+                const infos = ctx.apiHandlerInfos ?? [];
+                const apiHandlerInfos = infos.map((info)=>{
+                    const endpointOptions = Reflect.get(info.handler, MCP_BFF_ENDPOINT);
+                    if (!endpointOptions) return info;
+                    let handler = handlers.get(info.handler);
+                    if (!handler) {
+                        const handle = createMcpBffHandler({
+                            ...endpointOptions,
+                            root,
+                            development: options.development,
+                            entry: options.development ? options.devEntry : options.entry
+                        });
+                        handler = (input)=>handle(input, useHonoContext());
+                        handlers.set(info.handler, handler);
+                    }
+                    return {
+                        ...info,
+                        handler
+                    };
+                });
+                api.updateServerContext({
+                    ...ctx,
+                    apiHandlerInfos
+                });
+            };
+            api.prepareApiServer((input, next)=>{
+                bind();
+                next(input);
+            });
+            api.onReset(({ event })=>{
+                if ('file-change' === event.type) bind();
+            });
+        }
+    };
+}
+export default mcpBffRuntime;

package/dist/esm-node/bff.mjs

@@ -0,0 +1,18 @@
+import { MCP_BFF_ENDPOINT } from "./z~0.mjs";
+function mcpApps(options = {}) {
+    const endpoint = (_input)=>{
+        throw new Error('MCP endpoint is not initialized. Enable bffPlugin() and mcpAppsPlugin(), and export the handlers returned by mcpApps() from an API route.');
+    };
+    Object.defineProperty(endpoint, MCP_BFF_ENDPOINT, {
+        value: options
+    });
+    return {
+        POST: endpoint,
+        GET: endpoint,
+        DELETE: endpoint,
+        PUT: endpoint,
+        PATCH: endpoint,
+        OPTIONS: endpoint
+    };
+}
+export { mcpApps };

package/dist/esm-node/cli.mjs

@@ -0,0 +1,104 @@
+import node_path from "node:path";
+import { compileMcpApps } from "@modern-js/mcp-apps/build";
+import { chokidar, logger } from "@modern-js/utils";
+const mcpAppsPlugin = (options = {})=>({
+        name: '@modern-js/plugin-mcp-apps',
+        required: [
+            '@modern-js/plugin-bff'
+        ],
+        setup (api) {
+            let dependencies = new Set();
+            let watcher;
+            let timer;
+            let pending = Promise.resolve();
+            let closed = false;
+            let rebuildFailed = false;
+            const paths = ()=>{
+                const ctx = api.getAppContext();
+                return {
+                    root: ctx.appDirectory,
+                    source: node_path.resolve(ctx.appDirectory, options.config ?? 'mcp_apps.ts'),
+                    devOut: node_path.join(ctx.internalDirectory, 'mcp-apps'),
+                    prodOut: node_path.join(ctx.distDirectory, 'mcp-apps')
+                };
+            };
+            const compile = async (dev)=>{
+                const { root, source, devOut, prodOut } = paths();
+                const result = await compileMcpApps({
+                    configPath: source,
+                    outDir: dev ? devOut : prodOut,
+                    tsconfig: options.tsconfig ? node_path.resolve(root, options.tsconfig) : void 0,
+                    alias: options.alias,
+                    development: dev
+                });
+                dependencies = new Set(result.dependencies.map((file)=>node_path.resolve(file)));
+                rebuildFailed = false;
+                if (dev) watcher?.add([
+                    ...dependencies
+                ]);
+                if (dev) logger.info('[MCP Apps] definition and handlers ready');
+            };
+            const close = async ()=>{
+                closed = true;
+                clearTimeout(timer);
+                await watcher?.close();
+                await pending;
+            };
+            api.onBeforeExit(close);
+            api.onBeforeRestart(close);
+            api.onBeforeDev(async ()=>{
+                closed = false;
+                await compile(true);
+                const { root, devOut, prodOut } = paths();
+                watcher = chokidar.watch([
+                    root,
+                    ...dependencies
+                ], {
+                    ignoreInitial: true,
+                    ignored: [
+                        /[\\/]node_modules(?:[\\/]|$)/,
+                        /[\\/]\.git(?:[\\/]|$)/,
+                        node_path.join(root, '.output'),
+                        devOut,
+                        prodOut,
+                        node_path.dirname(prodOut)
+                    ]
+                });
+                watcher.on('error', (error)=>logger.error('[MCP Apps] watcher failed', error));
+                watcher.on('all', (event, file)=>{
+                    if (closed || !dependencies.has(node_path.resolve(file)) && !(rebuildFailed && 'add' === event)) return;
+                    if (!dependencies.has(node_path.resolve(file)) && !/\.(?:[cm]?[jt]sx?|json)$/.test(file)) return;
+                    clearTimeout(timer);
+                    timer = setTimeout(()=>{
+                        pending = pending.then(async ()=>{
+                            if (!closed) await compile(true);
+                        }).catch((error)=>{
+                            rebuildFailed = true;
+                            logger.error('[MCP Apps] rebuild failed; keeping last successful build', error);
+                        });
+                    }, 60);
+                });
+            });
+            api.onAfterBuild(()=>compile(false));
+            api._internalServerPlugins(({ plugins })=>{
+                const { root, devOut } = paths();
+                plugins.push({
+                    name: '@modern-js/plugin-mcp-apps/bff-runtime',
+                    options: {
+                        development: [
+                            'dev',
+                            'start'
+                        ].includes(api.getAppContext().command),
+                        devEntry: node_path.relative(root, node_path.join(devOut, 'mcp_apps.mjs')).split(node_path.sep).join('/'),
+                        entry: 'mcp-apps/mcp_apps.mjs'
+                    }
+                });
+                return {
+                    plugins
+                };
+            });
+        }
+    });
+const cli = mcpAppsPlugin;
+export default cli;
+export { mcpAppsPlugin };

package/dist/esm-node/server.mjs

@@ -0,0 +1,46 @@
+import node_path from "node:path";
+import { mcpApps } from "@modern-js/mcp-apps/hono";
+import { createArtifactHandler } from "@modern-js/mcp-apps/server";
+function endpointPath(endpoint = '/mcp') {
+    if (!/^\/(?:[a-zA-Z0-9_.~-]+\/?)+$/.test(endpoint) || endpoint.endsWith('/') || endpoint.split('/').some((part)=>'.' === part || '..' === part)) throw new Error('MCP endpoint must be an exact absolute path without wildcards, parameters or trailing slash');
+    return endpoint;
+}
+function mcpAppsServerPlugin(options = {}) {
+    const endpoint = endpointPath(options.endpoint);
+    return {
+        name: '@modern-js/plugin-mcp-apps/server-plugin',
+        setup (api) {
+            let handler;
+            api.onPrepare(()=>{
+                const ctx = api.getServerContext();
+                const development = options.development ?? 'development' === process.env.NODE_ENV;
+                const base = development ? ctx.appDirectory : ctx.distDirectory;
+                if (!base) throw new Error('MCP Apps requires a server application/artifact directory');
+                const entry = node_path.resolve(base, development && options.devEntry ? options.devEntry : options.entry ?? 'mcp-apps/mcp_apps.mjs');
+                handler = createArtifactHandler(entry, {
+                    development,
+                    serverInfo: options.serverInfo
+                });
+                ctx.middlewares.push({
+                    name: 'mcp-apps',
+                    path: endpoint,
+                    method: 'all',
+                    order: 'post',
+                    before: [
+                        'bind-bff',
+                        'render'
+                    ],
+                    handler: mcpApps({
+                        handler,
+                        endpoint
+                    })
+                });
+            });
+            api.onReset(({ event })=>{
+                if ('file-change' === event.type) handler?.reset();
+            });
+        }
+    };
+}
+export default mcpAppsServerPlugin;
+export { createArtifactHandler };

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

@@ -0,0 +1,2 @@
+const MCP_BFF_ENDPOINT = Symbol.for('@modern-js/plugin-mcp-apps/bff');
+export { MCP_BFF_ENDPOINT };

package/dist/types/bff-runtime.d.ts

@@ -0,0 +1,4 @@
+import { type ServerPlugin } from '@modern-js/server-core';
+import { type McpAppsBffRuntimeOptions } from './shared.js';
+/** Bind artifacts to BFF-discovered functions. Never registers HTTP middleware. */
+export default function mcpBffRuntime(options: McpAppsBffRuntimeOptions): ServerPlugin;

package/dist/types/bff.d.ts

@@ -0,0 +1,23 @@
+import type { McpBffOptions } from '@modern-js/mcp-apps/bff';
+export type McpEndpointOptions = Pick<McpBffOptions, 'serverInfo' | 'onError'>;
+/** Declare a BFF endpoint. Its compiled artifact is bound by the BFF lifecycle. */
+export declare function mcpApps(options?: McpEndpointOptions): {
+    POST: (_input: {
+        data?: unknown;
+    }) => Promise<Response>;
+    GET: (_input: {
+        data?: unknown;
+    }) => Promise<Response>;
+    DELETE: (_input: {
+        data?: unknown;
+    }) => Promise<Response>;
+    PUT: (_input: {
+        data?: unknown;
+    }) => Promise<Response>;
+    PATCH: (_input: {
+        data?: unknown;
+    }) => Promise<Response>;
+    OPTIONS: (_input: {
+        data?: unknown;
+    }) => Promise<Response>;
+};

package/dist/types/cli.d.ts

@@ -0,0 +1,5 @@
+import type { AppTools, CliPlugin } from '@modern-js/app-tools';
+import type { McpAppsPluginOptions } from './options.js';
+export type { McpAppsPluginOptions } from './options.js';
+export declare const mcpAppsPlugin: (options?: McpAppsPluginOptions) => CliPlugin<AppTools>;
+export default mcpAppsPlugin;

package/dist/types/options.d.ts

@@ -0,0 +1,21 @@
+export interface McpAppsPluginOptions {
+    /** Trusted application definition, relative to the project root. */
+    config?: string;
+    /** Optional tsconfig for config/handler compilation. */
+    tsconfig?: string;
+    /** Static server-only import aliases in addition to tsconfig paths. */
+    alias?: Record<string, string>;
+}
+export interface McpAppsServerOptions {
+    development?: boolean;
+    endpoint?: string;
+    /** Relative to appDirectory, only used in development. */
+    devEntry?: string;
+    /** Relative to distDirectory; serialized into the production launcher. */
+    entry?: string;
+    serverInfo?: {
+        name: string;
+        version: string;
+    };
+}
+export declare function endpointPath(endpoint?: string): string;

package/dist/types/server.d.ts

@@ -0,0 +1,5 @@
+import type { ServerPlugin } from '@modern-js/server-core';
+import { type McpAppsServerOptions } from './options.js';
+export type { McpAppsServerOptions } from './options.js';
+export { createArtifactHandler } from '@modern-js/mcp-apps/server';
+export default function mcpAppsServerPlugin(options?: McpAppsServerOptions): ServerPlugin;

package/dist/types/shared.d.ts

@@ -0,0 +1,8 @@
+export declare const MCP_BFF_ENDPOINT: unique symbol;
+export interface McpAppsBffRuntimeOptions {
+    development: boolean;
+    /** Relative to the project root. */
+    devEntry: string;
+    /** Relative to the compiled output root. */
+    entry: string;
+}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@modern-js/plugin-mcp-apps",
+  "version": "0.0.0-canary-20260924035651",
+  "description": "Modern.js integration for independently deployable MCP Apps",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/web-infra-dev/modern.js",
+    "directory": "packages/cli/plugin-mcp-apps"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/cli.d.ts",
+      "import": "./dist/esm-node/cli.mjs",
+      "require": "./dist/cjs/cli.cjs"
+    },
+    "./server-plugin": {
+      "types": "./dist/types/server.d.ts",
+      "import": "./dist/esm-node/server.mjs",
+      "require": "./dist/cjs/server.cjs"
+    },
+    "./bff": {
+      "types": "./dist/types/bff.d.ts",
+      "import": "./dist/esm-node/bff.mjs",
+      "require": "./dist/cjs/bff.cjs"
+    },
+    "./bff-runtime": {
+      "types": "./dist/types/bff-runtime.d.ts",
+      "import": "./dist/esm-node/bff-runtime.mjs",
+      "require": "./dist/cjs/bff-runtime.cjs"
+    }
+  },
+  "dependencies": {
+    "@modern-js/mcp-apps": "0.0.0-canary-20260924035651",
+    "@modern-js/utils": "0.0.0-canary-20260924035651",
+    "@modern-js/server-core": "0.0.0-canary-20260924035651"
+  },
+  "devDependencies": {
+    "@rslib/core": "1.0.1",
+    "@types/node": "^20",
+    "typescript": "^5",
+    "@scripts/rstest-config": "0.0.0-canary-20260924035651",
+    "@modern-js/app-tools": "0.0.0-canary-20260924035651"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "typesVersions": {
+    "*": {
+      ".": [
+        "dist/types/cli.d.ts"
+      ],
+      "server-plugin": [
+        "dist/types/server.d.ts"
+      ],
+      "bff": [
+        "dist/types/bff.d.ts"
+      ],
+      "bff-runtime": [
+        "dist/types/bff-runtime.d.ts"
+      ]
+    }
+  },
+  "types": "./dist/types/cli.d.ts",
+  "scripts": {
+    "build": "rslib build",
+    "test": "rstest",
+    "typecheck": "tsc --noEmit"
+  }
+}