MCP Apps
Modern.js 可以把 React 组件构建为 MCP 卡片。UI 构建与服务端通过 ui-manifest.json 关联,服务端直接使用官方 MCP SDK。
创建项目
使用包含 MCP Apps 支持的版本。运行 pnpm dev 后,MCP 地址为 /api/mcp。
构建插件、服务端插件、服务端适配器和卡片运行时都由 @modern-js/mcp-apps 提供,分别从 ./cli、./server-plugin、./server 和 ./react 导入。应用需安装 peer 依赖 react、react-dom、@modelcontextprotocol/server 和 @modelcontextprotocol/ext-apps,让卡片使用应用的 React,工具、资源注册和 HTTP 处理使用应用安装的 SDK。@modern-js/server-runtime 和 @module-federation/enhanced 是可选 peer,分别作为 BFF handler 获取请求上下文和 MF shell 运行时的默认实现。脚手架模板已声明这些依赖。
声明卡片
创建 mcp-views.json。字符串路径相对该 JSON 文件解析。对象可以引用本项目 MF 配置中已有的 expose,也可以通过 remote 引用已部署的远程模块,见下文。
在 modern.config.ts 中从 @modern-js/mcp-apps/cli 导入并加入 mcpAppsPlugin({ views: './mcp-views.json' })。本地卡片仅需该插件,MF 卡片还需启用 @module-federation/modern-js-v3 插件并开启 manifest 输出。插件读取实际 MF 构建产物,验证 expose 存在,生成项目自身构建的 shell。
插件按文件名在 web 构建产物中查找 MF manifest,默认为 mf-manifest.json,必须恰好匹配一个文件。shell 默认从 @module-federation/enhanced/runtime 导入 createInstance。使用其他 MF 实现时,可以通过 mf 参数替换:
引用已部署的远程模块
卡片由另一个项目作为 MF 远程模块发布时,用 remote 指定远程模块的 manifest 地址:
顶层 remote 与 csp 同级,供所有 expose 视图共用。单个视图可配置 remote 覆盖默认值。字符串路径仍引用本地组件。顶层和视图都未配置 remote 时,expose 引用本项目。配置顶层 remote 后,同一份配置中的 expose 视图无法再引用本项目的 expose。需要混用时,不配置顶层 remote,只在引用远程模块的视图上配置。
- 地址必须是绝对的 HTTP(S) 地址,路径以
.json结尾。不支持直接引用remoteEntry.js等非 manifest 入口 - 不需要填写远程模块的名称,运行时从 manifest 读取
- shell 在卡片打开时读取远程 manifest 并加载 expose。远程模块重新发布后,MCP 服务无需重新构建或重启。构建时不检查 expose 是否存在,缺失时卡片显示加载错误
- 本项目不需要启用 MF 插件,但需要安装
mf.runtime指定的运行时。远程模块使用其他 MF 实现时,按上文设置mf.runtime - manifest 所在的 origin 会自动加入 CSP。远程模块的脚本和样式由其他域名(例如 CDN)提供时,需要在
csp.resourceDomains中声明。manifest 和脚本需允许跨域访问 - 远程模块需把 React 声明为 singleton 共享依赖,与 shell 共用同一份 React
- 新增卡片或修改
remote、expose时,仍需重新构建 MCP 服务
本地卡片以独立入口构建,不加载框架的页面运行时。source.enableAsyncEntry 开启时,入口通过动态 import 建立异步边界,供 MF 共享依赖完成初始化。MF 插件会自动开启该选项。未开启时直接挂载卡片,不增加额外请求。
卡片必须默认导出 React 组件。props 来自 tool 返回的 structuredContent,mcpApp 为框架保留的注入字段。
默认包装器处理连接、主题、加载、错误、取消和 teardown。开始新一轮 tool 调用时会清空旧结果,不把输入参数合并进 props。卡片内调用 tool 返回的结果由组件自己处理,不会自动替换当前卡片数据。
编写服务端
创建 api/lambda/mcp.ts,使用官方 McpServer、registerAppTool 和 zod。UI 插件不自动挂载任何 MCP 路由。
需要启用 bffPlugin()。适配器根据 BFF 已解析的 JSON 重建请求,返回 SDK 的原始 Response。适配器通过 @modern-js/server-runtime 的 useHonoContext 获取原始请求,基于 Modern.js 封装的框架可以通过 createBffHandlers(createServer, { useContext }) 传入自己的实现。默认无状态 HTTP 模式由官方 SDK 处理协议和参数校验,GET、DELETE 等不支持的会话操作由 SDK 返回错误。认证与业务授权放在 HTTP 中间件或 createServer 中。每个请求创建独立的 server,业务数据需要持久化到外部存储。
独立 Hono 服务可通过 app.all('/mcp', c => handle(c.req.raw)) 挂载 createFetchHandler(createServer)。适配器默认只允许同源浏览器请求,额外来源通过第二个参数的 allowedOrigins 配置。
清单与部署
本地卡片文件名由卡片名生成稳定 hash,避免文件名冲突与路径注入。MF 卡片共用 shell。
清单契约为:
html、shell相对清单文件位置解析,也支持绝对 HTTP(S) 地址entry相对assetBase解析,也支持绝对 HTTP(S) 地址ui保留卡片的 CSP、permissions、domain、prefersBorder 元数据- 清单不记录 tool 或 resource URI,服务端生成
ui://app/<编码后的卡片名>,多个 tool 可以复用同一 URI - MF 配置在读取 resource 时注入 shell,不需要 tool result 携带框架元数据
createBffHandlers() 将服务端插件提供的清单路径和运行模式关联到当前请求。调用 registerUiResources(server, { request }) 即可自动获取配置。开发使用框架的内部目录,生产使用运行时的实际输出目录。显式选项优先于注入配置。独立服务必须显式配置 manifest 文件路径或 HTTP(S) URL,mode 默认为 production。相对 HTML 路径以清单位置为基准解析。
清单按来源地址和环境缓存。生产环境在进程生命周期内复用,原地址更新清单后需重启进程。开发环境检查本地文件状态,文件变化后重新加载,远程清单缓存 60 秒。并发加载会合并,加载失败后允许重试。HTML 仍在读取资源时加载,请求相关的地址和 metadata 不会跨请求复用。
output.assetPrefix 为绝对地址时用于推导 assetBase。request 表示使用请求的公开 origin,支持经过代理清理的 x-forwarded-proto。子路径或外部静态资源部署可以通过 registerUiResources 的 assetBase 显式覆盖。反向代理必须保留公开 host 并清理转发头。
服务端把资源根地址加入 CSP 的 resourceDomains、connectDomains 和 baseUriDomains,把 MF entry 的 origin 加入 connectDomains 和 resourceDomains。构建时还会把绝对地址或不带协议的 output.assetPrefix 的 origin 加入 CSP,//cdn.example/ 按 https://cdn.example 处理。其他 CDN、接口和 iframe 域名需在 mcp-views.json 中声明,或在配置中计算后通过 mcpAppsPlugin({ csp }) 传入,两者都会合并到每张卡片。生产部署必须保留清单、HTML、应用静态资源和 MF 产物。
平台可以把已构建的卡片文件和 MF 地址转换为绝对地址,组合成同版本的新清单,再由独立服务端消费。未知清单版本会被拒绝。
卡片能力声明
卡片默认声明支持 inline 和 fullscreen。本地组件模块及 MF expose 都可以导出 mcpCapabilities,补充能力或覆盖展示模式。
手动使用 createMcpView 时,也可以通过第三个参数传入能力声明。显式的展示模式数组会替换默认值。MF 模块在初始化前加载,确保握手包含该模块的能力。声明支持全屏不会自动添加全屏按钮或切换展示模式。
连接已部署的服务
应用开发者构建并部署 MCP 服务后,将实际的 MCP 地址提供给用户,例如 https://example.com/api/mcp。用户无需克隆应用或 Modern.js 仓库,也无需在本机运行 pnpm dev。服务需保持运行,客户端还需支持 MCP Apps 卡片展示。
HTTP 直连
如果客户端支持 Streamable HTTP,选择该传输类型,并将服务器地址填写为 https://example.com/api/mcp。鉴权信息按服务要求在客户端配置。
通过 STDIO 连接
如果客户端仅支持 STDIO,用户需先安装 Node.js 20 或更高版本(含 npm 和 npx),再配置 modern-mcp-stdio 桥接命令。npx 会下载并运行指定版本的包,无需预先安装 Modern.js。
将下面的 <version> 替换为包含 modern-mcp-stdio 功能的已发布 @modern-js/mcp-apps 版本,将 URL 替换为实际部署地址。应用提供方应向用户提供已验证的具体版本号。
如果客户端使用表单,命令填写 npx,参数按 args 数组逐项添加,每项单独一行。若客户端找不到 npx,命令填写用户本机的 npx 绝对路径。需要鉴权时,在参数末尾追加 --header 和 Authorization: Bearer <token> 两项,多个请求头可重复添加。
这里使用 --url 连接已部署的 HTTP 服务。--cwd 和本地脚本路径用于下文的开发调试,不需要提供给最终用户。桥接命令不会启动或部署应用服务。
生产环境如需将本地组件卡片打包为自包含 HTML,应用开发者应在 mcpAppsPlugin 中设置 inline: true 后构建部署。inline: 'dev' 仅作用于开发模式。MF 卡片仍需宿主能够访问其远程资源。
本机 stdio 调试
面向只支持本机 stdio 接入或限制隔离 iframe 访问本地资源的宿主(如桌面端 Agent),在 mcpAppsPlugin 中配置 inline,然后运行 pnpm dev 启动开发服务。
启动 pnpm dev 后,终端会输出一段可直接复制到本机 MCP 连接器的配置,使用 @modern-js/mcp-apps 内置的轻量脚本 modern-mcp-stdio 将 stdio 的 JSON-RPC 转发到本地 HTTP 开发服务(例如 http://localhost:8088/api/mcp):
- 请求处理:开发服务通过应用的 BFF 路由、自定义 Hono 中间件和服务端插件处理 HTTP 请求。需要向鉴权中间件透传请求头时,可追加
--header "Authorization: Bearer <token>"(可重复传多个) - 自动端口发现:默认连接器使用
--cwd <项目目录>,脚本在每次请求时读取node_modules/.modern-js/mcp-apps/dev-server.json自动定位当前开发服务地址。也可直接传入固定的 HTTP MCP URL - 增量构建:
inline模式下本地组件卡片通过独立的 watch 构建打包为单文件自包含 HTML(内联脚本、样式和导入资源,上限 5 MiB,不注入<base>或本地 CSP),修改组件后自动重编,下次读取卡片资源时生效。普通页面使用主应用的 HMR。若同一份mcp-views.json还包含 Module Federation 卡片,本地卡片走内联、MF 卡片使用 HTTP shell - 日志输出:开发服务的日志输出在
pnpm dev终端,转发脚本的stdout仅用于 JSON-RPC。modern dev未启动或重启期间,转发脚本会返回 JSON-RPC 错误而不是退出进程,待开发服务就绪后下一次调用自动恢复