@google/stitch-sdk

Generate UI screens from text prompts and extract their HTML and screenshots programmatically.

Quick Start

Set your API key and generate a screen:

import { stitch } from "@google/stitch-sdk";

// STITCH_API_KEY must be set in the environment
const project = stitch.project("your-project-id");
const screen = await project.generate(
  "A login page with email and password fields",
);
const html = await screen.getHtml();
const imageUrl = await screen.getImage();

html is a download URL for the screen's HTML. imageUrl is a download URL for the screenshot.

Need to create a project first? Use the tool client:

const result = await stitch.callTool("create_project", { title: "My App" });

Install

npm install @google/stitch-sdk

To use stitchTools() with the Vercel AI SDK, install ai as well:

npm install @google/stitch-sdk ai

Working with Projects and Screens

List existing projects

import { stitch } from "@google/stitch-sdk";

const projects = await stitch.projects();
for (const project of projects) {
  console.log(project.id, project.projectId);
  const screens = await project.screens();
  console.log(`  ${screens.length} screens`);
}

Reference a project by ID

If you already have a project ID, reference it directly:

const project = stitch.project("4044680601076201931");
// Call methods on it — each method fetches data as needed
const screens = await project.screens();

Edit a screen

const screen = await project.generate("A dashboard with charts");
const edited = await screen.edit("Make the background dark and add a sidebar");
const editedHtml = await edited.getHtml();

Generate variants

const variants = await screen.variants("Try different color schemes", {
  variantCount: 3,
  creativeRange: "EXPLORE",
  aspects: ["COLOR_SCHEME", "LAYOUT"],
});

for (const variant of variants) {
  console.log(variant.id, await variant.getHtml());
}

variantOptions fields:

Tool Client (Agent Usage)

For agents and orchestration scripts that need direct MCP tool access:

import { stitch } from "@google/stitch-sdk";

// List available tools
const { tools } = await stitch.listTools();
for (const tool of tools) {
  console.log(tool.name, tool.description);
}

// Call a tool directly
const result = await stitch.callTool("create_project", {
  title: "Agent Project",
});

For explicit configuration (custom API key, base URL), use StitchToolClient directly:

import { StitchToolClient } from "@google/stitch-sdk";

const client = new StitchToolClient({ apiKey: "your-api-key" });
const result = await client.callTool("create_project", {
  title: "Agent Project",
});
await client.close();

The client auto-connects on the first callTool or listTools call. No explicit connect() needed.

AI SDK Integration

Drop Stitch tools directly into the Vercel AI SDK:

import { generateText, stepCountIs } from "ai";
import { google } from "@ai-sdk/google";
import { stitchTools } from "@google/stitch-sdk/ai";

const { text, steps } = await generateText({
  model: google("gemini-2.5-flash"),
  tools: stitchTools(),
  prompt: "Create a project and generate a modern dashboard with a stat card",
  stopWhen: stepCountIs(5),
});

// The model autonomously calls create_project, generate_screen, get_screen
const toolCalls = steps.flatMap((s) => s.toolCalls);
console.log(`Model called ${toolCalls.length} tools`);

Filter to specific tools:

const tools = stitchTools({
  include: ["create_project", "generate_screen_from_text", "get_screen"],
});

ADK Integration

Use Stitch tools with the Google Agent Development Kit (ADK) for TypeScript:

import { stitchAdkTools } from "@google/stitch-sdk/adk";
import { LlmAgent } from "@google/adk";

// Get all Stitch tools formatted as ADK FunctionTools
const tools = stitchAdkTools();

// You can now pass these tools to your ADK agents
const designerAgent = new LlmAgent({
  name: "Designer",
  model: "gemini-2.5-pro",
  instruction: "You are a designer. Create a project and generate a screen.",
  tools,
});

Filter to specific tools:

const tools = stitchAdkTools({
  include: ["create_project", "generate_screen_from_text", "get_screen"],
});

API Reference

Stitch

The root class. Manages projects.

Project

A Stitch project containing screens.

DeviceType: "MOBILE" | "DESKTOP" | "TABLET" | "AGNOSTIC"

Screen

A generated UI screen. Provides access to HTML and screenshots.

getHtml() and getImage() use cached data from the generation response when available. If the screen was loaded from screens() or getScreen(), they call the get_screen API automatically.

modelId: "GEMINI_3_8_FLASH" | "GEMINI_3_5_FLASH_LITE" (optional, defaults to backend default)

DesignSystem

A visual theme or branding applied to projects and screens.

selectedScreenInstances is an array of { id: string, sourceScreen: string } objects. Get these from project.data.screenInstances.

StitchToolClient

Low-level authenticated pipe to the Stitch MCP server. Use this when you need direct tool access (e.g., in an AI agent).

const client = new StitchToolClient({ apiKey: "..." });
const result = await client.callTool("tool_name", { arg: "value" });
await client.close();

stitchTools()

Returns all Stitch MCP tools as Vercel AI SDK Tool objects. Import from @google/stitch-sdk/ai. Drop into generateText() or streamText() — the model calls tools autonomously.

import { generateText, stepCountIs } from "ai";
import { stitchTools } from "@google/stitch-sdk/ai";

const { text } = await generateText({
  model: yourModel,
  tools: stitchTools(),
  prompt: "Create a login page",
  stopWhen: stepCountIs(5),
});

Each tool's execute function calls StitchToolClient.callTool() under the hood. The client is lazily initialized via the singleton.

StitchProxy

An MCP proxy server that forwards requests to Stitch. Use this to expose Stitch tools through your own MCP server.

import { StitchProxy } from "@google/stitch-sdk";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const proxy = new StitchProxy({ apiKey: "..." });
const transport = new StdioServerTransport();
await proxy.start(transport);

stitch Singleton

A pre-configured Stitch instance that reads STITCH_API_KEY from the environment. Lazily initialized on first use.

import { stitch } from "@google/stitch-sdk";

// No setup needed — just use it
const projects = await stitch.projects();

Configuration

Environment Variables

Explicit Configuration

import { Stitch, StitchToolClient } from "@google/stitch-sdk";

const client = new StitchToolClient({
  apiKey: "your-api-key",
  baseUrl: "https://stitch.googleapis.com/mcp",
  timeout: 300_000,
});

const sdk = new Stitch(client);
const projects = await sdk.projects();

Authentication requires either apiKey or both accessToken and projectId.

Error Handling

All domain class methods throw StitchError on failure:

import { stitch, StitchError } from "@google/stitch-sdk";

try {
  const project = stitch.project("bad-id");
  await project.screens();
} catch (error) {
  if (error instanceof StitchError) {
    console.error(error.code); // "UNKNOWN_ERROR"
    console.error(error.message); // Human-readable description
    console.error(error.recoverable); // false
  }
}

Error codes: AUTH_FAILED, NOT_FOUND, PERMISSION_DENIED, RATE_LIMITED, NETWORK_ERROR, VALIDATION_ERROR, CLARIFICATION_REQUIRED, UNKNOWN_ERROR.

Answering a clarifying question

generate(), edit(), variants(), and apply() can end with Stitch asking a question instead of producing screens. That throws a recoverable StitchError with code CLARIFICATION_REQUIRED, and error.clarification holds the question and suggested replies. To answer, call the method again with your answer as the prompt:

import { stitch, StitchError } from "@google/stitch-sdk";

const project = stitch.project("4044680601076201931");
try {
  await project.generate("An app that picks your morning espresso");
} catch (error) {
  if (error instanceof StitchError && error.code === "CLARIFICATION_REQUIRED") {
    console.log(error.clarification?.question);
    const reply = error.clarification?.suggestions[0] ?? "Keep it simple";
    const screen = await project.generate(reply);
    console.log(screen.id);
  } else {
    throw error;
  }
}

Disclaimer

This is not an officially supported Google product. This project is not eligible for the Google Open Source Software Vulnerability Rewards Program.

License

Apache 2.0 — see LICENSE for details.