/mcp-app-scaffolding

name: mcp-app-scaffolding
description: Scaffolds MCP App project structure with correct directory layout, dependencies, entry points, and framework-specific templates. Handles React (useApp hook), Vanilla JS, Vue, Svelte, Preact, and Solid.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
graph:
  domains: [domain:software-engineering]
  specializations: [specialization:ai-agents-conversational]
  skillAreas: [skill-area:mcp-server-implementation, skill-area:mcp-tool-design]
  roles: [role:backend-engineer, role:fullstack-engineer]
  workflows: [workflow:feature-development]
  topics: [topic:api-design, topic:design-patterns]

mcp-app-scaffolding

Scaffold MCP App projects from scratch with correct structure, dependencies, and framework-specific templates following the reference-code-first methodology.

Overview

MCP Apps are interactive UIs that render inline in MCP-enabled hosts (Claude Desktop, ChatGPT, VS Code, Goose, Postman). Every MCP App requires:

• A **Tool** (called by the LLM/host, returns data) registered via `registerAppTool`
• A **Resource** (serves bundled HTML UI) registered via `registerAppResource`
• The tool's `_meta.ui.resourceUri` references the resource's URI

This skill handles the initial project scaffolding: cloning the SDK reference code, selecting a framework, generating the directory structure, and creating all entry points.

Capabilities

Reference Code Acquisition

• Clone SDK repository at exact published npm version
• Access framework templates from `examples/basic-server-{framework}/`
• Access API reference source from `src/`
• Access advanced patterns from `docs/patterns.md`
• Access basic-host reference for testing from `examples/basic-host/`

Framework Selection Decision Tree

• **React** (first-class support): SDK-provided `useApp` hook, `useHostStyles`, `useHostStyleVariables`, `useHostFonts`
• **Vanilla JS**: Manual App lifecycle, simplest setup, no framework overhead
• **Vue / Svelte / Preact / Solid**: Manual lifecycle management, follow team preference

Project Structure Generation

• Directory layout with `src/`, build configs, entry points
• Separate server and client source directories
• Proper `.gitignore` for build artifacts

Dependency Installation

• Runtime: `@modelcontextprotocol/ext-apps`, `@modelcontextprotocol/sdk`, `zod`
• Dev: `typescript`, `vite`, `vite-plugin-singlefile`, `tsx`, `concurrently`
• Framework-specific: `react`, `react-dom`, `@types/react`, `@types/react-dom` (for React)
• Always use `npm install` -- never hardcode version numbers

Usage

Step 1: Clone Reference Code

# Clone SDK at the exact version published to npm
git clone --branch "v$(npm view @modelcontextprotocol/ext-apps version)" \
  --depth 1 https://github.com/modelcontextprotocol/ext-apps.git /tmp/mcp-ext-apps

**Key reference locations:** | Path | Content | |------|---------| | `/tmp/mcp-ext-apps/examples/basic-server-react/` | React template | | `/tmp/mcp-ext-apps/examples/basic-server-vanillajs/` | Vanilla JS template | | `/tmp/mcp-ext-apps/examples/basic-server-vue/` | Vue template | | `/tmp/mcp-ext-apps/examples/basic-server-svelte/` | Svelte template | | `/tmp/mcp-ext-apps/examples/basic-server-preact/` | Preact template | | `/tmp/mcp-ext-apps/examples/basic-server-solid/` | Solid template | | `/tmp/mcp-ext-apps/src/app.ts` | App class API | | `/tmp/mcp-ext-apps/src/server/index.ts` | Server registration helpers | | `/tmp/mcp-ext-apps/src/react/useApp.tsx` | React useApp hook | | `/tmp/mcp-ext-apps/src/styles.ts` | Host styling helpers | | `/tmp/mcp-ext-apps/docs/patterns.md` | Advanced patterns | | `/tmp/mcp-ext-apps/examples/basic-host/` | Test host |

Step 2: Framework Decision Tree

Is the team familiar with React?
  YES -> Use React with useApp hook (SDK-provided, first-class)
  NO  -> Is this a simple app with minimal UI?
           YES -> Use Vanilla JS with manual lifecycle
           NO  -> Use team's preferred framework (Vue/Svelte/Preact/Solid)
                  with manual App lifecycle management

Step 3: Initialize Project

mkdir my-mcp-app && cd my-mcp-app
npm init -y

# Core dependencies
npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/sdk zod

# Dev dependencies
npm install -D typescript vite vite-plugin-singlefile tsx concurrently @types/node

# React-specific (if using React)
npm install react react-dom
npm install -D @types/react @types/react-dom

Step 4: Project Directory Layout

my-mcp-app/
├── src/
│   ├── server.ts          # MCP server with registerAppTool + registerAppResource
│   ├── main.ts            # Client UI entry (or main.tsx for React)
│   └── global.css         # Styles with host CSS variable fallbacks
├── mcp-app.html           # HTML entry point for Vite (or mcp-app.tsx for React)
├── vite.config.ts         # Vite + vite-plugin-singlefile
├── tsconfig.json          # TypeScript configuration
├── package.json           # Scripts: build:ui, build:server, build, dev
└── .gitignore             # dist/, node_modules/, /tmp/

Step 5: Package.json Scripts

{
  "scripts": {
    "build:ui": "vite build",
    "build:server": "tsc --project tsconfig.server.json",
    "build": "npm run build:ui && npm run build:server",
    "dev": "concurrently \"vite\" \"tsx watch src/server.ts\"",
    "serve": "tsx src/server.ts"
  }
}

Step 6: TypeScript Configuration

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "jsx": "react-jsx",
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["node_modules", "dist"]
}

Verification Checklist

• [ ] SDK reference code cloned at pinned version
• [ ] Framework selected based on team context
• [ ] All dependencies installed via `npm install` (no manual versions)
• [ ] Server entry point created