mountly-mcp 4.0.2 → 4.2.0

package/GLOSSARY.md

@@ -0,0 +1,37 @@
+# Mountly MCP glossary
+
+Public vocabulary for `mountly-mcp`. Skills, templates, CLI help, README, and
+docs must use these names.
+
+| Term                     | Meaning                                                                                      |
+| ------------------------ | -------------------------------------------------------------------------------------------- |
+| **App**                  | MCP server plus its Views (SEP-1865 product).                                                |
+| **View**                 | Iframe UI for a tool result (`ui://` resource).                                              |
+| **`ui://`**              | Required scheme for View resource URIs.                                                      |
+| **`createMcpView`**      | Wrap a React / Vue / Svelte component (`mountly-mcp/react` etc.). Vanilla: `publishMcpView`. |
+| **`mountlyMcpViews`**    | Vite plugin. Emits View HTML and `dist/mountly-mcp.manifest.json`.                           |
+| **`registerMcpApps`**    | Install Views and UI-linked tools on an unconnected `McpServer`.                             |
+| **`readMcpAppManifest`** | Load `dist/mountly-mcp.manifest.json` from `mountly-mcp/artifact`.                           |
+| **`mcp.fixtures.json`**  | Named samples for `mountly-mcp dev` (tool args with `--server`, else `structuredContent`).   |
+| **`create`**             | `mountly-mcp create`: scaffold a greenfield App.                                             |
+| **`add`**                | `mountly-mcp add`: add a second View to an existing Mountly Vite project.                    |
+| **`build`**              | `mountly-mcp build`: build Views via Vite.                                                   |
+| **`dev`**                | `mountly-mcp dev`: local sandboxed AppBridge host with live reload.                          |
+| **`verify`**             | `mountly-mcp verify`: conformance (`--strict`, `--render`).                                  |
+| **`doctor`**             | `mountly-mcp doctor`: check Node, Vite plugin, Playwright, peer floors.                      |
+
+## Do not put in MCP docs / skills / templates
+
+- Islands vocabulary, HTML island attributes, microfrontends
+- Cloning `jagreehal/mountly` or `modelcontextprotocol/ext-apps` for greenfield Views
+- Hand-writing View HTML or postMessage for Views
+- Calling Mountly the "default view layer" until hosts recommend it
+
+## Happy path
+
+```bash
+npx mountly-mcp create my-app --framework react   # react | vue | svelte | vanilla
+cd my-app && pnpm install && pnpm dev
+pnpm verify
+pnpm verify --strict --render   # CI
+```

package/README.md

@@ -1,12 +1,16 @@
 # mountly-mcp
 
-**Build MCP Apps from React, Vue, or Svelte components — new or existing.**
+Build MCP Apps Views from React, Vue, or Svelte. New apps or components you
+already ship.
 
-[MCP Apps](https://github.com/modelcontextprotocol/ext-apps) (SEP-1865) lets an
-MCP server render interactive UI inside Claude, ChatGPT and other hosts. The
-official SDK gives you the protocol. `mountly-mcp` is the view layer on top:
-write a component, get a `ui://` resource, a local host, and server registration
-without hand-writing the handshake HTML.
+[MCP Apps](https://github.com/modelcontextprotocol/ext-apps) (SEP-1865) is the
+protocol. Official packages speak the wire. `mountly-mcp` is the View kit:
+component → `ui://` resource → local host → `registerMcpApps` on your server.
+
+```bash
+npx mountly-mcp create my-app --framework react
+cd my-app && pnpm install && pnpm dev
+```
 
 ```ts
 import { createMcpView } from "mountly-mcp/react";
@@ -15,81 +19,69 @@ import Dashboard from "./Dashboard";
 createMcpView(Dashboard);
 ```
 
-That path is the default whether the dashboard is three metric cards for one
-host or a multi-View production server. Prefer the scaffolder for greenfield:
+`--framework`: `react` | `vue` | `svelte` | `vanilla`. Vanilla calls
+`publishMcpView` with `mount` / `update` / `unmount`. No framework runtime.
 
-```bash
-npx mountly-mcp create my-app --framework react
-cd my-app && pnpm install && pnpm dev
-```
+## vs ext-apps
 
-`--framework` takes `react`, `vue`, `svelte`, or `vanilla`. Vanilla pulls in no
-framework and no adapter: a View is just `mount` / `update` / `unmount`, so
-`publishMcpView` takes the object directly and the bridge drives it the same
-way it drives the others.
+| Need                                                    | Package                          |
+| ------------------------------------------------------- | -------------------------------- |
+| Host / bridge protocol                                  | `@modelcontextprotocol/ext-apps` |
+| Component → View → `dev` → `verify` → `registerMcpApps` | `mountly-mcp`                    |
 
-## Build with Agent Skills
+Details: [Mountly vs ext-apps](https://mountly.dev/mcp-apps/vs-ext-apps/).
 
-| Skill                                                                              | Try it                                |
-| ---------------------------------------------------------------------------------- | ------------------------------------- |
-| [`create-mcp-app`](../../plugins/mountly-mcp/skills/create-mcp-app/SKILL.md)       | _"Create an MCP App"_                 |
-| [`add-app-to-server`](../../plugins/mountly-mcp/skills/add-app-to-server/SKILL.md) | _"Add UI to my MCP server"_           |
-| [`convert-web-app`](../../plugins/mountly-mcp/skills/convert-web-app/SKILL.md)     | _"Turn my component into an MCP App"_ |
-| [`migrate-ext-apps`](../../plugins/mountly-mcp/skills/migrate-ext-apps/SKILL.md)   | _"Migrate from ext-apps"_             |
+## Agent Skills
+
+| Skill                                                                              | Ask for                             |
+| ---------------------------------------------------------------------------------- | ----------------------------------- |
+| [`create-mcp-app`](../../plugins/mountly-mcp/skills/create-mcp-app/SKILL.md)       | "Create an MCP App"                 |
+| [`add-app-to-server`](../../plugins/mountly-mcp/skills/add-app-to-server/SKILL.md) | "Add UI to my MCP server"           |
+| [`convert-web-app`](../../plugins/mountly-mcp/skills/convert-web-app/SKILL.md)     | "Turn my component into an MCP App" |
+| [`migrate-ext-apps`](../../plugins/mountly-mcp/skills/migrate-ext-apps/SKILL.md)   | "Migrate from ext-apps"             |
 
 ```
 /plugin marketplace add jagreehal/mountly
 /plugin install mountly-mcp@mountly
 ```
 
-Docs: [Agent Skills](https://mountly.dev/mcp-apps/agent-skills/).
-`mountly-mcp build` emits a versioned App manifest; `registerMcpApps` installs
-the Views into the MCP server you already own. Existing website components stay
-reusable as-is.
-
-The wire protocol is delegated to the official `@modelcontextprotocol/sdk` and
-`@modelcontextprotocol/ext-apps` packages in full, so server transports,
-handshakes, capabilities and message types track the spec rather than a
-reimplementation of it. Both are runtime dependencies of `mountly-mcp`.
+Or `npx skills add jagreehal/mountly`. Docs: [Agent Skills](https://mountly.dev/mcp-apps/agent-skills/).
 
 ## Install
 
 ```bash
-# React (default) — mountly + mountly-react included
+# React (default). mountly + mountly-react are included.
 npm install mountly-mcp react react-dom
 
 # Vue / Svelte
 npm install mountly-mcp mountly-vue vue   # or mountly-svelte + svelte
 ```
 
-Install `@modelcontextprotocol/sdk` directly only when your application imports
-its APIs itself, for example to configure a custom HTTP transport. Mountly's
-server entry point does not require a separate SDK install.
+Add `@modelcontextprotocol/sdk` when you import `McpServer`.
 
-## One build, one command
+Peers: Node 20+ (22 preferred), React 18 or 19. Scaffolds pin Vite 8.
+`npx mountly-mcp doctor` checks a project.
+
+## Build
 
 ```ts
 // vite.config.ts
-import vue from "@vitejs/plugin-vue";
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
 import { mountlyMcpViews } from "mountly-mcp/vite";
 
 export default defineConfig({
   plugins: [
-    vue(),
+    react(),
     mountlyMcpViews({
       apps: [
         {
-          entry: "src/dashboard.ts",
+          entry: "src/view.tsx",
           uri: "ui://weather-server/dashboard",
           name: "weather_dashboard",
           displayModes: ["inline", "fullscreen"],
           csp: { connectDomains: ["https://api.weather.com"] },
         },
-        {
-          entry: "src/settings.ts",
-          uri: "ui://weather-server/settings",
-          name: "weather_settings",
-        },
       ],
     }),
   ],
@@ -100,38 +92,19 @@ export default defineConfig({
 npx mountly-mcp build
 ```
 
-Each View is built in an isolated Vite environment and emitted as self-contained
-HTML with a transitional `.meta.json` file. The canonical
-`dist/mountly-mcp.manifest.json` gives build, dev, registration, and CI one
-versioned artifact contract. The original single-View plugin shape and
-`vite build` remain supported.
+Writes HTML and `dist/mountly-mcp.manifest.json`.
 
-## One command to develop it
+## Develop
 
 ```bash
-npx mountly-mcp dev
-# multi-View project
-npx mountly-mcp dev --app weather_dashboard
+npx mountly-mcp dev --server ./server.mjs
+npx mountly-mcp dev --app weather_dashboard --server ./server.mjs
 ```
 
-Builds the View, serves it in a local MCP Apps host, and rebuilds on save.
-Config comes from the plugin already in your vite config.
-
-It's a real host, not a preview: the published official `AppBridge` drives the
-handshake and host behavior, while Mountly supplies two origins and a sandbox
-proxy enforcing the CSP and permissions the App artifact declares. Sample tool
-results come from `mcp.fixtures.json`,
-one button each, so clicking between them exercises the update path:
-
-```json
-{ "annual": { "total": 99 }, "monthly": { "total": 12 } }
-```
+Real AppBridge host plus sandbox CSP. Tool arguments come from
+`mcp.fixtures.json`.
 
-Add `--server ./server.js` (a module default-exporting your server) and the
-fixtures become tool _arguments_ instead: the view renders what your handler
-really returns, and the tool calls the view makes itself are routed there too.
-
-## Install into your production server
+## Production server
 
 ```ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -153,152 +126,92 @@ await registerMcpApps(server, {
       config: {
         inputSchema: { type: "object", properties: { location: { type: "string" } } },
       },
-      handler: async ({ location }) => ({ structuredContent: { location, temperature: 72 } }),
+      handler: async ({ location }) => ({
+        structuredContent: { location, temperature: 72 },
+      }),
     },
   ],
 });
+// connect with YOUR transport after this
 ```
 
-Call `registerMcpApps` before connecting the server. Your application retains
-ownership of authentication, transport, prompts, non-UI tools, lifecycle, and
-deployment. Views and tools are independent, so several tools can link to one
-View and app-only tools use `visibility: "app"`. Mountly negotiates the UI
-extension and degrades to text-only model tools for hosts without MCP Apps.
-
-`createMcpAppServer` and `serveStdio` remain as convenience adapters for small
-servers and existing projects.
+Call `registerMcpApps` before `connect`. You keep auth, transport, and deploy.
 
-## Verify in CI
+## Verify
 
 ```bash
+npx mountly-mcp doctor
 npx mountly-mcp verify
-npx mountly-mcp verify --strict
-npx mountly-mcp verify --render --strict
+npx mountly-mcp verify --strict --render
 ```
 
-Static verification is deterministic and offline. `--render` additionally
-launches Chromium, waits for the explicit bridge mount state, and rejects Views
-that time out, throw, or mount without content. Errors always fail; advisory
-warnings fail only under `--strict`. The same engine is exported as
-`verifyMcpApps()` from `mountly-mcp/testing` for custom test runners. Install
-Playwright and Chromium for the browser tier.
-
-## Reading tool data in a view
-
-The bridge exposes `mcp`, `toolInput`, `toolResult`, and `hostContext`. React
-and Vue consume those bridge props in their wrapper and expose them through
-hooks/composables, leaving the existing component's props unchanged. Svelte
-receives them directly as component props:
-
-```tsx
-// React
-const result = useToolResult<{ structuredContent?: Quote }>();
-const quote = result?.structuredContent;
-useHostStyles(); // adopt the host's theme variables and fonts
-```
+## Second View
 
-```ts
-// Vue
-const result = useToolResult<{ structuredContent?: Quote }>(); // a ref
-const quote = computed(() => result.value?.structuredContent);
+```bash
+npx mountly-mcp add settings --framework react
 ```
 
-Svelte reads the props directly via `$props()` — see `mountly-mcp/svelte`.
+## Glossary
 
-## json-render MCP Apps integration
+[GLOSSARY.md](./GLOSSARY.md). Protocol: [`@modelcontextprotocol/ext-apps`](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps).
 
-Mountly now exposes a first-class json-render MCP facade so catalog-driven UIs
-can be shipped as MCP Apps with minimal protocol code:
+## Compose from teams' elements
+
+`mountly-mcp/compose` lets the agent build a page from many teams' custom
+elements, using a [`mountly-compose`](../mountly-compose/README.md) catalog read
+from their `custom-elements.json`:
 
 ```ts
-import { createJsonRenderMcpApp } from "mountly-mcp/json-render/mcp";
-import { catalog } from "./catalog.js";
-import { html } from "./dist/app-html.js";
-
-const app = createJsonRenderMcpApp({
-  name: "json-render-dashboard",
-  version: "1.0.0",
-  catalog,
-  html,
-  tool: {
-    name: "render_ui",
-    title: "Render UI",
-    description: "Render an interactive dashboard from a json-render spec.",
-    resourceUri: "ui://json-render-dashboard/view.html",
+import { loadCatalog } from "mountly-compose";
+import { registerComposeApp } from "mountly-mcp/compose";
+
+registerComposeApp(server, {
+  catalog: await loadCatalog("https://cdn.acme.com/registry.json", { actions }),
+  imports: {
+    "mountly-compose": "https://cdn.acme.com/mountly-compose.js",
+    "@modelcontextprotocol/ext-apps": "https://cdn.acme.com/ext-apps/app-with-deps.js",
+    react: "…",
+    "react/jsx-runtime": "…",
+    "react-dom/client": "…",
+    "mountly-react": "…",
+    "mountly/embed": "…",
   },
 });
 ```
 
-For iframe-side React hosts, use `mountly-mcp/json-render/app`:
-
-```tsx
-import { useJsonRenderApp } from "mountly-mcp/json-render/app";
+The catalog becomes `show_page`'s description, and the agent composes the page.
+The handler validates the page and repairs small mistakes. When a page needs
+more than a repair, the handler returns the reasons as a tool error for the
+agent to fix. The `ui://` view renders with `mountly-compose` and loads each
+team's embed on first use. Its CSP allows the origins in `imports` and the
+teams' embed origins. The view runs at a `null` origin, so the servers behind
+those URLs send `Access-Control-Allow-Origin`. When the user acts in a widget,
+the view sends the agent its next turn with the current page. The
+[`ai-compose`](../../docs/examples/ai-compose) example runs this in `mcp/`.
 
-function View() {
-  const { spec, loading, connected, error } = useJsonRenderApp({
-    name: "json-render-dashboard",
-    version: "1.0.0",
-  });
-
-  if (error) return <div>{error.message}</div>;
-  if (!connected || loading || !spec) return <div>Waiting…</div>;
-  return <pre>{JSON.stringify(spec, null, 2)}</pre>;
-}
-```
+## Advanced: json-render
 
-`buildAppHtml({ title, js, css })` is also exported from
-`mountly-mcp/json-render/app` to generate a self-contained HTML resource.
-
-### Interoperability with `@json-render/mcp`
-
-Mountly's facade is wire-compatible with [`@json-render/mcp`](https://www.npmjs.com/package/@json-render/mcp) in both
-directions, so you can mix the two without a bridge:
-
-- **Tool input** is `{ spec }`, typed from `catalog.zodSchema()`, and the tool
-  description carries `catalog.prompt()` — the model sees the full component
-  vocabulary.
-- **Tool output** carries the spec twice: as JSON in `content[0].text` (the
-  shape `@json-render/mcp`'s iframe hook reads) and as `structuredContent.spec`
-  (what Mountly's own hosts read).
-- **`useJsonRenderApp`** reads either shape, so an iframe built with Mountly
-  renders a `@json-render/mcp` server unchanged, and vice versa.
-
-One deliberate difference: `@json-render/core` 0.19 generates a _strict_ catalog
-schema that requires `visible` and `children` on every element, which rejects
-most first-attempt model output at the SDK's input gate. Mountly accepts the
-catalog schema **or** a looser spec shape, then validates in the handler and
-renders what it can. Drop the loose branch once core relaxes those fields.
+`mountly-mcp/json-render` is optional catalog-driven UI. Start with `create` /
+`createMcpView`. Docs: [Generative UI](https://mountly.dev/concepts/generative-ui/).
 
 ## Exports
 
-| Entry                  | What's in it                                            |
-| ---------------------- | ------------------------------------------------------- |
-| `mountly-mcp`          | `runBridge`, spec types re-exported from ext-apps       |
-| `mountly-mcp/react`    | `createMcpView` + hooks                                 |
-| `mountly-mcp/vue`      | `createMcpView` + composables                           |
-| `mountly-mcp/svelte`   | `createMcpView` (props-based)                           |
-| `mountly-mcp/vite`     | single- and multi-View `mountlyMcpViews()` build plugin |
-| `mountly-mcp/artifact` | versioned manifest and App artifact APIs                |
-| `mountly-mcp/dev`      | `startDevHost()` and in-process server connectivity     |
-| `mountly-mcp/build`    | `buildMcpResource` for other bundlers                   |
-| `mountly-mcp/server`   | `registerMcpApps` plus convenience server adapters      |
-| `mountly-mcp/testing`  | static/browser conformance and report formatting        |
-
-Types use the spec's own names (`McpUiHostContext`, `McpUiDisplayMode`, …) —
-one vocabulary, no translation layer.
-
-## Agent Skills
-
-Install the plugin skills and ask your coding agent to create an MCP App:
-[Agent Skills docs](https://mountly.dev/mcp-apps/agent-skills/) ·
-[`create-mcp-app`](../../plugins/mountly-mcp/skills/create-mcp-app/SKILL.md).
-
-Greenfield without an agent: `npx mountly-mcp create my-app --framework react`.
+| Entry                     | Contents                                |
+| ------------------------- | --------------------------------------- |
+| `mountly-mcp`             | `runBridge`, `publishMcpView`, types    |
+| `mountly-mcp/react`       | `createMcpView` + hooks                 |
+| `mountly-mcp/vue`         | `createMcpView` + composables           |
+| `mountly-mcp/svelte`      | `createMcpView` (props)                 |
+| `mountly-mcp/vite`        | `mountlyMcpViews()`                     |
+| `mountly-mcp/artifact`    | Manifest APIs                           |
+| `mountly-mcp/server`      | `registerMcpApps`                       |
+| `mountly-mcp/dev`         | Local host helpers                      |
+| `mountly-mcp/testing`     | `verifyMcpApps`                         |
+| `mountly-mcp/json-render` | Generative path                         |
+| `mountly-mcp/compose`     | `registerComposeApp`, `composeViewHtml` |
 
 ## See also
 
-- [`docs/examples/mcp-release-readiness`](../../docs/examples/mcp-release-readiness) —
-  production-shaped Vite View (closest to `create`)
-- [`docs/examples/mcp-app-demo`](../../docs/examples/mcp-app-demo) — advanced
-  protocol harness (not the greenfield starter)
-- `docs/how-to-test.md`
+- [`mcp-release-readiness`](../../docs/examples/mcp-release-readiness) — production-shaped Vite View
+- [`mcp-app-demo`](../../docs/examples/mcp-app-demo) — protocol harness
+- [Host matrix](https://mountly.dev/mcp-apps/host-matrix/)