mcp-app-studio 0.5.0 → 0.5.1

package/README.md

@@ -20,7 +20,7 @@ npm install
 npm run dev
 ```
 
-Open http://localhost:3000 — you're in the workbench.
+Open http://localhost:3002 — you're in the workbench.
 
 ## Universal SDK
 

package/dist/cli/index.js

@@ -3,22 +3,48 @@ import fs2 from "fs";
 import { createWriteStream } from "fs";
 import { Readable } from "stream";
 import { pipeline } from "stream/promises";
-import path2 from "path";
+import path3 from "path";
 import os from "os";
 import { fileURLToPath } from "url";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
 import { extract } from "tar";
 
+// src/cli/template-utils.ts
+import path from "path";
+function getGithubArchiveTarballUrl(repo, ref) {
+  return `https://github.com/${repo}/archive/${ref}.tar.gz`;
+}
+function isTarLinkEntry(entry) {
+  if (!entry || typeof entry !== "object") return false;
+  if (!("type" in entry)) return false;
+  const t = entry.type;
+  return t === "SymbolicLink" || t === "Link";
+}
+function assertSafeTarEntryPath(rootDir, entryPath) {
+  if (path.isAbsolute(entryPath)) {
+    throw new Error(`Template tarball contains an absolute path: ${entryPath}`);
+  }
+  const resolved = path.resolve(rootDir, entryPath);
+  if (resolved !== rootDir && !resolved.startsWith(`${rootDir}${path.sep}`)) {
+    throw new Error(`Template tarball contains an unsafe path: ${entryPath}`);
+  }
+}
+function filterTemplateTarEntry(rootDir, entryPath, entry) {
+  if (isTarLinkEntry(entry)) return false;
+  assertSafeTarEntryPath(rootDir, entryPath);
+  return true;
+}
+
 // src/cli/utils.ts
 import fs from "fs";
-import path from "path";
+import path2 from "path";
 function isValidProjectPath(name) {
   if (!name || name.trim() === "") {
     return { valid: false, error: "Project name is required" };
   }
   const trimmed = name.trim();
-  if (path.isAbsolute(trimmed)) {
+  if (path2.isAbsolute(trimmed)) {
     return {
       valid: false,
       error: "Absolute paths are not allowed. Use a relative path or project name."
@@ -31,9 +57,9 @@ function isValidProjectPath(name) {
     };
   }
   const cwd = process.cwd();
-  const resolved = path.resolve(cwd, trimmed);
-  const relative = path.relative(cwd, resolved);
-  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+  const resolved = path2.resolve(cwd, trimmed);
+  const relative = path2.relative(cwd, resolved);
+  if (relative.startsWith("..") || path2.isAbsolute(relative)) {
     return {
       valid: false,
       error: "Project must be created within current directory."
@@ -58,7 +84,7 @@ function emptyDir(dir) {
   if (!fs.existsSync(dir)) return;
   for (const file of fs.readdirSync(dir)) {
     if (file === ".git") continue;
-    fs.rmSync(path.join(dir, file), { recursive: true, force: true });
+    fs.rmSync(path2.join(dir, file), { recursive: true, force: true });
   }
 }
 var DEPENDENCY_OVERRIDES = {
@@ -66,8 +92,8 @@ var DEPENDENCY_OVERRIDES = {
   "@assistant-ui/react-ai-sdk": "^1.3.3",
   "@assistant-ui/react-markdown": "^0.12.1"
 };
-function updatePackageJson(dir, name, description, includeServer) {
-  const pkgPath = path.join(dir, "package.json");
+function updatePackageJson(dir, name, description, opts) {
+  const pkgPath = path2.join(dir, "package.json");
   if (!fs.existsSync(pkgPath)) return;
   try {
     const content = fs.readFileSync(pkgPath, "utf-8");
@@ -78,12 +104,10 @@ function updatePackageJson(dir, name, description, includeServer) {
     if (description) {
       pkg["description"] = description;
     }
-    if (includeServer) {
-      const scripts = pkg["scripts"] ?? {};
-      scripts["postinstall"] = "cd server && npm install";
-      pkg["scripts"] = scripts;
-    }
     const deps = pkg["dependencies"] ?? {};
+    if (opts?.mcpAppStudioVersion && opts.mcpAppStudioVersion !== "0.0.0") {
+      deps["mcp-app-studio"] = `^${opts.mcpAppStudioVersion}`;
+    }
     for (const [dep, version] of Object.entries(DEPENDENCY_OVERRIDES)) {
       if (deps[dep]) {
         deps[dep] = version;
@@ -107,9 +131,11 @@ function detectPackageManager() {
 }
 
 // src/cli/index.ts
-var __dirname = path2.dirname(fileURLToPath(import.meta.url));
-var TEMPLATE_REPO = "assistant-ui/mcp-app-studio-starter";
-var TEMPLATE_BRANCH = "main";
+var __dirname = path3.dirname(fileURLToPath(import.meta.url));
+var TEMPLATE_REPO = process.env["MCP_APP_STUDIO_TEMPLATE_REPO"] ?? "assistant-ui/mcp-app-studio-starter";
+var TEMPLATE_REF = process.env["MCP_APP_STUDIO_TEMPLATE_REF"] ?? process.env["MCP_APP_STUDIO_TEMPLATE_BRANCH"] ?? "main";
+var DOCS_URL = "https://github.com/assistant-ui/assistant-ui/tree/main/packages/mcp-app-studio";
+var EXAMPLES_URL = "https://github.com/assistant-ui/mcp-app-studio-starter";
 var REQUIRED_NODE_VERSION = { major: 20, minor: 9, patch: 0 };
 function parseNodeVersion(version) {
   const [majorRaw, minorRaw, patchRaw] = version.split(".");
@@ -139,7 +165,7 @@ function ensureSupportedNodeVersion() {
 }
 function getVersion() {
   try {
-    const pkgPath = path2.resolve(__dirname, "../package.json");
+    const pkgPath = path3.resolve(__dirname, "../package.json");
     const pkg = JSON.parse(fs2.readFileSync(pkgPath, "utf-8"));
     return pkg.version || "0.0.0";
   } catch {
@@ -163,7 +189,7 @@ ${pc.bold("Options:")}
   --version, -v           Show version number
   -y, --yes               Non-interactive mode (use defaults or flag values)
   --template <name>       Template to use: minimal, poi-map (default: minimal)
-  --include-server        Include MCP server (default when not using -y)
+  --include-server        Include MCP server (default: true)
   --no-server             Do not include MCP server
   --description <text>    App description
 
@@ -173,8 +199,8 @@ ${pc.bold("Examples:")}
   npx mcp-app-studio my-app -y --template poi-map --include-server
 
 ${pc.bold("Learn more:")}
-  Documentation: https://github.com/assistant-ui/mcp-app-studio
-  Examples:      https://github.com/assistant-ui/mcp-app-studio-starter
+  Documentation: ${DOCS_URL}
+  Examples:      ${EXAMPLES_URL}
 `);
 }
 function quotePath(p2) {
@@ -201,6 +227,76 @@ var TEMPLATE_DEFAULT_COMPONENT = {
   minimal: "welcome",
   "poi-map": "poi-map"
 };
+function writeStudioConfig(targetDir, template, appName) {
+  const exportConfig = TEMPLATE_EXPORT_CONFIG[template];
+  const config = {
+    widget: {
+      entryPoint: exportConfig.entryPoint,
+      exportName: exportConfig.exportName,
+      name: appName
+    }
+  };
+  fs2.writeFileSync(
+    path3.join(targetDir, "mcp-app-studio.config.json"),
+    `${JSON.stringify(config, null, 2)}
+`
+  );
+}
+function updateServerPackageName(targetDir, projectPackageName) {
+  const serverPkgPath = path3.join(targetDir, "server", "package.json");
+  if (!fs2.existsSync(serverPkgPath)) return;
+  const raw = fs2.readFileSync(serverPkgPath, "utf-8");
+  const pkg = JSON.parse(raw);
+  const baseName = projectPackageName.includes("/") ? projectPackageName.split("/").pop() : projectPackageName;
+  if (!baseName) return;
+  pkg["name"] = `${baseName}-mcp-server`;
+  fs2.writeFileSync(serverPkgPath, `${JSON.stringify(pkg, null, 2)}
+`, "utf-8");
+}
+function ensureServerPostinstall(targetDir) {
+  const pkgPath = path3.join(targetDir, "package.json");
+  const serverPkgPath = path3.join(targetDir, "server", "package.json");
+  if (!fs2.existsSync(pkgPath) || !fs2.existsSync(serverPkgPath)) return;
+  const raw = fs2.readFileSync(pkgPath, "utf-8");
+  const pkg = JSON.parse(raw);
+  const scripts = pkg["scripts"] ?? {};
+  if (scripts["postinstall"]) return;
+  const scriptPath = path3.join(
+    targetDir,
+    "scripts",
+    "mcp-app-studio-postinstall.cjs"
+  );
+  fs2.mkdirSync(path3.dirname(scriptPath), { recursive: true });
+  fs2.writeFileSync(
+    scriptPath,
+    `/* eslint-disable */
+const { spawnSync } = require("node:child_process");
+const { existsSync } = require("node:fs");
+const { join } = require("node:path");
+
+const ROOT = process.cwd();
+const SERVER_DIR = join(ROOT, "server");
+
+if (!existsSync(join(SERVER_DIR, "package.json"))) process.exit(0);
+if (existsSync(join(SERVER_DIR, "node_modules")) || existsSync(join(SERVER_DIR, ".pnp.cjs"))) process.exit(0);
+
+const ua = process.env.npm_config_user_agent || "";
+let pm = "npm";
+if (ua.includes("pnpm")) pm = "pnpm";
+else if (ua.includes("yarn")) pm = "yarn";
+else if (ua.includes("bun")) pm = "bun";
+
+console.log("\\n\\x1b[2mInstalling server dependencies (" + pm + ")...\\x1b[0m\\n");
+const result = spawnSync(pm, ["install"], { cwd: SERVER_DIR, stdio: "inherit", shell: process.platform === "win32" });
+process.exit(result.status == null ? 1 : result.status);
+`,
+    "utf-8"
+  );
+  scripts["postinstall"] = "node scripts/mcp-app-studio-postinstall.cjs";
+  pkg["scripts"] = scripts;
+  fs2.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}
+`, "utf-8");
+}
 function generateComponentRegistry(components) {
   const imports = [];
   const entries = [];
@@ -326,8 +422,10 @@ function generateExamplesIndex(components) {
 ` : "// No examples\n";
 }
 function updateExportScriptDefaults(targetDir, entryPoint, exportName) {
-  const exportScriptPath = path2.join(targetDir, "scripts/export.ts");
+  const exportScriptPath = path3.join(targetDir, "scripts/export.ts");
+  if (!fs2.existsSync(exportScriptPath)) return;
   let content = fs2.readFileSync(exportScriptPath, "utf-8");
+  if (content.includes("mcp-app-studio.config.json")) return;
   content = content.replace(
     /entryPoint: "lib\/workbench\/wrappers\/[^"]+"/,
     `entryPoint: "${entryPoint}"`
@@ -358,19 +456,22 @@ function generateWorkbenchIndexExport(components) {
   return exports.length > 0 ? `export { ${exports.join(", ")} } from "./wrappers";` : "// No SDK exports";
 }
 function updateWorkbenchIndex(targetDir, components) {
-  const indexPath = path2.join(targetDir, "lib/workbench/index.ts");
+  const indexPath = path3.join(targetDir, "lib/workbench/index.ts");
   let content = fs2.readFileSync(indexPath, "utf-8");
   const wrappersExportRegex = /export \{[^}]*\} from "\.\/wrappers";/;
   const newExport = generateWorkbenchIndexExport(components);
   if (wrappersExportRegex.test(content)) {
     content = content.replace(wrappersExportRegex, newExport);
   } else {
-    content = content.trimEnd() + "\n\n" + newExport + "\n";
+    content = `${content.trimEnd()}
+
+${newExport}
+`;
   }
   fs2.writeFileSync(indexPath, content);
 }
 function updateWorkbenchStoreDefault(targetDir, defaultComponent) {
-  const storePath = path2.join(targetDir, "lib/workbench/store.ts");
+  const storePath = path3.join(targetDir, "lib/workbench/store.ts");
   let content = fs2.readFileSync(storePath, "utf-8");
   content = content.replace(
     /selectedComponent: "[^"]+"/,
@@ -380,17 +481,17 @@ function updateWorkbenchStoreDefault(targetDir, defaultComponent) {
 }
 function applyTemplate(targetDir, template) {
   const components = TEMPLATE_COMPONENTS[template];
-  const registryPath = path2.join(
+  const registryPath = path3.join(
     targetDir,
     "lib/workbench/component-registry.tsx"
   );
   fs2.writeFileSync(registryPath, generateComponentRegistry(components));
-  const wrappersIndexPath = path2.join(
+  const wrappersIndexPath = path3.join(
     targetDir,
     "lib/workbench/wrappers/index.ts"
   );
   fs2.writeFileSync(wrappersIndexPath, generateWrappersIndex(components));
-  const examplesIndexPath = path2.join(
+  const examplesIndexPath = path3.join(
     targetDir,
     "components/examples/index.ts"
   );
@@ -398,23 +499,23 @@ function applyTemplate(targetDir, template) {
   updateWorkbenchIndex(targetDir, components);
   const defaultComponent = TEMPLATE_DEFAULT_COMPONENT[template];
   updateWorkbenchStoreDefault(targetDir, defaultComponent);
-  const examplesDir = path2.join(targetDir, "components/examples");
+  const examplesDir = path3.join(targetDir, "components/examples");
   if (!components.includes("welcome")) {
-    fs2.rmSync(path2.join(examplesDir, "welcome-card"), {
+    fs2.rmSync(path3.join(examplesDir, "welcome-card"), {
       recursive: true,
       force: true
     });
     fs2.rmSync(
-      path2.join(targetDir, "lib/workbench/wrappers/welcome-card-sdk.tsx"),
+      path3.join(targetDir, "lib/workbench/wrappers/welcome-card-sdk.tsx"),
       { force: true }
     );
   }
   if (!components.includes("poi-map")) {
-    fs2.rmSync(path2.join(examplesDir, "poi-map"), {
+    fs2.rmSync(path3.join(examplesDir, "poi-map"), {
       recursive: true,
       force: true
     });
-    fs2.rmSync(path2.join(targetDir, "lib/workbench/wrappers/poi-map-sdk.tsx"), {
+    fs2.rmSync(path3.join(targetDir, "lib/workbench/wrappers/poi-map-sdk.tsx"), {
       force: true
     });
   }
@@ -425,16 +526,61 @@ function applyTemplate(targetDir, template) {
     exportConfig.exportName
   );
 }
-async function downloadTemplate(targetDir) {
-  const tarballUrl = `https://github.com/${TEMPLATE_REPO}/archive/refs/heads/${TEMPLATE_BRANCH}.tar.gz`;
-  const tempDir = path2.join(os.tmpdir(), `mcp-app-studio-${Date.now()}`);
-  const tarballPath = path2.join(tempDir, "template.tar.gz");
+var REQUIRED_TEMPLATE_PATHS = [
+  "package.json",
+  "scripts/dev.ts",
+  "scripts/export.ts",
+  "lib/workbench/component-registry.tsx",
+  "lib/workbench/wrappers/index.ts",
+  "components/examples/index.ts",
+  "lib/workbench/index.ts",
+  "lib/workbench/store.ts"
+];
+function validateTemplateDir(templateDir) {
+  const missing = REQUIRED_TEMPLATE_PATHS.filter(
+    (p2) => !fs2.existsSync(path3.join(templateDir, p2))
+  );
+  if (missing.length > 0) {
+    throw new Error(
+      `Template validation failed. Missing expected files:
+${missing.map((p2) => `- ${p2}`).join(
+        "\n"
+      )}
+
+This may indicate the starter template has changed. Try updating mcp-app-studio or set MCP_APP_STUDIO_TEMPLATE_REPO / MCP_APP_STUDIO_TEMPLATE_REF to a compatible template.`
+    );
+  }
+}
+function copyDirContents(srcDir, destDir) {
+  fs2.mkdirSync(destDir, { recursive: true });
+  const entries = fs2.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === ".git") continue;
+    const srcPath = path3.join(srcDir, entry.name);
+    const destPath = path3.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copyDirContents(srcPath, destPath);
+      continue;
+    }
+    if (entry.isFile()) {
+      fs2.mkdirSync(path3.dirname(destPath), { recursive: true });
+      fs2.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+async function downloadTemplateToTemp() {
+  const tarballUrl = getGithubArchiveTarballUrl(TEMPLATE_REPO, TEMPLATE_REF);
+  const tempDir = fs2.mkdtempSync(
+    path3.join(os.tmpdir(), "mcp-app-studio-template-")
+  );
+  const tarballPath = path3.join(tempDir, "template.tar.gz");
+  const extractDir = path3.join(tempDir, "extract");
   try {
-    fs2.mkdirSync(tempDir, { recursive: true });
+    fs2.mkdirSync(extractDir, { recursive: true });
     const response = await fetch(tarballUrl);
     if (!response.ok) {
       throw new Error(
-        `Failed to download template: ${response.status} ${response.statusText}`
+        `Failed to download template from ${tarballUrl}: ${response.status} ${response.statusText}`
       );
     }
     const fileStream = createWriteStream(tarballPath);
@@ -446,15 +592,33 @@ async function downloadTemplate(targetDir) {
       body
     );
     await pipeline(nodeStream, fileStream);
-    fs2.mkdirSync(targetDir, { recursive: true });
     await extract({
       file: tarballPath,
-      cwd: targetDir,
-      strip: 1
-      // Remove the top-level directory (e.g., mcp-app-studio-starter-main/)
+      cwd: extractDir,
+      strip: 0,
+      filter: (entryPath, entry) => filterTemplateTarEntry(extractDir, entryPath, entry)
     });
-  } finally {
-    fs2.rmSync(tempDir, { recursive: true, force: true });
+    const topLevelDirs = fs2.readdirSync(extractDir, { withFileTypes: true }).filter((d) => d.isDirectory());
+    if (topLevelDirs.length !== 1) {
+      throw new Error(
+        `Unexpected template archive layout. Expected a single top-level directory, found ${topLevelDirs.length}.`
+      );
+    }
+    const topLevelDir = topLevelDirs[0];
+    if (!topLevelDir) {
+      throw new Error(
+        "Unexpected template archive layout. No top-level directory found."
+      );
+    }
+    const templateDir = path3.join(extractDir, topLevelDir.name);
+    validateTemplateDir(templateDir);
+    return { tempDir, templateDir };
+  } catch (err) {
+    try {
+      fs2.rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+    }
+    throw err;
   }
 }
 function parseArgs(args) {
@@ -599,8 +763,8 @@ async function main() {
     p.cancel("Operation cancelled.");
     process.exit(0);
   }
-  const targetDir = path2.resolve(process.cwd(), projectName);
-  const packageName = projectName === "." ? toValidPackageName(path2.basename(targetDir)) : toValidPackageName(projectName);
+  const targetDir = path3.resolve(process.cwd(), projectName);
+  const packageName = projectName === "." ? toValidPackageName(path3.basename(targetDir)) : toValidPackageName(projectName);
   const config = {
     name: projectName,
     packageName,
@@ -608,9 +772,11 @@ async function main() {
     template,
     includeServer
   };
-  if (!isEmpty(targetDir)) {
+  const targetNotEmpty = !isEmpty(targetDir);
+  let shouldOverwrite = false;
+  if (targetNotEmpty) {
     if (nonInteractive) {
-      emptyDir(targetDir);
+      shouldOverwrite = true;
     } else {
       const overwrite = await p.confirm({
         message: `Directory "${projectName}" is not empty. Remove existing files?`,
@@ -620,13 +786,14 @@ async function main() {
         p.cancel("Operation cancelled.");
         process.exit(0);
       }
-      emptyDir(targetDir);
+      shouldOverwrite = true;
     }
   }
   const s = p.spinner();
   s.start("Downloading template...");
+  let downloaded;
   try {
-    await downloadTemplate(targetDir);
+    downloaded = await downloadTemplateToTemp();
   } catch (error) {
     s.stop("Download failed");
     p.log.error(
@@ -635,16 +802,35 @@ async function main() {
     process.exit(1);
   }
   s.message("Creating project...");
-  updatePackageJson(
-    targetDir,
-    config.packageName,
-    config.description,
-    config.includeServer
-  );
+  try {
+    if (!downloaded) {
+      throw new Error(
+        "Internal error: template download did not return a result"
+      );
+    }
+    if (shouldOverwrite) {
+      emptyDir(targetDir);
+    }
+    fs2.mkdirSync(targetDir, { recursive: true });
+    copyDirContents(downloaded.templateDir, targetDir);
+  } finally {
+    if (downloaded?.tempDir) {
+      fs2.rmSync(downloaded.tempDir, { recursive: true, force: true });
+    }
+  }
+  updatePackageJson(targetDir, config.packageName, config.description, {
+    mcpAppStudioVersion: getVersion()
+  });
+  if (config.includeServer) {
+    ensureServerPostinstall(targetDir);
+  }
   s.message("Applying template...");
   applyTemplate(targetDir, config.template);
-  if (!config.includeServer) {
-    fs2.rmSync(path2.join(targetDir, "server"), { recursive: true, force: true });
+  writeStudioConfig(targetDir, config.template, path3.basename(targetDir));
+  if (config.includeServer) {
+    updateServerPackageName(targetDir, config.packageName);
+  } else {
+    fs2.rmSync(path3.join(targetDir, "server"), { recursive: true, force: true });
   }
   s.stop("Project created!");
   const pm = detectPackageManager();
@@ -694,12 +880,8 @@ async function main() {
   );
   p.log.message("");
   p.log.step(pc.bold("Learn more:"));
-  p.log.message(
-    `  ${pc.dim("\u2022")} SDK Docs:   ${pc.cyan("https://github.com/assistant-ui/mcp-app-studio#sdk")}`
-  );
-  p.log.message(
-    `  ${pc.dim("\u2022")} Examples:   ${pc.cyan("https://github.com/assistant-ui/mcp-app-studio-starter")}`
-  );
+  p.log.message(`  ${pc.dim("\u2022")} SDK Docs:   ${pc.cyan(DOCS_URL)}`);
+  p.log.message(`  ${pc.dim("\u2022")} Examples:   ${pc.cyan(EXAMPLES_URL)}`);
   if (config.includeServer) {
     p.log.message(
       `  ${pc.dim("\u2022")} MCP Guide:  ${pc.cyan("https://modelcontextprotocol.io/quickstart")}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-app-studio",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Build interactive apps for AI assistants (ChatGPT, Claude, MCP hosts)",
   "keywords": [
     "chatgpt",
@@ -62,9 +62,9 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@clack/prompts": "^0.11.0",
+    "@clack/prompts": "^1.0.0",
     "picocolors": "^1.1.1",
-    "tar": "^7.5.6"
+    "tar": "^7.5.7"
   },
   "peerDependencies": {
     "@modelcontextprotocol/ext-apps": ">=0.4.0",
@@ -79,12 +79,12 @@
     }
   },
   "devDependencies": {
-    "@modelcontextprotocol/ext-apps": "^0.4.0",
-    "@types/node": "^25.0.10",
-    "@types/react": "^19.1.6",
+    "@modelcontextprotocol/ext-apps": "^1.0.1",
+    "@types/node": "^25.2.0",
+    "@types/react": "^19.2.10",
     "@types/tar": "^6.1.13",
     "@vitest/coverage-v8": "^4.0.18",
-    "react": "^19.1.0",
+    "react": "^19.2.4",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",