For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt, and this page is available as Markdown at /zh/guides/advanced-features/mcp-apps.md.
  • 简体中文
  • MCP Apps

    Modern.js 可以把 React 组件构建为 MCP 卡片。UI 构建与服务端通过 ui-manifest.json 关联,服务端直接使用官方 MCP SDK。

    创建项目

    npx @modern-js/create@latest my-mcp --template mcp-apps
    # 复用本项目的 Module Federation expose
    npx @modern-js/create@latest my-mf-mcp --template mcp-apps --mf

    使用包含 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 引用已部署的远程模块,见下文。

    {
      "views": {
        "todos": "./src/components/Todos.tsx",
        "stats": { "expose": "./Stats" }
      },
      "csp": { "resourceDomains": [], "connectDomains": [] },
      "prefersBorder": true
    }

    在 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 参数替换:

    mcpAppsPlugin({
      views: './mcp-views.json',
      mf: {
        // 构建产物中 MF manifest 的文件名
        manifestFile: 'vmok-manifest.json',
        // 从应用解析,需导出兼容的 createInstance
        runtime: '@vmok/kit/runtime',
      },
    });

    引用已部署的远程模块

    卡片由另一个项目作为 MF 远程模块发布时,用 remote 指定远程模块的 manifest 地址:

    {
      "remote": "https://ui.example.com/mf-manifest.json",
      "views": {
        "todos": { "expose": "./Todos" },
        "stats": { "expose": "./Stats" }
      },
      "csp": { "resourceDomains": ["https://cdn.example.com"] }
    }

    顶层 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 为框架保留的注入字段。

    import type { McpViewProps } from '@modern-js/mcp-apps/react'
    
    export default function Todos({
      todos = [],
      mcpApp,
    }: McpViewProps<{ todos: string[] }>) {
      return (
        <section>
          <ul>
            {todos.map(todo => (
              <li key={todo}>{todo}</li>
            ))}
          </ul>
          <button
            onClick={() =>
              mcpApp.callServerTool({ name: 'refresh', arguments: {} })
            }
          >
            刷新
          </button>
        </section>
      )
    }

    默认包装器处理连接、主题、加载、错误、取消和 teardown。开始新一轮 tool 调用时会清空旧结果,不把输入参数合并进 props。卡片内调用 tool 返回的结果由组件自己处理,不会自动替换当前卡片数据。

    编写服务端

    创建 api/lambda/mcp.ts,使用官方 McpServer、registerAppTool 和 zod。UI 插件不自动挂载任何 MCP 路由。

    import { McpServer } from '@modelcontextprotocol/server'
    import { registerAppTool } from '@modelcontextprotocol/ext-apps/server'
    import {
      createBffHandlers,
      registerUiResources,
    } from '@modern-js/mcp-apps/server'
    import { z } from 'zod'
    
    async function createServer(request: Request) {
      const server = new McpServer({ name: 'todos', version: '1.0.0' })
      const ui = await registerUiResources(server, { request })
      registerAppTool(
        server,
        'list_todos',
        {
          inputSchema: z.object({}),
          _meta: { ui: { resourceUri: ui.todos } },
        },
        async () => ({
          content: [{ type: 'text', text: 'Todo list' }],
          structuredContent: { todos: ['Read the MCP Apps guide'] },
        }),
      )
      return server
    }
    
    export const { POST, GET, DELETE } = createBffHandlers(createServer)

    需要启用 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 配置。

    清单与部署

    dist/
    ├─ mcp-apps/
    │  ├─ ui-manifest.json
    │  └─ ui/
    │     ├─ mcp-ui-<name>-<hash>.html
    │     └─ mcp-shell.html
    └─ static/
       └─ mf-manifest.json

    本地卡片文件名由卡片名生成稳定 hash,避免文件名冲突与路径注入。MF 卡片共用 shell。

    清单契约为:

    {
      "version": 1,
      "assetBase": "request",
      "remotes": {
        "todo_ui": {
          "entry": "static/mf-manifest.json",
          "shell": "./ui/mcp-shell.html"
        }
      },
      "views": {
        "todos": {
          "html": "./ui/mcp-ui-local-25bf8e1a2393.html",
          "ui": { "prefersBorder": true }
        },
        "stats": { "remote": "todo_ui", "expose": "./Stats", "ui": {} }
      }
    }
    • 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,补充能力或覆盖展示模式。

    import type { McpCapabilities } from '@modern-js/mcp-apps/react'
    
    export const mcpCapabilities = {
      availableDisplayModes: ['inline'],
    } satisfies McpCapabilities
    
    export default function Card() {
      return <div>My card</div>
    }

    手动使用 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 替换为实际部署地址。应用提供方应向用户提供已验证的具体版本号。

    {
      "mcpServers": {
        "app": {
          "command": "npx",
          "args": [
            "-y",
            "--package=@modern-js/mcp-apps@<version>",
            "modern-mcp-stdio",
            "--url",
            "https://example.com/api/mcp"
          ]
        }
      }
    }

    如果客户端使用表单,命令填写 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 启动开发服务。

    mcpAppsPlugin({
      views: './mcp-views.json',
      // 'dev' 仅在开发模式打包自包含内联 HTML,true 同时作用于开发和生产构建
      inline: 'dev',
    });

    启动 pnpm dev 后,终端会输出一段可直接复制到本机 MCP 连接器的配置,使用 @modern-js/mcp-apps 内置的轻量脚本 modern-mcp-stdio 将 stdio 的 JSON-RPC 转发到本地 HTTP 开发服务(例如 http://localhost:8088/api/mcp):

    {
      "mcpServers": {
        "app": {
          "command": "node",
          "args": [
            "<app>/node_modules/@modern-js/mcp-apps/bin/modern-mcp-stdio.js",
            "--cwd",
            "<app>"
          ]
        }
      }
    }
    • 请求处理:开发服务通过应用的 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 错误而不是退出进程,待开发服务就绪后下一次调用自动恢复