@google/stitch-sdk

@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 = await stitch.createProject("My App");
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.

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:

Field	Type	Default	Description
variantCount	number	3	Number of variants (1–5)
creativeRange	string	"EXPLORE"	"REFINE", "EXPLORE", or "REIMAGINE"
aspects	string[]	all	"LAYOUT", "COLOR_SCHEME", "IMAGES", "TEXT_FONT", "TEXT_CONTENT"

Tool Client (Agent Usage)

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

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

const client = new StitchToolClient({ apiKey: "your-api-key" });

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

// Call a tool directly — returns are now strongly typed!
import { CreateProjectResponse } from "@google/stitch-sdk";
const result = await client.callTool<CreateProjectResponse>("create_project", {
  title: "Agent Project",
});
console.log(result.project?.projectId);

await client.close();

The client auto-connects on the first callTool or listTools call. No explicit connect() needed. All tool responses and input parameters are strictly typed and exported from the SDK.

API Reference

Stitch

The root class. Manages projects.

Method	Parameters	Returns	Description
createProject(title)	title: string	Promise<Project>	Create a new project
projects()	—	Promise<Project[]>	List all accessible projects
project(id)	id: string	Project	Reference a project by ID (no API call)

Project

A Stitch project containing screens.

Property	Type	Description
id	string	Alias for projectId
projectId	string	Bare project ID (no projects/ prefix)

Method	Parameters	Returns	Description
generate(prompt, deviceType?)	prompt: string, deviceType?: DeviceType	Promise<Screen>	Generate a screen from a text prompt
screens()	—	Promise<Screen[]>	List all screens in the project
getScreen(screenId)	screenId: string	Promise<Screen>	Retrieve a specific screen by ID

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

Screen

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

Property	Type	Description
id	string	Alias for screenId
screenId	string	Bare screen ID
projectId	string	Parent project ID

Method	Parameters	Returns	Description
edit(prompt, deviceType?, modelId?)	prompt: string	Promise<Screen>	Edit the screen with a text prompt
variants(prompt, variantOptions, deviceType?, modelId?)	prompt: string, variantOptions: object	Promise<Screen[]>	Generate design variants
getHtml()	—	Promise<string>	Get the screen's HTML download URL
getImage()	—	Promise<string>	Get the screen's screenshot download URL

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_PRO" | "GEMINI_3_FLASH"

StitchToolClient

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

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

const client = new StitchToolClient({ apiKey: "..." });
const result = await client.callTool<GetScreenResponse>("get_screen", { projectId: "...", screenId: "..." });
await client.close();

Method	Parameters	Returns	Description
callTool<T>(name, args)	name: string, args: Record<string, any>	Promise<T>	Call an MCP tool
listTools()	—	Promise<{ tools }>	List available tools
connect()	—	Promise<void>	Explicitly connect (auto-called by callTool)
close()	—	Promise<void>	Close the connection

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();

toolMap

Static tool schemas with pre-parsed parameters. Available on stitch.toolMap or as a standalone export. No network call or API key needed.

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

// Look up a tool
const tool = stitch.toolMap.get("generate_screen_from_text");
if (tool) {
  // Pre-parsed params — no JSON Schema parsing needed
  const required = tool.params.filter(p => p.required);
  const optional = tool.params.filter(p => !p.required);
  console.log(required.map(p => p.name)); // ["projectId", "prompt"]
  console.log(optional.map(p => p.name)); // ["deviceType", "modelId"]
}

// Iterate all tools
for (const [name, tool] of stitch.toolMap) {
  for (const param of tool.params) {
    console.log(param.name, param.type, param.required);
  }
}

Each ToolParam has: name, type, description, required, and enum (for constrained values).

The raw inputSchema (ToolInputSchema) is also available on each entry. Standalone exports: toolMap, toolDefinitions, ToolInfo, ToolParam, ToolDefinition, ToolInputSchema, ToolPropertySchema.

Configuration

Environment Variables

Variable	Required	Description
STITCH_API_KEY	Yes (or use OAuth)	API key for authentication
STITCH_ACCESS_TOKEN	No	OAuth access token (alternative to API key)
GOOGLE_CLOUD_PROJECT	With OAuth	Google Cloud project ID
STITCH_HOST	No	Override the MCP server URL

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();

Option	Type	Default	Description
apiKey	string	STITCH_API_KEY	API key
accessToken	string	STITCH_ACCESS_TOKEN	OAuth token
projectId	string	GOOGLE_CLOUD_PROJECT	Cloud project ID
baseUrl	string	https://stitch.googleapis.com/mcp	MCP server URL
timeout	number	300000	Request timeout (ms)

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, UNKNOWN_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.