How the generate_screen_from_text MCP Tool Works in stitch::generate-design

The generate_screen_from_text MCP tool converts natural-language UI descriptions into fully-rendered Stitch screens by accepting an enhanced prompt, project ID, and optional design system, then returning HTML, screenshots, and component metadata for local storage.

The generate_screen_from_text tool serves as the core intelligence engine within the stitch::generate-design skill in the google-labs-code/stitch-skills repository. This Model-Controlled-Prompt (MCP) endpoint transforms textual interface descriptions into production-ready HTML and CSS through a structured three-layer pipeline. Understanding its architecture reveals how the Stitch ecosystem bridges natural language inputs and tangible design assets.

Three-Layer Architecture

The tool operates through distinct phases defined in plugins/stitch-design/skills/generate-design/SKILL.md. Each layer prepares and refines the request before the final MCP execution.

Prompt Enhancement Pipeline

Before invoking the MCP, the skill refines raw user input into professional UI terminology. This preprocessing removes design-system tokens and structures layout descriptions to optimize model comprehension. The enhancement logic resides in lines 27-55 of the skill file, where the system augments descriptions with professional UX terminology while filtering out implementation-specific keywords.

Project and Design System Resolution

The skill discovers the target projectId via the list_projects utility and optionally binds a design system file. When present, the designSystem parameter passes global styling rules to the MCP server, ensuring generated screens adhere to established brand guidelines. This resolution occurs in the "Determine the Mode → Generate from Text Flow" section (lines 99-108), which handles the branching logic between new screen generation and existing screen modification.

MCP Execution Layer

The final layer transmits the processed payload to the Stitch MCP server using the stitch::generate_screen_from_text prefix. The server parses the enhanced prompt, maps UI terms to its internal component library, and composes a Sketch-like description that renders to HTML and CSS. This execution is documented in lines 120-133 of the skill file and referenced in the higher-level stitch-loop skill at plugins/stitch-utilities/skills/stitch-loop/SKILL.md.

Input Payload Schema

The tool expects a JSON payload with specific parameters that define the generation context:

{
  "projectId": "12345",
  "prompt": "Sticky navigation bar with glassmorphism effect and centered logo. Hero section with a headline, subtext, and primary CTA button. Feature grid of three cards, each with an image, title, and short description.",
  "designSystem": "assets/design-system.json",
  "deviceType": "DESKTOP"
}

The projectId identifies the target Stitch project, while prompt contains the enhanced natural-language description. The optional designSystem parameter references a JSON file path containing global tokens, and deviceType specifies the target viewport dimensions for responsive rendering.

Response Handling and Asset Management

The MCP server returns an outputComponents object containing:

• textDescription: A human-readable summary of the generated screen elements
• suggestions: Optional improvement recommendations for the UI
• htmlUrl and screenshotUrl: Direct URLs to the generated assets

According to the implementation in SKILL.md, the stitch::generate-design skill automatically downloads these assets into the local .stitch/designs directory using standard HTTP requests. The skill then updates .stitch/metadata.json (lines 49-55) to index the new screen for project tracking.

Implementation Example

A complete workflow involves enhancing the prompt, resolving the project, calling the MCP, and persisting results:

# 1. Enhance prompt (handled by the skill)

enhanced = enhance_prompt(user_prompt)

# 2. Resolve project

proj_id = list_projects().first()['id']

# 3. Generate screen via MCP

result = call_mcp(
    tool="generate_screen_from_text",
    payload={
        "projectId": proj_id,
        "prompt": enhanced,
        "deviceType": "DESKTOP"
    }
)

# 4. Process AI feedback

print(result['outputComponents']['textDescription'])
print(result['outputComponents']['suggestions'])

# 5. Download assets

download(result['outputComponents']['htmlUrl'],
         f".stitch/designs/{result['screenId']}.html")
download(result['outputComponents']['screenshotUrl'],
         f".stitch/designs/{result['screenId']}.png")

The higher-level stitch-loop skill demonstrates similar invocation patterns for site-building workflows, wrapping the tool in iterative generation cycles.

Summary

• The generate_screen_from_text tool requires an enhanced prompt, projectId, and optional designSystem to generate screens through the MCP server
• It processes requests through three layers: prompt enhancement, project resolution, and MCP execution as defined in plugins/stitch-design/skills/generate-design/SKILL.md
• The tool returns structured outputComponents containing descriptions, suggestions, and asset URLs for HTML and screenshot files
• Generated assets are automatically downloaded to .stitch/designs and indexed in .stitch/metadata.json according to the skill's post-generation handling logic

Frequently Asked Questions

What parameters does generate_screen_from_text require?

The tool requires projectId and prompt parameters, optionally accepting designSystem and deviceType. The projectId identifies the target Stitch project discovered via list_projects, while prompt contains the natural-language UI description passed through the skill's enhancement pipeline defined in lines 27-55 of the generate-design skill file.

How does the tool handle design systems?

When a designSystem path is provided in the payload, the MCP server applies global styles from the referenced JSON file to ensure visual consistency. This integration occurs during the project resolution phase before the actual generation begins, allowing the model to map components against established design tokens.

Where are generated screen assets stored?

The stitch::generate-design skill automatically downloads HTML and screenshot files to the .stitch/designs directory within the project root. The skill then updates .stitch/metadata.json to track the new screen metadata, making the generated assets available for further editing or deployment.

Can I use generate_screen_from_text outside the generate-design skill?

Yes, the tool is exposed as a standard MCP endpoint and can be invoked from any skill using the stitch::generate_screen_from_text prefix. The stitch-loop utility skill in plugins/stitch-utilities/skills/stitch-loop/SKILL.md demonstrates this pattern for advanced site-building workflows that require iterative screen generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}