@n8n/mcp-apps 0.1.0

package/LICENSE.md

@@ -0,0 +1,88 @@
+# License
+
+Portions of this software are licensed as follows:
+
+- Content of branches other than the main branch (i.e. "master") are not licensed.
+- Source code files that contain ".ee." in their filename or ".ee" in their dirname are NOT licensed under
+  the Sustainable Use License.
+  To use source code files that contain ".ee." in their filename or ".ee" in their dirname you must hold a
+	valid n8n Enterprise License specifically allowing you access to such source code files and as defined
+	in "LICENSE_EE.md".
+- All third party components incorporated into the n8n Software are licensed under the original license
+  provided by the owner of the applicable component.
+- Content outside of the above mentioned files or restrictions is available under the "Sustainable Use
+  License" as defined below.
+
+## Sustainable Use License
+
+Version 1.0
+
+### Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+### Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license
+to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+### Limitations
+
+You may use or modify the software only for your own internal business purposes or for non-commercial or
+personal use. You may distribute the software or provide it to others only if you do so free of charge for
+non-commercial purposes. You may not alter, remove, or obscure any licensing, copyright, or other notices of
+the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+### Patents
+
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to
+license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case
+subject to the limitations and conditions in this license. This license does not cover any patent claims that
+you cause to be infringed by modifications or additions to the software. If you or your company make any
+written claim that the software infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company makes such a claim, your patent
+license ends immediately for work on behalf of your company.
+
+### Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these
+terms. If you modify the software, you must include in any modified copies of the software a prominent notice
+stating that you have modified the software.
+
+### No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+### Termination
+
+If you use the software in violation of these terms, such use is not licensed, and your license will
+automatically terminate. If the licensor provides you with a notice of your violation, and you cease all
+violation of this license no later than 30 days after you receive that notice, your license will be reinstated
+retroactively. However, if you violate these terms after such reinstatement, any additional violation of these
+terms will cause your license to terminate automatically and permanently.
+
+### No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will
+not be liable to you for any damages arising out of these terms or the use or nature of the software, under
+any kind of legal claim.
+
+### Definitions
+
+The “licensor” is the entity offering these terms.
+
+The “software” is the software the licensor makes available under these terms, including any portion of it.
+
+“You” refers to the individual or entity agreeing to these terms.
+
+“Your company” is any legal entity, sole proprietorship, or other kind of organization that you work for, plus
+all organizations that have control over, are under the control of, or are under common control with that
+organization. Control means ownership of substantially all the assets of an entity, or the power to direct its
+management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+“Your license” is the license granted to you for the software under these terms.
+
+“Use” means anything you do with the software requiring your license.
+
+“Trademark” means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,132 @@
+# @n8n/mcp-apps
+
+UI resources and server helpers that let the n8n MCP server return **MCP
+Apps** — small, sandboxed HTML/Vue experiences rendered inside MCP clients
+that support the
+[`@modelcontextprotocol/ext-apps`](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps)
+extension. The package owns both the runtime UI bundles and the small server
+helpers used by `packages/cli` to register them as MCP resources and tools.
+
+## What it provides
+
+- **Server helpers** (`@n8n/mcp-apps/server`) for registering MCP App tools
+  and the static HTML resources that back them.
+- **Vue UI apps** under `src/apps/*`, built with Vite as standalone, fully
+  inlined HTML files (CSS + JS in a single document) so they can be served
+  directly as MCP resources.
+- **i18n plumbing** powered by `vue-i18n`, with locale negotiation driven by
+  the host context the MCP client provides at runtime.
+
+Today the package ships a single app, `workflow-preview`, which is rendered
+after the `create_workflow_from_code` MCP tool returns and gives the user a
+button to open the freshly created workflow in n8n. New apps can be added
+alongside it (see [Adding a new app](#adding-a-new-app)).
+
+## Package layout
+
+```
+src/
+  apps-manifest.ts          # single source of truth for the apps registry
+  apps/                     # Vue UI apps, each built into a standalone HTML
+    workflow-preview/
+      App.vue               # root component
+      main.ts               # mounts App with i18n
+      index.html            # entry HTML (built into dist/apps/<app>.html)
+      tokens.scss           # design tokens / global styles
+      url.ts                # defense-in-depth URL validation
+  i18n/                     # vue-i18n setup + host locale resolution
+  locales/                  # flat-key locale files (en.json, …)
+  server/                   # consumed by packages/cli
+    apps/                   # MCP resource registrations for each UI app
+    constants.ts            # shared URIs, MIME type, _meta keys
+    register-mcp-app-tool.ts
+    resource-loader.ts      # lazy reads built HTML from dist/apps
+    index.ts                # public entry: @n8n/mcp-apps/server
+```
+
+`apps-manifest.ts` is the canonical registry of MCP apps. Both the Vite
+build (entry directory + output HTML filename per `--mode`) and the
+server-side resource loader (compile-time union + runtime allow-list of
+loadable HTML files) derive from it, so the build and runtime stay in
+lockstep and there is no separate list to maintain.
+
+The Vite build (`pnpm build:ui`) emits one inlined HTML file per app into
+`dist/apps/<app>.html`. The TypeScript build (`pnpm build:server`) emits the
+server helpers into `dist/server/`. Both run as part of `pnpm build`.
+
+## UI runtime
+
+Each app:
+
+- Connects to the host via `@modelcontextprotocol/ext-apps`'s `App` class.
+- Receives a `McpUiHostContext` (theme, style variables, host fonts, locale)
+  through `onhostcontextchanged` and reflects it on the document.
+- Reads the originating tool's `structuredContent` via `ontoolresult` to
+  populate its own state.
+- Calls `app.openLink({ url })` to ask the host to navigate — never opens
+  links itself.
+
+URL handling is locked down by `isAllowedWorkflowUrl` in
+`src/apps/workflow-preview/url.ts`: only `http(s)://` URLs with a non-empty
+host are accepted, both when reading the tool result and right before calling
+`openLink`. This is defense in depth on top of the host's own validation.
+
+## Internationalization
+
+Locale files live under `src/locales/` and use flat, namespaced keys
+(`workflowPreview.openButton`, `workflowPreview.ariaLabel.ready`, …). The
+host's BCP 47 locale is resolved to a shipped locale via `resolveLocale`,
+applied to the `vue-i18n` instance, and mirrored to `<html lang>` for
+assistive tech. See `src/i18n/index.ts` for the full contract.
+
+To add a new locale:
+
+1. Drop `<code>.json` next to `en.json` in `src/locales/`.
+2. Import it in `src/i18n/index.ts` and add the code to `SUPPORTED_LOCALES`.
+
+The schema is derived from `en.json`, so other locales are type-checked
+against the same key set.
+
+## Adding a new app
+
+1. Create `src/apps/<app-name>/` with `index.html`, `main.ts`, and an
+   `App.vue` root component. Mount it through the shared `i18n` instance.
+2. Add an entry to `MCP_APPS` in `src/apps-manifest.ts`:
+
+   ```ts
+   '<app-name>': {
+     entry: '<app-name>',           // directory under src/apps/
+     htmlFile: '<app-name>.html',   // output under dist/apps/
+   },
+   ```
+
+   This single entry teaches Vite about the new `--mode`, expands the
+   `McpAppHtmlFileName` type union, and adds the file to the
+   `loadAppHtml` runtime allow-list. `pnpm build:ui --mode <app-name>`
+   will then produce `dist/apps/<app-name>.html`.
+3. Add the app's URI constant to `src/server/constants.ts` and a
+   `register<App>App` helper in `src/server/apps/` that calls
+   `server.resource(...)` with `loadAppHtml('<app-name>.html')`.
+4. Re-export the helper and URI constant from `src/server/index.ts`.
+5. Add any UI strings to `src/locales/en.json` under a new app-scoped
+   key prefix.
+
+## SDK version compatibility
+
+`src/server/sdk-version.test.ts` asserts that the
+`@modelcontextprotocol/sdk` version installed via the pnpm catalog satisfies
+the peer range declared by `@modelcontextprotocol/ext-apps`. CI fails the
+moment those two pins drift, so bumping one without the other is caught
+immediately.
+
+## Scripts
+
+| Command            | Description                                             |
+|--------------------|---------------------------------------------------------|
+| `pnpm build`       | Build UI apps and server helpers                        |
+| `pnpm build:ui`    | Build the Vue apps to inlined HTML in `dist/apps/`      |
+| `pnpm build:server`| Build the server entry to `dist/server/`                |
+| `pnpm typecheck`   | Run `vue-tsc` over the UI and `tsc` over the server     |
+| `pnpm lint`        | Lint with the shared ESLint config                      |
+| `pnpm test`        | Run unit tests with Vitest                              |
+| `pnpm test:dev`    | Run Vitest in watch mode                                |