Stitch SDK Development

Stitch SDK Development

This skill encodes the expertise needed to develop @google/stitch-sdk — the core systems, patterns, and philosophies. It does not enumerate every method (the codebase is the source of truth for that). It teaches you how to think about the system.

The Generation Pipeline

The domain layer is fully generated. No handwritten domain classes. The pipeline has 3 stages:

Stage 1: Capture            Stage 2: Domain Design       Stage 3: Generate
┌──────────────────┐       ┌──────────────────┐        ┌──────────────────────────┐
│ capture-tools.ts │──────▶│  domain-map.json │───────▶│ generate-sdk.ts          │
│                  │       │  (the IR)        │        │                          │
│ Connects to MCP  │       │ Classes, bindings│        │ Deterministic            │
│ server, calls    │       │ arg routing,     │        │ codegen into             │
│ tools/list       │       │ cache, extraction│        │ packages/sdk/generated/  │
└──────────────────┘       └──────────────────┘        └──────────────────────────┘
        │                          │                           │
        ▼                          ▼                           ▼
 tools-manifest.json        domain-map.json          packages/sdk/generated/src/*.ts
 (raw MCP tool schemas)     (tool→class mapping)     (Stitch, Project, Screen)

Stage 1 (bun scripts/capture-tools.ts): Connects to the live Stitch MCP server, calls tools/list, writes tools-manifest.json. Source of truth for what tools exist.

Stage 2 (agent/human): Reads the manifest and produces domain-map.json — the intermediate representation. This is where judgment lives: which tool maps to which class, what args come from self vs param vs computed, how to extract the return value, and what data to cache.

Stage 3 (bun scripts/generate-sdk.ts): Deterministic codegen. Reads manifest + domain-map, emits TypeScript classes in packages/sdk/generated/src/. No LLM involved — pure template expansion.

Integrity: stitch-sdk.lock records SHA-256 hashes of all inputs and outputs. bun scripts/validate-generated.ts verifies consistency. Run in CI to prevent publishing stale code.

Supporting a New Tool

When the Stitch MCP server adds a new tool:

1. Run Stage 1 to capture the updated manifest
2. Run Stage 2: add a binding in domain-map.json for the new tool
3. Run Stage 3 to regenerate the SDK classes
4. Run validate-generated.ts to confirm consistency
5. Update tests as needed

The Domain Map IR

domain-map.json expresses two things:

Classes: What domain objects exist and how they're constructed.

{
  "Screen": {
    "constructorParams": ["projectId", "screenId"],
    "parentField": "projectId",
    "reference": { "keys": ["projectId", "screenId"] }
  }
}

Bindings: How MCP tools map to class methods.

{
  "tool": "generate_screen_from_text",
  "class": "Project",
  "method": "generate",
  "args": {
    "projectId": { "from": "self" },
    "prompt": { "from": "param" },
    "name": {
      "from": "computed",
      "template": "projects/{projectId}/screens/{screenId}"
    }
  },
  "returns": {
    "class": "Screen",
    "projection": [
      { "prop": "outputComponents", "index": 0 },
      { "prop": "design" },
      { "prop": "screens", "index": 0 }
    ]
  }
}

Arg routing: self = injected from this, param = passed by the caller, computed = built from a template at call time, selfArray = [this.field] wrapped as array.

Response projections: Structured ProjectionStep[] arrays validated against outputSchema. Use index for single items, each for arrays. Empty [] = direct return.

Cache: Methods can specify a cache with a structured projection to check this.data before calling the API:

{
  "cache": {
    "projection": [{ "prop": "htmlCode" }, { "prop": "downloadUrl" }],
    "description": "Use cached download URL from generation response"
  }
}

Dual Modality

The SDK serves two distinct consumers with different needs:

Agent Modality — StitchToolClient

For AI agents and orchestration scripts. Raw tool pipe. The agent receives tool schemas, constructs JSON, sends it, gets JSON back. No domain knowledge required.

Quick Start (Singleton)

The stitch singleton exposes both domain methods and tool methods via a Proxy. No instantiation needed — it lazily creates a StitchToolClient from env vars on first access.

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

// Discover available tools
const { tools } = await stitch.listTools();

// Call any tool by name with a JSON payload
const result = await stitch.callTool("generate_screen_from_text", {
  projectId: "123",
  prompt: "A login page",
});

// Clean up when done
await stitch.close();

The singleton reads STITCH_API_KEY (or STITCH_ACCESS_TOKEN + GOOGLE_CLOUD_PROJECT) from the environment. Set STITCH_BASE_URL to override the server URL. (STITCH_HOST is a deprecated alias, removed in 2.0.)

Direct Instantiation

For explicit control (multiple clients, custom config, testing), instantiate StitchToolClient directly:

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

const client = new StitchToolClient({ apiKey: "my-key" });
const tools = await client.listTools();
const result = await client.callTool("create_project", { title: "My App" });
await client.close();

Config resolution: Constructor params → env vars → defaults. Auth requires either apiKey or accessToken + projectId (validated via Zod at construction time).

Connection: callTool and listTools auto-connect on first call. Concurrent calls safely share the connection via a promise-based lock.

AI SDK Adapter — stitchTools()

For agents built on the Vercel AI SDK. Transforms MCP tool schemas into AI SDK-compatible tool definitions, enabling plug-and-play with generateText().

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

const result = await generateText({
  model: google("gemini-2.0-flash"),
  tools: stitchTools(), // all tools
  // or: stitchTools({ include: ["create_project"] })  // filtered
  prompt: "Create a project called My App",
});

stitchTools() is exported from the /ai subpath to keep the ai dependency optional. It uses the same shared StitchToolClient singleton internally.

The /tools subpath provides O(1) tool lookup with pre-parsed params — static, auth-free, no network call:

import { toolMap } from "@google/stitch-sdk/tools";
const tool = toolMap.get("create_project");
tool.params; // ToolParam[] — flat, pre-parsed
tool.params.filter((p) => p.required); // required params only
tool.inputSchema; // raw ToolInputSchema still available

Both toolDefinitions and toolMap are exported from the @google/stitch-sdk/tools subpath (kept off the root entry so it stays lean).

SDK Modality — Generated Domain Classes

For humans writing precise, programmatic scripts. Generated domain facade over callTool. Typed parameters, domain objects returned, StitchError thrown on failure.

const project = await stitch.createProject({ title: "My App" });
const generation = await project.generate("A login page");
const html = await generation.first.getHtml();

Both modalities share StitchToolClient underneath. The domain classes are a typed layer over callTool.

Error Handling — Throws at the Boundary

All generated methods use throw StitchError for error handling. No Result<T> pattern.

// Generated method pattern (inside each method):
try {
  const raw = await this.client.callTool<any>("tool_name", args);
  return /* extracted result */;
} catch (error) {
  throw StitchError.fromUnknown(error);
}

StitchError.fromUnknown() ensures all errors are normalized to StitchError with a code, message, and recoverability hint.

Infrastructure (Handwritten)

These components remain handwritten as they provide foundational plumbing:

• StitchToolClient — MCP transport, auth, tool invocation
• StitchError — typed error class with codes, messages, recovery hints
• StitchProxy — MCP proxy server for re-exposing Stitch to other agents
• singleton.ts — lazy proxy for stitch export with env var config