playbooks

home / skills / openclaw / skills / mcp-app-builder

mcp-app-builder skill

/skills/hollaugo/mcp-app-builder

This skill helps you scaffold and implement MCP Apps with React UIs, enforcing exact dependency versions and server/UI patterns.

npx playbooks add skill openclaw/skills --skill mcp-app-builder

Review the files below or copy the command above to add this skill to your agents.

Files (14)
SKILL.md
2.1 KB
---
name: mcp-app-builder
description: Build new MCP Apps (MCP servers with React UI output) using @modelcontextprotocol/ext-apps and the MCP SDK. Use when asked to scaffold or implement MCP App servers, add UI-rendering tools/resources, or migrate a standard MCP server to an MCP App with Vite single-file UI bundles.
---

# MCP App Builder

## Overview
Create MCP Apps that expose tools with visual React UIs for ChatGPT or Claude. Follow the exact dependency versions and server/UI patterns in `references/mcp-app-spec.md`.

## Workflow
1. Clarify requirements: what data to visualize, UI pattern (card, table, chart, dashboard, form), data source, and how many tools (start with 1-2).
2. Design tools and UI mapping: define tool names, zod input schemas, output shape, and UI resource URIs (`ui://.../app.html`). Map each tool to one React entrypoint and one HTML file.
3. Scaffold the project: start from `assets/mcp-app-template/` when possible, then customize tool names, schemas, and UI. Ensure `package.json` uses the exact versions, plus `tsconfig.json`, `vite.config.ts`, Tailwind + PostCSS, and per-tool build scripts.
4. Implement the server: use `registerAppTool`/`registerAppResource`, zod schemas directly, `createServer()` factory per request, and `createMcpExpressApp` with `app.all("/mcp", ...)`.
5. Implement the UI: use `useApp` + `useHostStyles`, parse tool results, handle loading/error/empty states, and apply safe-area insets.
6. Build and test: run `npm run build`, then `npm run serve`, then verify via a tunnel if needed.

## Hard Requirements
- Use the exact dependency versions listed in `references/mcp-app-spec.md`.
- Use `registerAppTool`/`registerAppResource` and zod schemas directly (not JSON Schema objects).
- Create a new `McpServer` instance per request via `createServer()`.
- Use `createMcpExpressApp` and `app.all("/mcp", ...)`.
- Bundle UI into single-file HTML via `vite-plugin-singlefile`.
- Use host CSS variables for theme compatibility.

## References
- `references/mcp-app-spec.md` (authoritative spec, patterns, code templates, gotchas)
## Assets
- `assets/mcp-app-template/` (ready-to-copy MCP App skeleton with one tool + UI)

Overview

This skill scaffolds and builds MCP Apps: MCP servers that expose tools with React UIs packaged as single-file HTML bundles. It guides project layout, exact dependency and build patterns, server wiring, Zod schemas, and UI integration so the app matches the MCP App spec. Use the provided template and tooling to produce repeatable, spec-compliant MCP Apps quickly.

How this skill works

The skill inspects requested UI patterns, tool definitions, and data sources, then scaffolds a project from the MCP App template. It enforces required patterns: Zod input schemas, registerAppTool/registerAppResource usage, createServer() per request, createMcpExpressApp with app.all('/mcp'), and bundling UI into single-file HTML via the Vite single-file plugin. It also configures Tailwind/PostCSS and host CSS variable usage for theme compatibility.

When to use it

  • Scaffold a new MCP App with React-based UI entrypoints and server tooling.
  • Migrate an existing standard MCP server to an MCP App with single-file UI bundles.
  • Add UI-rendering resources or new tools that require per-tool HTML entrypoints.
  • Ensure compliance with the MCP App spec and exact dependency versions before release.

Best practices

  • Start by clarifying data, UI pattern (card/table/chart/form), and number of tools (1–2 to start).
  • Always use Zod schemas directly for tool inputs and outputs; avoid JSON Schema conversions.
  • Create a new McpServer per incoming request via createServer(), never reuse a global instance.
  • Use createMcpExpressApp and app.all('/mcp', ...) so the routing matches the spec.
  • Bundle each tool UI as a single-file HTML with vite-plugin-singlefile and respect host CSS variables for themes.
  • Copy the assets/mcp-app-template and adapt package.json, tsconfig, and per-tool build scripts instead of reinventing the layout.

Example use cases

  • Build an MCP App that visualizes analytics rows as cards and charts, each tool producing a specific React entrypoint.
  • Migrate a CLI-only MCP tool to an app that returns an HTML UI resource (ui://.../app.html) for richer interaction.
  • Add a new report tool with Zod-validated inputs and a table-style React UI bundled into a single HTML file.
  • Create a dashboard app exposing multiple tools and resources, each mapped to its own entrypoint and built via per-tool scripts.

FAQ

Do I have to use the exact dependency versions?

Yes. The MCP App spec requires exact versions to ensure consistent runtime behavior and compatibility with host integrations.

Can I reuse a single McpServer instance across requests?

No. The spec mandates creating a new McpServer per request using createServer() to avoid cross-request state and lifecycle issues.