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 templates: 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:
- --template react|vanillajs - Skip template selection prompt
- --no-install - Skip automatic npm install

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
└── 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 and quickstart docs to reference the new CLI tool

Testing

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

# Test scaffolding
cd /tmp
node /path/to/ext-apps/packages/create-mcp-app/dist/index.js my-app --template react
cd my-app && npm install && npm run build

Test plan

Package builds successfully
React template scaffolds and builds
Vanilla JS template scaffolds correctly
CLI help displays correctly
Prettier passes on all new files
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: 975cb61

- 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.

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

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

liady commented Jan 25, 2026 •

edited

Loading

Uh oh!

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

edited

Loading

Uh oh!

jonathanhefner left a comment

Uh oh!

jonathanhefner Jan 27, 2026

Uh oh!

jonathanhefner Jan 27, 2026

Uh oh!

jonathanhefner Jan 27, 2026

Uh oh!

jonathanhefner Jan 27, 2026

Uh oh!

jonathanhefner Jan 27, 2026

Uh oh!

jonathanhefner Jan 27, 2026

Uh oh!

jonathanhefner Jan 27, 2026

Uh oh!

jonathanhefner Jan 27, 2026

Uh oh!

jonathanhefner Jan 27, 2026

Uh oh!

jonathanhefner Jan 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

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

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

Uh oh!

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

Uh oh!

Uh oh!

jonathanhefner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

liady commented Jan 25, 2026 •

edited

Loading

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

edited

Loading