feat: add @modelcontextprotocol/create-mcp-app package #353

liady · 2026-01-25T20:37:09Z

Closes #354

Summary

Enable scaffolding new MCP App projects with a single command:

npm create @modelcontextprotocol/mcp-app my-app

Features

Interactive CLI with beautiful UX using @clack/prompts
Two frameworks: React and Vanilla JS
Uses tsx for running the dev server (broader compatibility than bun)
Uses esbuild for bundling server files
Supports command-line flags:
- --framework react|vanillajs - Skip framework selection prompt
Always runs npm install after scaffolding

Package Structure

packages/create-mcp-app/
├── src/           # CLI source code
├── templates/
│   ├── base/      # Shared files (server.ts, main.ts, configs)
│   ├── react/     # React-specific files
│   └── vanillajs/ # Vanilla JS-specific files
├── test/          # E2E scaffold tests
└── dist/          # Compiled CLI

Changes

Add packages/create-mcp-app/ with CLI implementation and templates
Add packages/* to workspaces in root package.json
Add publish-packages job to npm-publish workflow
Update README to reference the new CLI tool
SDK version read dynamically from package.json at runtime
E2E test scaffolds both templates and verifies they build

Testing

# Build the package
npm run build --workspace packages/create-mcp-app

# Run scaffold E2E test (scaffolds + builds both templates)
npm test --workspace packages/create-mcp-app

# Manual test
cd /tmp
node /path/to/ext-apps/packages/create-mcp-app/dist/index.js my-app --framework react
cd my-app && npm run build

Test plan

Package builds successfully
React template scaffolds and builds
Vanilla JS template scaffolds and builds
CLI help displays correctly
E2E scaffold test passes (both templates)
Test with basic-host after merge

🤖 Generated with Claude Code

Enable scaffolding new MCP App projects via `npm create @modelcontextprotocol/mcp-app`. Features: - Interactive CLI with @clack/prompts for beautiful UX - React and Vanilla JS templates included - Uses tsx for broader compatibility (no bun dependency) - Templates include server, UI, and build configuration - Supports --template and --no-install flags Changes: - Add packages/create-mcp-app/ with CLI and templates - Add packages/* to workspaces in root package.json - Add publish-packages job to npm-publish workflow Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

pkg-pr-new · 2026-01-25T20:40:15Z

Open in StackBlitz

@modelcontextprotocol/ext-apps

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/ext-apps@353

@modelcontextprotocol/server-basic-react

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-basic-react@353

@modelcontextprotocol/server-basic-vanillajs

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-basic-vanillajs@353

@modelcontextprotocol/server-budget-allocator

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-budget-allocator@353

@modelcontextprotocol/server-cohort-heatmap

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-cohort-heatmap@353

@modelcontextprotocol/server-customer-segmentation

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-customer-segmentation@353

@modelcontextprotocol/server-map

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-map@353

@modelcontextprotocol/server-pdf

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-pdf@353

@modelcontextprotocol/server-scenario-modeler

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-scenario-modeler@353

@modelcontextprotocol/server-shadertoy

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-shadertoy@353

@modelcontextprotocol/server-sheet-music

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-sheet-music@353

@modelcontextprotocol/server-system-monitor

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-system-monitor@353

@modelcontextprotocol/server-threejs

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-threejs@353

@modelcontextprotocol/server-transcript

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-transcript@353

@modelcontextprotocol/server-video-resource

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-video-resource@353

@modelcontextprotocol/server-wiki-explorer

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/server-wiki-explorer@353

commit: d15a5a1

- Add Quick Start section to README with npm create command - Add tip callout to quickstart guide for faster project setup Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jonathanhefner

I left some comments, but I think my biggest qualm is testing. I think we need to be 100% sure that the code we generate works end-to-end. Right now, it looks like the scaffold code isn't being tested nor even type-checked (unless I missed it?).

jonathanhefner · 2026-01-27T15:37:38Z

docs/quickstart.md

+> [!TIP]
+> **Want to skip the setup?** Run `npm create @modelcontextprotocol/mcp-app my-app` to scaffold this project automatically, then skip to [Section 3: Build the View](#3-build-the-view).


This actually replaces all but the last step of the Quickstart guide ("See it in action").

I don't think we want to pitch this in the Quickstart, because the Quickstart is a "learn by doing" tutorial. If we replace the "doing" with npm create @modelcontextprotocol/mcp-app my-app, that kind of defeats the purpose. 😄

jonathanhefner · 2026-01-27T15:42:21Z

packages/create-mcp-app/src/cli.ts

+  npm create @modelcontextprotocol/mcp-app [project-name] [options]
+
+${pc.bold("Options:")}
+  -t, --template <name>  Template to use (${TEMPLATES.map((t) => t.value).join(", ")})


I think this would be better named as --framework. (I would assume a --template option designates an actual template to use — i.e., a path to a directory.)

jonathanhefner · 2026-01-27T15:42:40Z

packages/create-mcp-app/src/cli.ts

+
+${pc.bold("Options:")}
+  -t, --template <name>  Template to use (${TEMPLATES.map((t) => t.value).join(", ")})
+  --no-install           Skip npm install


Just curious: what's the use case for this option?

jonathanhefner · 2026-01-27T15:45:57Z

packages/create-mcp-app/src/utils.ts

+/** Current SDK version - used in generated package.json files */
+export const SDK_VERSION = "0.4.1";


I think we need a way for this to be dynamically computed or at least automatically updated.

jonathanhefner · 2026-01-27T15:46:45Z

packages/create-mcp-app/src/utils.ts

+  if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/i.test(name)) {
+    return "Project name must be lowercase alphanumeric with optional hyphens";
+  }


What is the reason for this restriction?

jonathanhefner · 2026-01-27T16:06:36Z

packages/create-mcp-app/templates/react/src/mcp-app.module.css

+.main {
+  --color-primary: #2563eb;
+  --color-primary-hover: #1d4ed8;
+
+  width: 100%;
+  max-width: 425px;
+  box-sizing: border-box;
+  padding: 1rem;
+
+  > * {
+    margin-top: 0;
+    margin-bottom: 0;
+  }
+
+  > * + * {
+    margin-top: 1.5rem;
+  }
+}


I don't think we want this CSS either. It might be beneficial to include some basic styling that uses CSS variables from the host context, but I'm not sure if that would be better here or in global.css. 🤔

jonathanhefner · 2026-01-27T16:08:53Z

packages/create-mcp-app/templates/react/src/mcp-app.tsx

+  useEffect(() => {
+    if (toolResult) {
+      setServerTime(extractTime(toolResult));
+    }
+  }, [toolResult]);
+
+  const handleGetTime = useCallback(async () => {
+    try {
+      console.info("Calling get-time tool...");
+      const result = await app.callServerTool({
+        name: "get-time",
+        arguments: {},
+      });
+      console.info("get-time result:", result);
+      setServerTime(extractTime(result));
+    } catch (e) {
+      console.error(e);
+      setServerTime("[ERROR]");
+    }
+  }, [app]);


Similar to my comment about the tool, I don't think we should be including this in a scaffold.

jonathanhefner · 2026-01-27T16:17:38Z

packages/create-mcp-app/templates/react/package.json.tmpl

+    "@modelcontextprotocol/sdk": "^1.24.0",
+    "cors": "^2.8.5",
+    "express": "^5.1.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "@vitejs/plugin-react": "^4.3.4",
+    "concurrently": "^9.2.1",
+    "cross-env": "^10.1.0",
+    "esbuild": "^0.25.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vite": "^6.0.0",
+    "vite-plugin-singlefile": "^2.3.0"


I am wary about hard-coding these version numbers.

jonathanhefner · 2026-01-27T16:23:07Z

packages/create-mcp-app/templates/react/tsconfig.json

+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src", "server.ts"]


include is missing main.ts, but also there is a problem with this approach: using DOM APIs in server code isn't flagged by the IDE. We kind of accept / overlook that for our in-repo examples, but if we're generating code for other people's projects, I would like to do better.

jonathanhefner · 2026-01-27T16:25:31Z

packages/create-mcp-app/README.md

+Then test with the basic-host:
+
+```bash
+SERVERS='["http://localhost:3001/mcp"]' npx @modelcontextprotocol/basic-host


@modelcontextprotocol/basic-host is not a published package.

- Rename --template flag to --framework - Remove --no-install flag (always install deps) - Read SDK_VERSION dynamically from package.json at runtime - Simplify project name validation (filesystem + npm rules only) - Replace get-time example tool with minimal hello stub - Remove __dirname/import.meta.filename hack in server template - Strip scaffold CSS to minimal layout-only styles - Simplify React scaffold to minimal connected component - Fix tsconfig.json to include main.ts in both templates - Add tsconfig.server.json main.ts include for server code - Fix README.md (remove --no-install, basic-host reference) - Remove quickstart.md scaffold tip (tutorial shouldn't shortcut itself) - Add E2E scaffold test that builds both templates end-to-end Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

packages/create-mcp-app/test/scaffold-build.test.mjs

- Rename --template to --framework flag - Dynamically resolve MCP SDK version from installed package - Remove dot/underscore name restriction and regex interpolation concern - Simplify scaffold templates: remove example tool UI, use TODO placeholders - Delete CSS module files, use global.css with host style variables - Switch test from execSync to execFileSync to avoid shell injection - Add separate tsconfig.server.json without DOM libs for server code Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

liady and others added 2 commits January 25, 2026 22:50

docs: add create-mcp-app references to README and quickstart

50ebcd9

- Add Quick Start section to README with npm create command - Add tip callout to quickstart guide for faster project setup Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Merge branch 'main' into feat/create-app

975cb61

liady marked this pull request as ready for review January 25, 2026 21:31

liady requested a review from ochafik January 25, 2026 21:31

ochafik requested review from jonathanhefner and localden January 26, 2026 15:06

jonathanhefner reviewed Jan 27, 2026

View reviewed changes

liady marked this pull request as draft January 29, 2026 20:18

liady and others added 2 commits January 29, 2026 22:23

Merge branch 'main' into feat/create-app

4b6bbee

github-advanced-security bot found potential problems Jan 29, 2026

View reviewed changes

packages/create-mcp-app/test/scaffold-build.test.mjs Fixed Show fixed Hide fixed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add @modelcontextprotocol/create-mcp-app package #353

feat: add @modelcontextprotocol/create-mcp-app package #353

Uh oh!

liady commented Jan 25, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 25, 2026 •

edited

Loading

jonathanhefner left a comment

jonathanhefner Jan 27, 2026

jonathanhefner Jan 27, 2026

jonathanhefner Jan 27, 2026

jonathanhefner Jan 27, 2026

jonathanhefner Jan 27, 2026

jonathanhefner Jan 27, 2026

jonathanhefner Jan 27, 2026

jonathanhefner Jan 27, 2026

jonathanhefner Jan 27, 2026

jonathanhefner Jan 27, 2026

Uh oh!

Labels

3 participants

		> [!TIP]
		> Want to skip the setup? Run `npm create @modelcontextprotocol/mcp-app my-app` to scaffold this project automatically, then skip to [Section 3: Build the View](#3-build-the-view).

		/** Current SDK version - used in generated package.json files */
		export const SDK_VERSION = "0.4.1";

feat: add @modelcontextprotocol/create-mcp-app package #353

Are you sure you want to change the base?

feat: add @modelcontextprotocol/create-mcp-app package #353

Uh oh!

Conversation

liady commented Jan 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Features

Package Structure

Changes

Testing

Test plan

pkg-pr-new bot commented Jan 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

jonathanhefner left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Uh oh!

Labels

3 participants

liady commented Jan 25, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 25, 2026 •

edited

Loading