git:20260507.44b06c0 to git:20260601.da7723a

- ---

- 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

-

- ```bash

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

-

- ```bash

- 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

-

- ```json

- {

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

-

- ```json

- {

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

-

- ```javascript

- 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.appName} (${inputs.framework})`,

- skill: {

- name: 'mcp-app-scaffolding',

- context: {

- appName: inputs.appName,

- framework: inputs.framework,

- description: inputs.description,

- transport: inputs.transport,

- existingServer: inputs.existingServer,

- instructions: [

- 'Clone SDK reference code at published npm version',

- 'Execute framework selection decision tree',

- 'Generate project directory structure',

- 'Install all dependencies via npm install',

- 'Create server and client entry points',

- 'Configure Vite with vite-plugin-singlefile',

- 'Set up TypeScript and build scripts'

- ]

- }

- },

- io: {

- inputJsonPath: `tasks/${taskCtx.effectId}/input.json`,

- outputJsonPath: `tasks/${taskCtx.effectId}/result.json`

- }

- };

- }

- });

- ```

-

- ## 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](https://github.com/modelcontextprotocol/ext-apps)

- - [MCP Apps SDK npm](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps)

- - [MCP Apps Quickstart](https://github.com/modelcontextprotocol/ext-apps/blob/main/docs/quickstart.md)

- - [MCP Apps Overview](https://github.com/modelcontextprotocol/ext-apps/blob/main/docs/overview.md)

- - [MCP Specification (2026-01-26)](https://spec.modelcontextprotocol.io/)

-

- ## Related Skills

-

- - mcp-tool-resource-pattern

- - mcp-host-styling-integration

- - single-file-bundling

- - mcp-app-verification

-

- ## Related Agents

-

- - mcp-app-architect

- - mcp-ui-developer