generate-interactive-mcp-app

# Generate Interactive MCP App This skill provides the structure and instructions required to build an interactive, frontend-enabled MCP application using React, Vite, and the Model Context Protocol `ext-apps` SDK. ## Requirements When building an interactive MCP app, you must abide by the following architectural constraints: ### 1. Build System & Bundling - Utilize **Vite** along with `vite-plugin-singlefile`. Interactive MCP apps serve their frontend via custom URI protocols (`ui://...`), making it highly advantageous to bundle the entire React application (HTML, CSS, JS) into a single file to simplify resource serving. - The `mcp-app.html` file must act as the Vite input. ### 2. Required File Structure Your generated workspace should include at least the following: - `package.json`: Include `@modelcontextprotocol/sdk`, `@modelcontextprotocol/ext-apps`, `react`, and `vite`. - `main.ts`: The entry point that opens the transport (e.g., `StdioServerTransport` for Claude Desktop). - `server.ts`: Initializes `McpServer`, sets up tools, and exposes the UI resource. - `vite.config.ts`: Configures the single-file plugin. - `mcp-app.html`: Boilerplate HTML container. - `src/mcp-app.tsx`: The React entrypoint demonstrating the `useApp` hook. - `src/global.css` & `src/mcp-app.module.css`: Global baseline and scoped CSS Modules. ### 3. Connection and Logic (`src/mcp-app.tsx`) - Use the `useApp` hook from `@modelcontextprotocol/ext-apps/react` to wire the UI to the MCP host. - Handle `app.onhostcontextchanged` to calculate `safeAreaInsets` and prevent the UI from being clipped by the Claude Desktop interface. - Handle `app.ontoolresult` to parse incoming data generated by standard MCP tool calls. - Use `app.callServerTool({ name, arguments })` to execute logic directly from user interactions in the UI. ### 4. Styling and Theming Rules - **Color Scheme**: Include `<meta name="color-scheme" content="light dark">` in the HTML head. - **CSS Modules**: Prefer CSS Modules (`*.module.css`) to prevent style collisions between different parts of the interactive card. - **Safe Area Insets**: Always apply padding to the main container mapping to the host's safe area (`hostContext.safeAreaInsets.top|bottom|left|right`). ## AI Implementation Steps When asked to create an MCP UI application, follow these sequential steps: 1. Define the backend dependencies and initialize the `package.json` with correct build scripts (e.g., `tsc && vite build`). 2. Write the backend logic (`server.ts` and `main.ts`) defining the necessary tools and `McpServer` setup. 3. Write the frontend React logic (`mcp-app.tsx`), tightly binding the `useApp` hook with UI state. 4. Implement standard CSS and safe area padding calculations. 5. Provide the user with a setup guide on how to register the app in their `claude_desktop_config.json`.