@modern-js/app-tools 3.10.4 → 3.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,159 @@
1
+ > For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.
2
+
3
+ # MCP Apps
4
+
5
+ Modern.js builds React cards for MCP hosts. UI builds and servers exchange only `ui-manifest.json`. Servers use the official MCP SDK directly.
6
+
7
+ ## Create a project
8
+
9
+ ```bash
10
+ npx @modern-js/create@latest my-mcp --template mcp-apps
11
+ npx @modern-js/create@latest my-mf-mcp --template mcp-apps --mf
12
+ ```
13
+
14
+ Choose a release containing MCP Apps support. Run `pnpm dev`. The explicit BFF route is `/api/mcp`.
15
+
16
+ `@modern-js/mcp-apps` provides the build plugin, server plugin, server adapters and card runtime through `./cli`, `./server-plugin`, `./server` and `./react`. The application must install the peers `react`, `react-dom`, `@modelcontextprotocol/server` and `@modelcontextprotocol/ext-apps`, so cards use the application's React and tools, resources and HTTP handling use the application's SDK versions. `@modern-js/server-runtime` and `@module-federation/enhanced` are optional peers that provide the default request context for BFF handlers and the default MF shell runtime. The project templates already declare these dependencies.
17
+
18
+ ## Build cards
19
+
20
+ Declare local default-export React components or this project's MF exposes in `mcp-views.json`:
21
+
22
+ ```json
23
+ {
24
+ "views": {
25
+ "todos": "./src/components/Todos.tsx",
26
+ "stats": { "expose": "./Stats" }
27
+ },
28
+ "csp": { "resourceDomains": [], "connectDomains": [] },
29
+ "prefersBorder": true
30
+ }
31
+ ```
32
+
33
+ Import `mcpAppsPlugin` from `@modern-js/mcp-apps/cli` and add `mcpAppsPlugin({ views: './mcp-views.json' })` to your Modern.js plugins. Paths resolve relative to the JSON file. MF cards require the Modern.js MF plugin with manifest output enabled. The UI plugin validates exposes against the actual emitted MF manifest and builds the shell with the application's React dependencies.
34
+
35
+ The plugin finds the MF manifest in the web build output by filename, `mf-manifest.json` by default, and requires exactly one match. The shell imports `createInstance` from `@module-federation/enhanced/runtime` by default. Other MF implementations can replace both through the `mf` option:
36
+
37
+ ```ts
38
+ mcpAppsPlugin({
39
+ views: './mcp-views.json',
40
+ mf: {
41
+ // MF manifest filename in the build output
42
+ manifestFile: 'vmok-manifest.json',
43
+ // Resolved from the application. Must export a compatible createInstance
44
+ runtime: '@vmok/kit/runtime',
45
+ },
46
+ });
47
+ ```
48
+
49
+ Local cards build as separate entries without the framework page runtime. With `source.enableAsyncEntry`, each entry adds a dynamic import boundary so MF shared dependencies can initialize. The MF plugin enables this option automatically. Otherwise cards mount directly without an extra request.
50
+
51
+
52
+ ```tsx
53
+ import type { McpViewProps } from '@modern-js/mcp-apps/react'
54
+
55
+ export default function Todos({
56
+ todos = [],
57
+ mcpApp,
58
+ }: McpViewProps<{ todos: string[] }>) {
59
+ return (
60
+ <section>
61
+ <ul>
62
+ {todos.map(todo => (
63
+ <li key={todo}>{todo}</li>
64
+ ))}
65
+ </ul>
66
+ <button
67
+ onClick={() =>
68
+ mcpApp.callServerTool({ name: 'refresh', arguments: {} })
69
+ }
70
+ >
71
+ Refresh
72
+ </button>
73
+ </section>
74
+ )
75
+ }
76
+ ```
77
+
78
+ Props come from successful `structuredContent`. The reserved `mcpApp` prop is injected by the wrapper. Input arguments are not merged into props. New input, cancellation and teardown clear previous output. The wrapper manages connection, host styling and loading/error states. Results from tools called inside a card must be handled by the component itself.
79
+
80
+ ## Write the server
81
+
82
+ Enable `bffPlugin()` and create `api/lambda/mcp.ts`. The UI plugin does not register any HTTP route.
83
+
84
+
85
+ ```ts
86
+ import { McpServer } from '@modelcontextprotocol/server'
87
+ import { registerAppTool } from '@modelcontextprotocol/ext-apps/server'
88
+ import {
89
+ createBffHandlers,
90
+ registerUiResources,
91
+ } from '@modern-js/mcp-apps/server'
92
+ import { z } from 'zod'
93
+
94
+ async function createServer(request: Request) {
95
+ const server = new McpServer({ name: 'todos', version: '1.0.0' })
96
+ const ui = await registerUiResources(server, { request })
97
+ registerAppTool(
98
+ server,
99
+ 'list_todos',
100
+ {
101
+ inputSchema: z.object({}),
102
+ _meta: { ui: { resourceUri: ui.todos } },
103
+ },
104
+ async () => ({
105
+ content: [{ type: 'text', text: 'Todo list' }],
106
+ structuredContent: { todos: ['Read the MCP Apps guide'] },
107
+ }),
108
+ )
109
+ return server
110
+ }
111
+
112
+ export const { POST, GET, DELETE } = createBffHandlers(createServer)
113
+ ```
114
+
115
+ The adapter reconstructs BFF's consumed JSON body and returns the SDK Response. It reads the raw request through `useHonoContext` from `@modern-js/server-runtime`. Frameworks built on Modern.js can pass their own implementation with `createBffHandlers(createServer, { useContext })`. The official SDK owns protocol serving and tool validation. Serving is stateless, so unsupported session operations such as GET and DELETE are rejected by the SDK. Return a fresh server per request. Put authentication and authorization in surrounding middleware or the factory, and persist business data in an external store.
116
+
117
+ For independent Hono servers, create `handle = createFetchHandler(createServer)` and mount `app.all('/mcp', c => handle(c.req.raw))`. Foreign browser origins are rejected unless listed in `allowedOrigins` in the adapter's second argument.
118
+
119
+ ## Manifest and deployment
120
+
121
+ Builds emit `dist/mcp-apps/ui-manifest.json` and `dist/mcp-apps/ui/*.html`. Static JavaScript, CSS and MF files remain in the application's standard output. MF-only projects also emit a UI manifest. Local HTML filenames use a stable hash of the view name. MF cards share `mcp-shell.html`.
122
+
123
+ The version 1 manifest contains `assetBase`, `remotes` and `views`. A local view has `{ html, ui }`. An MF view has `{ remote, expose, ui }`, with its remote declaring `{ entry, shell }`.
124
+
125
+ - HTML and shell paths resolve relative to the manifest location
126
+ - MF entry paths resolve relative to `assetBase`
127
+ - Absolute HTTP(S) sources are supported for independent deployments
128
+ - `ui` preserves CSP, permissions, domain and border preferences
129
+ - Resource URIs are generated as `ui://app/<encoded-view-name>` by the server, and multiple tools can share a card
130
+ - MF configuration is injected into resource HTML instead of tool results
131
+
132
+ `createBffHandlers()` associates the server plugin’s manifest path and runtime mode with the current request. Call `registerUiResources(server, { request })` to resolve them automatically. Development uses the framework internal directory and production uses the runtime output directory. Explicit options override injected configuration. Independent services must provide a `manifest` file path or HTTP(S) URL. The `mode` option defaults to `production`. Relative HTML resolves against the manifest location.
133
+
134
+ Manifests are cached by source URL and environment. Production caches successful loads for the process lifetime, so updating the same location requires a process restart. Development detects local file changes and caches remote manifests for 60 seconds. Concurrent loads are coalesced and failures can be retried. HTML is read per resource request, and request-specific URLs and metadata remain isolated.
135
+
136
+ An absolute `output.assetPrefix` becomes `assetBase`. Otherwise request-origin resolution is used. Override `assetBase` in `registerUiResources` for a separate static origin or deployment path prefix. Request mode honors sanitized `x-forwarded-proto` headers. Reverse proxies must preserve the public host and sanitize forwarded headers.
137
+
138
+ Required asset, connection and base URI origins are added to CSP. MF entry origins are also added to connection permissions. The origin of an absolute or protocol-relative `output.assetPrefix` is added at build time, with `//cdn.example/` treated as `https://cdn.example`. Declare any other API, chunk/CDN or iframe origins in `mcp-views.json`, or pass domains computed in the config through `mcpAppsPlugin({ csp })`. Both are merged into every view. Deploy the manifest and HTML together with the application static assets and MF output.
139
+
140
+ Platforms may rewrite file and MF addresses to absolute URLs and combine cards into another manifest of the same version. Unknown versions are rejected.
141
+
142
+ ## Card capabilities
143
+
144
+ Cards advertise `inline` and `fullscreen` by default. Both local component modules and MF exposes can export `mcpCapabilities` to declare additional capabilities or override the display modes.
145
+
146
+
147
+ ```tsx
148
+ import type { McpCapabilities } from '@modern-js/mcp-apps/react'
149
+
150
+ export const mcpCapabilities = {
151
+ availableDisplayModes: ['inline'],
152
+ } satisfies McpCapabilities
153
+
154
+ export default function Card() {
155
+ return <div>My card</div>
156
+ }
157
+ ```
158
+
159
+ You can also pass capabilities as the third argument to `createMcpView`. Explicit display mode arrays replace the defaults. MF modules are loaded before initialization so the handshake includes their capabilities. Declaring fullscreen support does not add a fullscreen button or switch modes automatically.
package/docs/llms.txt CHANGED
@@ -52,6 +52,7 @@
52
52
  - [Extend Request SDK](/guides/advanced-features/bff/sdk.md): The unified invocation of BFF functions is isomorphic in both CSR and SSR. The request SDK encapsulated by Modern.js relies on the Fetch API on the browser side, and on node-fetch on the server side. However, in actual business scenarios, additional processing may be required for requests or responses, such as: Writing authentication information in the request headersUniform handling of response data or errorsUsing other methods to send requests when the native fetch function is unavailable on specific platforms To address these scenarios, Modern.js provides the configure function, which offers a series of extension capabilities. You can use it to configure SSR passthrough request headers, add interceptors, or customize the request SDK.
53
53
  - [File Upload](/guides/advanced-features/bff/upload.md): BFF combined with runtime framework provides file upload capabilities, supporting integrated calls and pure function manual calls. BFF Function First, create the api/lambda/upload.ts file: Integrated Calling Next, directly import and call the function in src/routes/upload/page.tsx: Manual Calling You can manually upload files using the fetch API, when calling fetch, set the body as FormData type and submit a post request.
54
54
  - [Cross-Project Invocation](/guides/advanced-features/bff/cross-project.md): Based on the BFF architecture, Modern.js provides cross-project invocation capabilities, allowing BFF functions created in one project to be invoked by other projects through integrated calls, enabling function sharing and feature reuse across projects. Cross-project invocation consists of producer and consumer sides. The producer is responsible for creating and providing BFF services while generating integrated invocation SDK, and the consumer initiates requests through these SDK.
55
+ - [MCP Apps](/guides/advanced-features/mcp-apps.md): Modern.js builds React cards for MCP hosts. UI builds and servers exchange only ui-manifest.json. Servers use the official MCP SDK directly.
55
56
  - [Code Splitting](/guides/advanced-features/page-performance/code-split.md): Code splitting is a common way to optimize frontend resource loading. This article will introduce the three types of code splitting supported by Modern.js: dynamic importReact.lazyloadable
56
57
  - [Inline Static Assets](/guides/advanced-features/page-performance/inline-assets.md): Inline static assets refer to the practice of including the content of a static asset directly in a HTML or JS file, instead of linking to an external file. This can improve the performance of a website by reducing the number of HTTP requests that the browser has to make to load the page. However, static assets inlining also has some disadvantages, such as increasing the size of a single file, which may lead to slower loading. Therefore, in the actual scenario, it is necessary to decide whether to use static assets inlining according to the specific situation. Modern.js will automatically inline static assets that are less than 10KB, but sometimes you may need to manually control assets to force them to be inlined or not, and this document explains how to precisely control the inlining behavior of static assets.
57
58
  - [Bundle Size Optimization](/guides/advanced-features/page-performance/optimize-bundle.md): Bundle size optimization is an important part of optimizing your production environment because it directly affects the user experience. In this document, we will introduce some common bundle size optimization methods in Modern.js.
package/package.json CHANGED
@@ -15,7 +15,7 @@
15
15
  "modern",
16
16
  "modern.js"
17
17
  ],
18
- "version": "3.10.4",
18
+ "version": "3.11.0",
19
19
  "types": "./dist/types/index.d.ts",
20
20
  "main": "./dist/cjs/index.js",
21
21
  "exports": {
@@ -126,16 +126,16 @@
126
126
  "ndepe": "^0.1.13",
127
127
  "pkg-types": "^1.3.1",
128
128
  "std-env": "^3.10.0",
129
- "@modern-js/builder": "3.10.4",
130
- "@modern-js/i18n-utils": "3.10.4",
131
- "@modern-js/plugin": "3.10.4",
132
- "@modern-js/plugin-data-loader": "3.10.4",
133
- "@modern-js/prod-server": "3.10.4",
134
- "@modern-js/server": "3.10.4",
135
- "@modern-js/server-core": "3.10.4",
136
- "@modern-js/server-utils": "3.10.4",
137
- "@modern-js/types": "3.10.4",
138
- "@modern-js/utils": "3.10.4"
129
+ "@modern-js/builder": "3.11.0",
130
+ "@modern-js/i18n-utils": "3.11.0",
131
+ "@modern-js/plugin": "3.11.0",
132
+ "@modern-js/prod-server": "3.11.0",
133
+ "@modern-js/plugin-data-loader": "3.11.0",
134
+ "@modern-js/server": "3.11.0",
135
+ "@modern-js/server-core": "3.11.0",
136
+ "@modern-js/server-utils": "3.11.0",
137
+ "@modern-js/types": "3.11.0",
138
+ "@modern-js/utils": "3.11.0"
139
139
  },
140
140
  "devDependencies": {
141
141
  "@types/babel__traverse": "7.28.0",
@@ -143,8 +143,8 @@
143
143
  "ts-node": "^10.9.2",
144
144
  "tsconfig-paths": "^4.2.0",
145
145
  "typescript": "^5",
146
- "@modern-js/rslib": "3.10.4",
147
- "@scripts/rstest-config": "2.66.3"
146
+ "@modern-js/rslib": "3.11.0",
147
+ "@scripts/rstest-config": "2.66.4"
148
148
  },
149
149
  "peerDependencies": {
150
150
  "ts-node": "^10.9.2",