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 (server.ts)
• Client entry point created (main.ts / main.tsx)
• HTML entry point created (mcp-app.html / mcp-app.tsx)
• Vite config with vite-plugin-singlefile present
• Build scripts defined (build:ui, build:server, build)
• TypeScript configured correctly
• .gitignore includes dist/ and node_modules/

Task Definition

const mcpAppScaffoldingTask = defineTask({
  name: 'mcp-app-scaffolding',
  description: 'Scaffold MCP App project structure with framework-specific templates',

  inputs: {
    appName: { type: 'string', required: true },
    framework: { type: 'string', default: 'react' },
    description: { type: 'string', default: '' },
    transport: { type: 'string', default: 'stdio' },
    existingServer: { type: 'boolean', default: false }
  },

  outputs: {
    projectDir: { type: 'string' },
    framework: { type: 'string' },
    files: { type: 'array' },
    artifacts: { type: 'array' }
  },

  async run(inputs, taskCtx) {
    return {
      kind: 'skill',
      title: `Scaffold MCP App:  ()`,
      : {
        : ,
        : {
          : inputs.,
          : inputs.,
          : inputs.,
          : inputs.,
          : inputs.,
          : [
            ,
            ,
            ,
            ,
            ,
            ,
            
          ]
        }
      },
      : {
        : ,
        : 
      }
    };
  }
});

Applicable Processes

• create-mcp-app.js
• add-app-to-mcp-server.js

External Dependencies

• Node.js 18+
• npm
• Git (for cloning SDK reference code)
• @modelcontextprotocol/ext-apps npm package
• @modelcontextprotocol/sdk npm package

References

• MCP Apps SDK Repository
• MCP Apps SDK npm
• MCP Apps Quickstart
• MCP Apps Overview
• MCP Specification (2026-01-26)

Related Skills

• mcp-tool-resource-pattern
• mcp-host-styling-integration
• single-file-bundling
• mcp-app-verification

Related Agents

• mcp-app-architect
• mcp-ui-developer