mountly-mcp 4.0.2 → 4.1.0

package/dist/doctor-B54H6CRN.js

@@ -0,0 +1,122 @@
+import {
+  CLI_ERROR_CODES,
+  cliError
+} from "./chunk-EOWAWZH2.js";
+
+// src/doctor.ts
+import { existsSync, readFileSync } from "fs";
+import { createRequire } from "module";
+import { resolve } from "path";
+function nodeMajor() {
+  return Number(process.versions.node.split(".")[0] ?? 0);
+}
+function tryResolve(specifier, fromDir) {
+  try {
+    const require2 = createRequire(resolve(fromDir, "package.json"));
+    return require2.resolve(specifier);
+  } catch {
+    return null;
+  }
+}
+function runDoctor(cwd = process.cwd()) {
+  const checks = [];
+  const major = nodeMajor();
+  checks.push({
+    id: "node",
+    ok: major >= 20,
+    detail: major >= 20 ? `Node ${process.versions.node} (ok; 20+ required, 22+ recommended)` : `Node ${process.versions.node} is below 20. Upgrade Node, then re-run mountly-mcp doctor.`
+  });
+  const viteConfigCandidates = [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vite.config.js",
+    "vite.config.mjs"
+  ].map((name) => resolve(cwd, name));
+  const viteConfig = viteConfigCandidates.find((path) => existsSync(path));
+  checks.push({
+    id: "vite-config",
+    ok: Boolean(viteConfig),
+    detail: viteConfig ? `Found ${viteConfig}` : "No vite.config.* in this directory. Run from the View project, or: npx mountly-mcp create my-app --framework react"
+  });
+  if (viteConfig) {
+    const source = readFileSync(viteConfig, "utf8");
+    const hasPlugin = /mountlyMcpViews\s*\(/.test(source);
+    checks.push({
+      id: "vite-plugin",
+      ok: hasPlugin,
+      detail: hasPlugin ? "vite config imports mountlyMcpViews()" : `Add mountlyMcpViews() from "mountly-mcp/vite" to ${viteConfig}`
+    });
+  }
+  const manifest = resolve(cwd, "dist/mountly-mcp.manifest.json");
+  checks.push({
+    id: "manifest",
+    ok: existsSync(manifest),
+    detail: existsSync(manifest) ? `Found ${manifest}` : "No dist/mountly-mcp.manifest.json yet. Run: npx mountly-mcp build"
+  });
+  const playwright = tryResolve("playwright", cwd) ?? tryResolve("@playwright/test", cwd);
+  checks.push({
+    id: "playwright",
+    ok: Boolean(playwright),
+    detail: playwright ? `Playwright resolvable for verify --render (${playwright})` : "Playwright not installed. For CI render checks: pnpm add -D playwright && npx playwright install chromium"
+  });
+  const pkgPath = resolve(cwd, "package.json");
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps.react) {
+      const reactPath = tryResolve("react/package.json", cwd);
+      if (reactPath) {
+        const reactPkg = JSON.parse(readFileSync(reactPath, "utf8"));
+        const reactMajor = Number((reactPkg.version ?? "0").split(".")[0]);
+        checks.push({
+          id: "react",
+          ok: reactMajor >= 19,
+          detail: reactMajor >= 19 ? `React ${reactPkg.version} (ok)` : `React ${reactPkg.version} is below 19. mountly-mcp/react and mountly-react require React 19.`
+        });
+      }
+    }
+    if (deps.vite) {
+      const vitePath = tryResolve("vite/package.json", cwd);
+      if (vitePath) {
+        const vitePkg = JSON.parse(readFileSync(vitePath, "utf8"));
+        const viteMajor = Number((vitePkg.version ?? "0").split(".")[0]);
+        checks.push({
+          id: "vite",
+          ok: viteMajor >= 8,
+          detail: viteMajor >= 8 ? `Vite ${vitePkg.version} (ok)` : `Vite ${vitePkg.version} is below 8. mountly-mcp/vite is built and tested against Vite 8.`
+        });
+      }
+    }
+  }
+  const hard = checks.filter((c) => c.id !== "manifest" && c.id !== "playwright");
+  const ok = hard.every((c) => c.ok);
+  return { ok, checks };
+}
+function formatDoctorReport(report) {
+  const lines = ["mountly-mcp doctor", ""];
+  for (const check of report.checks) {
+    lines.push(`${check.ok ? "ok" : "FAIL"}  ${check.id.padEnd(14)} ${check.detail}`);
+  }
+  lines.push("");
+  lines.push(report.ok ? "Ready for mountly-mcp build / dev / verify." : "Fix FAIL items above.");
+  lines.push("");
+  return `${lines.join("\n")}
+`;
+}
+function doctorCommand(cwd = process.cwd()) {
+  const report = runDoctor(cwd);
+  process.stdout.write(formatDoctorReport(report));
+  if (!report.ok) {
+    throw cliError(
+      CLI_ERROR_CODES.DOCTOR_FAILED,
+      "one or more doctor checks failed",
+      "Fix the FAIL lines above, then re-run: mountly-mcp doctor"
+    );
+  }
+}
+export {
+  doctorCommand,
+  formatDoctorReport,
+  runDoctor
+};
+//# sourceMappingURL=doctor-B54H6CRN.js.map

package/dist/doctor-B54H6CRN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/doctor.ts"],"sourcesContent":["import { existsSync, readFileSync } from \"node:fs\";\nimport { createRequire } from \"node:module\";\nimport { resolve } from \"node:path\";\nimport { CLI_ERROR_CODES, cliError } from \"./errors.js\";\n\nexport interface DoctorCheck {\n  id: string;\n  ok: boolean;\n  detail: string;\n}\n\nexport interface DoctorReport {\n  ok: boolean;\n  checks: DoctorCheck[];\n}\n\nfunction nodeMajor(): number {\n  return Number(process.versions.node.split(\".\")[0] ?? 0);\n}\n\nfunction tryResolve(specifier: string, fromDir: string): string | null {\n  try {\n    const require = createRequire(resolve(fromDir, \"package.json\"));\n    return require.resolve(specifier);\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Check the local project for Mountly MCP readiness. Exits nonzero via the\n * CLI when `ok` is false.\n */\nexport function runDoctor(cwd = process.cwd()): DoctorReport {\n  const checks: DoctorCheck[] = [];\n\n  const major = nodeMajor();\n  checks.push({\n    id: \"node\",\n    ok: major >= 20,\n    detail:\n      major >= 20\n        ? `Node ${process.versions.node} (ok; 20+ required, 22+ recommended)`\n        : `Node ${process.versions.node} is below 20. Upgrade Node, then re-run mountly-mcp doctor.`,\n  });\n\n  const viteConfigCandidates = [\n    \"vite.config.ts\",\n    \"vite.config.mts\",\n    \"vite.config.js\",\n    \"vite.config.mjs\",\n  ].map((name) => resolve(cwd, name));\n  const viteConfig = viteConfigCandidates.find((path) => existsSync(path));\n  checks.push({\n    id: \"vite-config\",\n    ok: Boolean(viteConfig),\n    detail: viteConfig\n      ? `Found ${viteConfig}`\n      : \"No vite.config.* in this directory. Run from the View project, or: npx mountly-mcp create my-app --framework react\",\n  });\n\n  if (viteConfig) {\n    const source = readFileSync(viteConfig, \"utf8\");\n    const hasPlugin = /mountlyMcpViews\\s*\\(/.test(source);\n    checks.push({\n      id: \"vite-plugin\",\n      ok: hasPlugin,\n      detail: hasPlugin\n        ? \"vite config imports mountlyMcpViews()\"\n        : `Add mountlyMcpViews() from \"mountly-mcp/vite\" to ${viteConfig}`,\n    });\n  }\n\n  const manifest = resolve(cwd, \"dist/mountly-mcp.manifest.json\");\n  checks.push({\n    id: \"manifest\",\n    ok: existsSync(manifest),\n    detail: existsSync(manifest)\n      ? `Found ${manifest}`\n      : \"No dist/mountly-mcp.manifest.json yet. Run: npx mountly-mcp build\",\n  });\n\n  const playwright = tryResolve(\"playwright\", cwd) ?? tryResolve(\"@playwright/test\", cwd);\n  checks.push({\n    id: \"playwright\",\n    ok: Boolean(playwright),\n    detail: playwright\n      ? `Playwright resolvable for verify --render (${playwright})`\n      : \"Playwright not installed. For CI render checks: pnpm add -D playwright && npx playwright install chromium\",\n  });\n\n  const pkgPath = resolve(cwd, \"package.json\");\n  if (existsSync(pkgPath)) {\n    const pkg = JSON.parse(readFileSync(pkgPath, \"utf8\")) as {\n      dependencies?: Record<string, string>;\n      peerDependencies?: Record<string, string>;\n      devDependencies?: Record<string, string>;\n    };\n    const deps = { ...pkg.dependencies, ...pkg.devDependencies };\n    if (deps.react) {\n      const reactPath = tryResolve(\"react/package.json\", cwd);\n      if (reactPath) {\n        const reactPkg = JSON.parse(readFileSync(reactPath, \"utf8\")) as { version?: string };\n        const reactMajor = Number((reactPkg.version ?? \"0\").split(\".\")[0]);\n        checks.push({\n          id: \"react\",\n          ok: reactMajor >= 19,\n          detail:\n            reactMajor >= 19\n              ? `React ${reactPkg.version} (ok)`\n              : `React ${reactPkg.version} is below 19. mountly-mcp/react and mountly-react require React 19.`,\n        });\n      }\n    }\n    if (deps.vite) {\n      const vitePath = tryResolve(\"vite/package.json\", cwd);\n      if (vitePath) {\n        const vitePkg = JSON.parse(readFileSync(vitePath, \"utf8\")) as { version?: string };\n        const viteMajor = Number((vitePkg.version ?? \"0\").split(\".\")[0]);\n        checks.push({\n          id: \"vite\",\n          ok: viteMajor >= 8,\n          detail:\n            viteMajor >= 8\n              ? `Vite ${vitePkg.version} (ok)`\n              : `Vite ${vitePkg.version} is below 8. mountly-mcp/vite is built and tested against Vite 8.`,\n        });\n      }\n    }\n  }\n\n  // Manifest missing is advisory for a brand-new scaffold before first build.\n  const hard = checks.filter((c) => c.id !== \"manifest\" && c.id !== \"playwright\");\n  const ok = hard.every((c) => c.ok);\n\n  return { ok, checks };\n}\n\nexport function formatDoctorReport(report: DoctorReport): string {\n  const lines = [\"mountly-mcp doctor\", \"\"];\n  for (const check of report.checks) {\n    lines.push(`${check.ok ? \"ok\" : \"FAIL\"}  ${check.id.padEnd(14)} ${check.detail}`);\n  }\n  lines.push(\"\");\n  lines.push(report.ok ? \"Ready for mountly-mcp build / dev / verify.\" : \"Fix FAIL items above.\");\n  lines.push(\"\");\n  return `${lines.join(\"\\n\")}\\n`;\n}\n\nexport function doctorCommand(cwd = process.cwd()): void {\n  const report = runDoctor(cwd);\n  process.stdout.write(formatDoctorReport(report));\n  if (!report.ok) {\n    throw cliError(\n      CLI_ERROR_CODES.DOCTOR_FAILED,\n      \"one or more doctor checks failed\",\n      \"Fix the FAIL lines above, then re-run: mountly-mcp doctor\",\n    );\n  }\n}\n"],"mappings":"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","names":["require"]}

package/dist/doctor.d.ts

@@ -0,0 +1,16 @@
+export interface DoctorCheck {
+    id: string;
+    ok: boolean;
+    detail: string;
+}
+export interface DoctorReport {
+    ok: boolean;
+    checks: DoctorCheck[];
+}
+/**
+ * Check the local project for Mountly MCP readiness. Exits nonzero via the
+ * CLI when `ok` is false.
+ */
+export declare function runDoctor(cwd?: string): DoctorReport;
+export declare function formatDoctorReport(report: DoctorReport): string;
+export declare function doctorCommand(cwd?: string): void;

package/dist/errors-4ERW7HZB.js

@@ -0,0 +1,11 @@
+import {
+  CLI_ERROR_CODES,
+  MountlyMcpCliError,
+  cliError
+} from "./chunk-EOWAWZH2.js";
+export {
+  CLI_ERROR_CODES,
+  MountlyMcpCliError,
+  cliError
+};
+//# sourceMappingURL=errors-4ERW7HZB.js.map

package/dist/errors-4ERW7HZB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * LLM-shaped CLI errors: a stable code plus the next command or file to open.
+ * Skills and agents should key off the `mountly-mcp/…` code prefix.
+ */
+export declare const CLI_ERROR_CODES: {
+    readonly MISSING_VITE_PLUGIN: "mountly-mcp/missing-vite-plugin";
+    readonly NO_VITE_CONFIG: "mountly-mcp/no-vite-config";
+    readonly UNKNOWN_VIEW: "mountly-mcp/unknown-view";
+    readonly MULTI_VIEW_NEEDS_APP: "mountly-mcp/multi-view-needs-app";
+    readonly INVALID_UI_URI: "mountly-mcp/invalid-ui-uri";
+    readonly BAD_SERVER_EXPORT: "mountly-mcp/bad-server-export";
+    readonly NO_TOOL_FOR_VIEW: "mountly-mcp/no-tool-for-view";
+    readonly UNKNOWN_OPTION: "mountly-mcp/unknown-option";
+    readonly UNKNOWN_COMMAND: "mountly-mcp/unknown-command";
+    readonly TARGET_EXISTS: "mountly-mcp/target-exists";
+    readonly MISSING_TEMPLATE: "mountly-mcp/missing-template";
+    readonly DOCTOR_FAILED: "mountly-mcp/doctor-failed";
+};
+export type CliErrorCode = (typeof CLI_ERROR_CODES)[keyof typeof CLI_ERROR_CODES];
+export declare class MountlyMcpCliError extends Error {
+    readonly code: CliErrorCode;
+    readonly next: string;
+    constructor(code: CliErrorCode, message: string, next: string);
+}
+export declare function cliError(code: CliErrorCode, message: string, next: string): MountlyMcpCliError;

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "mountly-mcp",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "description": "Build MCP Apps (SEP-1865) views from React, Vue or Svelte components — new or existing. One build emits the ui:// resource, its sidecar, and the MCP server wiring.",
   "keywords": [
     "chatgpt",
     "claude",
     "mcp",
     "mcp-apps",
+    "mcp-apps-view",
     "mcp-ui",
     "mcp-view",
     "model-context-protocol",
     "react",
     "sep-1865",
     "svelte",
+    "ui-resource",
     "vite-plugin",
     "vue"
   ],
@@ -27,7 +29,8 @@
   },
   "files": [
     "dist",
-    "templates"
+    "templates",
+    "GLOSSARY.md"
   ],
   "type": "module",
   "main": "./dist/index.js",
@@ -107,7 +110,7 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "mountly": "^1.0.0",
+    "mountly": "^1.0.1",
     "mountly-react": "^2.1.0",
     "zod": "^4.4.3"
   },
@@ -125,8 +128,8 @@
     "tsup": "^8.5.1",
     "typescript": "^7.0.2",
     "vite": "^8.1.5",
-    "mountly-svelte": "^2.1.0",
-    "mountly-vue": "^2.1.0"
+    "mountly-vue": "^2.1.0",
+    "mountly-svelte": "^2.1.0"
   },
   "peerDependencies": {
     "@json-render/core": "^0.20.0",
@@ -138,7 +141,7 @@
     "playwright": ">=1.62.1",
     "react": "^19",
     "react-dom": "^19",
-    "vite": "^8.2.1"
+    "vite": "^8"
   },
   "peerDependenciesMeta": {
     "@json-render/core": {

package/templates/react/README.md.tmpl

@@ -2,14 +2,91 @@
 
 MCP App scaffolded with `mountly-mcp create`.
 
+## Runbook
+
 ```bash
 pnpm install
-pnpm dev      # sandboxed host on :5179
-pnpm verify   # conformance
+pnpm dev                 # sandboxed AppBridge host on :5179 (uses --server ./server.mjs)
+pnpm verify              # static conformance
+pnpm verify:render       # + Chromium mount check (needs Playwright)
+```
+
+| File | Role |
+| --- | --- |
+| `src/view.tsx` | `createMcpView`: View entry; reads tool data via `useToolResult` |
+| `server.mjs` | `registerMcpApps`: factory for `mountly-mcp dev --server` |
+| `serve-stdio.mjs` | Stdio entry for Claude Desktop / VS Code / ChatGPT connectors |
+| `mcp.fixtures.json` | Tool **arguments** when using `--server` |
+| `vite.config.ts` | `mountlyMcpViews({ apps: [...] })` |
+| `dist/mountly-mcp.manifest.json` | Build artifact (after `pnpm build` / first `dev`) |
+
+Do not clone the Mountly monorepo for greenfield apps: this project is the canonical path.
+
+## Open in a real host
+
+`serve-stdio.mjs` is included. Build first (`pnpm build` or run `pnpm dev` once), then point the host at that entry.
+
+Never write logs to **stdout** in a stdio server.
+
+### Claude Desktop
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+
+```json
+{
+  "mcpServers": {
+    "{{slug}}": {
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/{{name}}/serve-stdio.mjs"]
+    }
+  }
+}
+```
+
+### VS Code
+
+`.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "{{slug}}": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${workspaceFolder}/serve-stdio.mjs"]
+    }
+  }
+}
 ```
 
-- View: `src/view.tsx` (`createMcpView`)
-- Server: `server.mjs` (`registerMcpApps`)
-- Fixtures: `mcp.fixtures.json` (tool args when using `--server`)
+### ChatGPT
+
+Use a connector / custom MCP that runs the same `serve-stdio.mjs` (or an HTTP transport your deployment owns). Mountly does not own OAuth or hosting.
+
+## CI
+
+```yaml
+# .github/workflows/mcp-verify.yml
+name: mcp-verify
+on: [push, pull_request]
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: pnpm }
+      - run: pnpm install
+      - run: pnpm exec mountly-mcp build
+      - run: pnpm exec playwright install chromium
+      - run: pnpm exec mountly-mcp verify --strict --render
+```
+
+## Add another View
+
+```bash
+pnpm exec mountly-mcp add settings --framework react
+```
 
-Do not clone the Mountly monorepo for greenfield apps — this project is the canonical path.
+Then register a tool with matching `resourceUri` in `server.mjs` via `registerMcpApps`.

package/templates/react/package.json.tmpl

@@ -8,6 +8,8 @@
     "dev": "mountly-mcp dev --server ./server.mjs",
     "verify": "mountly-mcp verify",
     "verify:strict": "mountly-mcp verify --strict",
+    "verify:render": "mountly-mcp verify --strict --render",
+    "doctor": "mountly-mcp doctor",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

package/templates/react/serve-stdio.mjs.tmpl

@@ -0,0 +1,9 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import createServer from "./server.mjs";
+
+/**
+ * Stdio entry for Claude Desktop / VS Code / other MCP hosts.
+ * Never write logs to stdout: stdout is the JSON-RPC channel.
+ */
+const server = await createServer();
+await server.connect(new StdioServerTransport());

package/templates/react/server.mjs.tmpl

@@ -1,3 +1,4 @@
+import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { readMcpAppManifest } from "mountly-mcp/artifact";
 import { registerMcpApps } from "mountly-mcp/server";
@@ -5,6 +6,10 @@ import { z } from "zod";
 
 const URI = "{{uri}}";
 
+// Resolved from this file, not the cwd: an MCP host spawns the process with a
+// working directory of its own choosing.
+const MANIFEST = fileURLToPath(new URL("./dist/mountly-mcp.manifest.json", import.meta.url));
+
 function sampleCards() {
   return [
     { label: "Requests", value: Math.floor(1200 + Math.random() * 200) },
@@ -20,7 +25,7 @@ export default async function createServer() {
     { capabilities: { tools: {}, resources: {} } },
   );
 
-  const { artifacts } = await readMcpAppManifest("dist/mountly-mcp.manifest.json");
+  const { artifacts } = await readMcpAppManifest(MANIFEST);
 
   await registerMcpApps(server, {
     views: artifacts.map((artifact) => ({ artifact })),

package/templates/react/src/view.tsx.tmpl

@@ -130,7 +130,7 @@ function Dashboard() {
       <p className="eyebrow">MCP App · Mountly</p>
       <h1>{title}</h1>
       <p className="subtitle">
-        Built with <code>mountly-mcp</code> — try Refresh to call an app-only tool.
+        Built with <code>mountly-mcp</code>. Try Refresh to call an app-only tool.
       </p>
       <div className="grid">
         {cards.length === 0

package/templates/svelte/README.md.tmpl

@@ -1,14 +1,37 @@
 # {{name}}
 
-MCP App scaffolded with `mountly-mcp create --framework svelte`.
+MCP App scaffolded with `mountly-mcp create` (Svelte).
+
+## Runbook
 
 ```bash
 pnpm install
 pnpm dev
 pnpm verify
+pnpm verify:render
+```
+
+| File | Role |
+| --- | --- |
+| `src/view.ts` | `createMcpView` entry |
+| `src/Dashboard.svelte` | View UI: `toolResult` prop |
+| `server.mjs` | `registerMcpApps` factory |
+| `mcp.fixtures.json` | Tool args for `dev --server` |
+
+## Open in a real host
+
+`serve-stdio.mjs` is included. Point Claude Desktop or VS Code at that entry (stdio). ChatGPT: use your connector against the same process.
+
+## CI
+
+```bash
+pnpm exec mountly-mcp build
+pnpm exec playwright install chromium
+pnpm exec mountly-mcp verify --strict --render
 ```
 
-- View: `src/view.ts` + `src/Dashboard.svelte`
-- Server: `server.mjs` (`registerMcpApps`)
+## Add another View
 
-Do not clone the Mountly monorepo for greenfield apps — this project is the canonical path.
+```bash
+pnpm exec mountly-mcp add settings --framework svelte
+```

package/templates/svelte/package.json.tmpl

@@ -8,6 +8,8 @@
     "dev": "mountly-mcp dev --server ./server.mjs",
     "verify": "mountly-mcp verify",
     "verify:strict": "mountly-mcp verify --strict",
+    "verify:render": "mountly-mcp verify --strict --render",
+    "doctor": "mountly-mcp doctor",
     "typecheck": "svelte-check --tsconfig ./tsconfig.json"
   },
   "dependencies": {

package/templates/svelte/serve-stdio.mjs.tmpl

@@ -0,0 +1,5 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import createServer from "./server.mjs";
+
+const server = await createServer();
+await server.connect(new StdioServerTransport());

package/templates/svelte/server.mjs.tmpl

@@ -1,3 +1,4 @@
+import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { readMcpAppManifest } from "mountly-mcp/artifact";
 import { registerMcpApps } from "mountly-mcp/server";
@@ -5,6 +6,10 @@ import { z } from "zod";
 
 const URI = "{{uri}}";
 
+// Resolved from this file, not the cwd: an MCP host spawns the process with a
+// working directory of its own choosing.
+const MANIFEST = fileURLToPath(new URL("./dist/mountly-mcp.manifest.json", import.meta.url));
+
 function sampleCards() {
   return [
     { label: "Requests", value: Math.floor(1200 + Math.random() * 200) },
@@ -20,7 +25,7 @@ export default async function createServer() {
     { capabilities: { tools: {}, resources: {} } },
   );
 
-  const { artifacts } = await readMcpAppManifest("dist/mountly-mcp.manifest.json");
+  const { artifacts } = await readMcpAppManifest(MANIFEST);
 
   await registerMcpApps(server, {
     views: artifacts.map((artifact) => ({ artifact })),

package/templates/svelte/src/Dashboard.svelte.tmpl

@@ -61,7 +61,7 @@
   <p class="eyebrow">MCP App · Mountly</p>
   <h1>{title}</h1>
   <p class="subtitle">
-    Built with <code>mountly-mcp</code> — try Refresh to call an app-only tool.
+    Built with <code>mountly-mcp</code>. Try Refresh to call an app-only tool.
   </p>
   <div class="grid">
     {#if cards.length === 0}

package/templates/vanilla/README.md.tmpl

@@ -1,20 +1,36 @@
 # {{name}}
 
-MCP App scaffolded with `mountly-mcp create`.
+MCP App scaffolded with `mountly-mcp create` (vanilla: no framework).
+
+## Runbook
 
 ```bash
 pnpm install
-pnpm dev      # sandboxed host on :5179
-pnpm verify   # conformance
+pnpm dev
+pnpm verify
+pnpm verify:render
 ```
 
-- View: `src/view.ts` (`publishMcpView`)
-- Server: `server.mjs` (`registerMcpApps`)
-- Fixtures: `mcp.fixtures.json` (tool args when using `--server`)
+| File | Role |
+| --- | --- |
+| `src/view.ts` | `publishMcpView`: `mount` / `update` / `unmount` |
+| `server.mjs` | `registerMcpApps` factory |
+| `mcp.fixtures.json` | Tool args for `dev --server` |
+
+## Open in a real host
+
+`serve-stdio.mjs` is included. Register that command in Claude Desktop / VS Code / ChatGPT.
 
-No framework, no adapter: a View is just `mount` / `update` / `unmount`, so
-`publishMcpView` takes the object directly. The bridge drives it exactly as it
-drives a React, Vue or Svelte View. Add a framework later by swapping
-`publishMcpView(...)` for that framework's `createMcpView(Component)`.
+## CI
 
-Do not clone the Mountly monorepo for greenfield apps — this project is the canonical path.
+```bash
+pnpm exec mountly-mcp build
+pnpm exec playwright install chromium
+pnpm exec mountly-mcp verify --strict --render
+```
+
+## Add another View
+
+```bash
+pnpm exec mountly-mcp add settings --framework vanilla
+```

package/templates/vanilla/package.json.tmpl

@@ -8,6 +8,8 @@
     "dev": "mountly-mcp dev --server ./server.mjs",
     "verify": "mountly-mcp verify",
     "verify:strict": "mountly-mcp verify --strict",
+    "verify:render": "mountly-mcp verify --strict --render",
+    "doctor": "mountly-mcp doctor",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

package/templates/vanilla/serve-stdio.mjs.tmpl

@@ -0,0 +1,5 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import createServer from "./server.mjs";
+
+const server = await createServer();
+await server.connect(new StdioServerTransport());

package/templates/vanilla/server.mjs.tmpl

@@ -1,3 +1,4 @@
+import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { readMcpAppManifest } from "mountly-mcp/artifact";
 import { registerMcpApps } from "mountly-mcp/server";
@@ -5,6 +6,10 @@ import { z } from "zod";
 
 const URI = "{{uri}}";
 
+// Resolved from this file, not the cwd: an MCP host spawns the process with a
+// working directory of its own choosing.
+const MANIFEST = fileURLToPath(new URL("./dist/mountly-mcp.manifest.json", import.meta.url));
+
 function sampleCards() {
   return [
     { label: "Requests", value: Math.floor(1200 + Math.random() * 200) },
@@ -20,7 +25,7 @@ export default async function createServer() {
     { capabilities: { tools: {}, resources: {} } },
   );
 
-  const { artifacts } = await readMcpAppManifest("dist/mountly-mcp.manifest.json");
+  const { artifacts } = await readMcpAppManifest(MANIFEST);
 
   await registerMcpApps(server, {
     views: artifacts.map((artifact) => ({ artifact })),

package/templates/vanilla/src/view.ts.tmpl

@@ -2,7 +2,7 @@ import { publishMcpView, type McpViewProps } from "mountly-mcp";
 
 /**
  * No framework, no adapter. A View is just `mount` / `update` / `unmount`, so
- * `publishMcpView` takes this object directly — the bridge drives it exactly
+ * `publishMcpView` takes this object directly. The bridge drives it exactly
  * as it drives a React, Vue or Svelte View.
  */
 

package/templates/vue/README.md.tmpl

@@ -1,14 +1,37 @@
 # {{name}}
 
-MCP App scaffolded with `mountly-mcp create --framework vue`.
+MCP App scaffolded with `mountly-mcp create` (Vue).
+
+## Runbook
 
 ```bash
 pnpm install
 pnpm dev
 pnpm verify
+pnpm verify:render
+```
+
+| File | Role |
+| --- | --- |
+| `src/view.ts` | `createMcpView` entry |
+| `src/Dashboard.vue` | View UI: `useToolResult` |
+| `server.mjs` | `registerMcpApps` factory |
+| `mcp.fixtures.json` | Tool args for `dev --server` |
+
+## Open in a real host
+
+`serve-stdio.mjs` is included. Point Claude Desktop / VS Code at `node` + absolute path to that file (see the React scaffold README for JSON shapes). ChatGPT: use your connector against the same process.
+
+## CI
+
+```bash
+pnpm exec mountly-mcp build
+pnpm exec playwright install chromium
+pnpm exec mountly-mcp verify --strict --render
 ```
 
-- View: `src/view.ts` + `src/Dashboard.vue`
-- Server: `server.mjs` (`registerMcpApps`)
+## Add another View
 
-Do not clone the Mountly monorepo for greenfield apps — this project is the canonical path.
+```bash
+pnpm exec mountly-mcp add settings --framework vue
+```

package/templates/vue/package.json.tmpl

@@ -8,6 +8,8 @@
     "dev": "mountly-mcp dev --server ./server.mjs",
     "verify": "mountly-mcp verify",
     "verify:strict": "mountly-mcp verify --strict",
+    "verify:render": "mountly-mcp verify --strict --render",
+    "doctor": "mountly-mcp doctor",
     "typecheck": "vue-tsc --noEmit"
   },
   "dependencies": {