convert_stitch_to_react

The convert_stitch_to_react tool is the single entry point exposed by the HolyStitch MCP server. It accepts Stitch screens either by fetching them from the Stitch API (via projectId) or by receiving raw HTML directly (via htmlScreens), then compiles and writes a full Next.js or Vite project to disk — deterministically, with no AI tokens spent on the conversion itself.

You must provide either projectId (requires STITCH_API_KEY) or htmlScreens. Providing neither returns an error.

Input parameters

projectId

string

The Stitch project ID, found in your Stitch project URL. When provided, HolyStitch fetches all screens (or the subset specified by screenIds) from the Stitch API.Requires the STITCH_API_KEY environment variable to be set in your MCP config:

"env": { "STITCH_API_KEY": "your-key" }

Use this or htmlScreens — not both.

screenIds

string[]

An optional list of screen IDs to convert. When omitted, all screens in the project are converted. Only valid when projectId is also provided.

htmlScreens

array

Pass HTML screens directly instead of fetching from the Stitch API. Each element becomes one page in the output project. Use this when you already have the HTML or when STITCH_API_KEY is not available.

Show HtmlScreen object

string

required

Unique identifier for the screen. Used internally for deduplication.

name

string

required

Human-readable screen name. Determines the route and file name — for example, "Pricing" produces route /pricing and file app/pricing/page.tsx. The first screen always maps to /.

html

string

required

Full HTML string for the screen. May be a complete HTML document (with <head>, <body>) or a body fragment.

outputDir

string

Directory to write the generated project into. Defaults to the current working directory. Pass a relative name like "my-app" to create a sub-folder, or an absolute path.

framework

"nextjs" | "vite"

default:"nextjs"

The React framework to target.

"nextjs" — generates an App Router project with app/ layout, next.config.js, app/layout.tsx, and next/font/google optimization.
"vite" — generates a src/-based project with hash routing via src/App.tsx.

language

"typescript" | "javascript"

default:"typescript"

Output language. TypeScript generates .tsx/.ts files with typed component interfaces; JavaScript generates .jsx/.js files.

styling

"tailwind"

default:"tailwind"

CSS approach. Currently only "tailwind" is supported. The Tailwind theme is extracted directly from the Stitch HTML and written into tailwind.config.js.

Response

The tool returns a JSON object. After it returns, read project-context.md immediately — it contains the routing table, a fix checklist, and instructions for completing the conversion.

summary

string

A human-readable one-line summary of what was converted, e.g. "Converted 3 screens into 14 components and 3 pages".

outputDir

string

The absolute path to the directory where all project files were written.

filesWritten

number

Total number of files written to disk, including components, pages, config files, and source HTML reference files.

pages

array

One entry per screen converted.

Show Page object

route

string

The URL route for this page, e.g. "/", "/pricing", "/changelog". The first screen always receives "/".

path

string

Relative path to the page file within the output directory, e.g. "app/page.tsx" or "app/pricing/page.tsx".

screenName

string

The original screen name as provided in the input, e.g. "Home", "Pricing".

components

string[]

Names of the root-level components imported by this page file.

components

array

All component files written, including nested child components.

Show Component object

name

string

PascalCase component name, e.g. "TopNavBar", "HeroSection", "Footer".

path

string

Relative path to the component file, e.g. "components/TopNavBar.tsx".

sharedComponents

string[]

Component names that appear on two or more screens. These are written once and imported by every page that uses them. Changes to a shared component affect all pages.

hasTailwindTheme

boolean

true if a tailwind.config block was found in the Stitch HTML and extracted into tailwind.config.js. false means the default Tailwind theme was used — you may need to add custom colors manually.

hasCustomCss

boolean

true if any custom CSS was found in <style> blocks in the Stitch HTML and written into globals.css.

sourceHtmlPaths

string[]

Paths to the original HTML files written to stitch-source/ for AI reference, e.g. ["stitch-source/Home.html", "stitch-source/Pricing.html"]. These are the ground truth for pixel-accurate conversion.

warnings

string[]

Structural warnings detected during conversion. Common warnings include:

Unclosed tags — detected by counting open vs. close tags in a component; indicates HTML was cut at a comment boundary inside a nested element.
Color token conflicts — the same Tailwind color token has different values on different screens; you must reconcile them in tailwind.config.js.
Low-similarity component copies — a component with the same name appears on multiple screens but has different content; both versions are written separately (see similarity gating).

Examples

Convert a full project by `projectId`

Fetches all screens from a Stitch project and generates a Next.js TypeScript project in a sub-folder called my-app.

{
  "projectId": "abc123xyz",
  "outputDir": "my-app",
  "framework": "nextjs",
  "language": "typescript",
  "styling": "tailwind"
}

STITCH_API_KEY must be set in your MCP server environment config:

{
  "mcpServers": {
    "holystitch": {
      "command": "node",
      "args": ["/path/to/holystitch/packages/mcp-server/dist/index.js"],
      "env": {
        "STITCH_API_KEY": "your-api-key-here"
      }
    }
  }
}

Convert specific screens by `screenIds`

Fetch only the Home and Pricing screens from a project, generating a Vite JavaScript project.

{
  "projectId": "abc123xyz",
  "screenIds": ["screen_home_01", "screen_pricing_02"],
  "outputDir": "my-vite-app",
  "framework": "vite",
  "language": "javascript",
  "styling": "tailwind"
}

Pass raw HTML screens directly

Use this when you have the HTML already and do not want to set up the Stitch API key.

{
  "htmlScreens": [
    {
      "id": "home",
      "name": "Home",
      "html": "<!DOCTYPE html><html><head>...</head><body><!-- TopNavBar --><nav class=\"flex items-center justify-between p-4\">...</nav><!-- HeroSection --><section class=\"py-20\">...</section></body></html>"
    },
    {
      "id": "pricing",
      "name": "Pricing",
      "html": "<!DOCTYPE html><html><head>...</head><body><!-- TopNavBar --><nav class=\"flex items-center justify-between p-4\">...</nav><!-- PricingTable --><section class=\"grid grid-cols-3 gap-6\">...</section></body></html>"
    }
  ],
  "outputDir": "stitch-output",
  "framework": "nextjs",
  "language": "typescript"
}

In this example, TopNavBar appears on both screens and is detected as a shared component — it is written once to components/TopNavBar.tsx and imported by both page files.

What the tool writes

After a successful conversion, the output directory contains:

my-app/
├── app/
│   ├── layout.tsx          # Root layout with next/font/google and Tailwind globals
│   ├── globals.css         # Tailwind directives + extracted custom CSS + icon font imports
│   ├── page.tsx            # First screen (route "/")
│   └── pricing/
│       └── page.tsx        # Second screen (route "/pricing")
├── components/
│   ├── TopNavBar.tsx       # Shared component — imported by both pages
│   ├── HeroSection.tsx
│   └── PricingTable.tsx
├── stitch-source/
│   ├── Home.html           # Original Stitch HTML — ground truth for pixel-accurate fixes
│   └── Pricing.html
├── project-context.md      # Agent handoff: routing table, fix checklist, source map
├── package.json
├── tailwind.config.js      # Extracted Stitch theme (colors, fonts, dark mode)
├── tsconfig.json
├── postcss.config.js
├── next.config.js
└── .gitignore

Read project-context.md immediately after the tool returns. It contains the full fix checklist and source-to-component mapping. Do not start editing files before reading it.

Similarity gating

When the same component name appears on multiple screens, HolyStitch computes a Jaccard similarity score over word tokens in the two HTML fragments. If the similarity is below 70%, the versions are treated as distinct widgets that happen to share a label. The second version is written as ComponentName + PascalCasedScreenName (e.g. FooterPricing) and a warning is added to warnings[]. If similarity is ≥ 70%, the first version is reused as a shared component.

After the tool returns

The generated project is scaffolded but not finished. Your AI assistant should:

Read project-context.md from top to bottom before touching any file.
Open every stitch-source/*.html file — these are the pixel-accurate reference.
For each component, locate the matching  section in the source HTML and verify the JSX reproduces it faithfully.
Fix JSX errors (unclosed tags, style strings, fragments).
Run npm install && npm run build and fix every error.
Start the dev server and compare each route visually against its source HTML.

MCP Tool

Pipeline Internals

convert_stitch_to_react

Input parameters

Response

Examples

Convert a full project by `projectId`

Convert specific screens by `screenIds`

Pass raw HTML screens directly

What the tool writes

Similarity gating

After the tool returns

Build docs developers (and LLMs) love

MCP Tool

Pipeline Internals

Documentation Index

​Input parameters

​Response

​Examples

​Convert a full project by projectId

​Convert specific screens by screenIds

​Pass raw HTML screens directly

​What the tool writes

​Similarity gating

​After the tool returns

Build docs developers (and LLMs) love

Input parameters

Response

Examples

Convert a full project by `projectId`

Convert specific screens by `screenIds`

Pass raw HTML screens directly

What the tool writes

Similarity gating

After the tool returns