アーキテクチャ

Stitch SDK は手書きの REST クライアントではありません。Model Context Protocol（MCP）の上に構築された生成済みのドメイン層であり、流れるように書ける TypeScript API を提供しながら、Stitch が提供するすべてのツールについて単一の信頼できる情報源を保つように設計されています。

なぜ REST ではなく MCP なのか

Stitch はすでに、AI エージェントが直接接続する MCP サーバーを運用しています。SDK は別個の REST API サーフェスを維持するのではなく、同じ MCP サーバーに HTTP 経由で接続します。つまり：

単一の API サーフェス。 SDK で利用できるツールは、AI エージェントが使うツールとまったく同じです。ずれが生じません。
即時の更新。 MCP サーバーに新しいツールが追加されると、SDK ジェネレーターが自動的に取り込みます。
エージェントとの互換性。 SDK スクリプトでも AI エージェントでも、同じ callTool のセマンティクスが機能します。

3 つの層

SDK は明確な 3 層アーキテクチャを採用しています：

┌─────────────────────────────────┐
│     stitch (singleton proxy)     │  ← What you import
├─────────────────────────────────┤
│  Stitch / Project / Screen       │  ← Generated domain classes
├─────────────────────────────────┤
│       StitchToolClient           │  ← MCP-over-HTTP transport
└─────────────────────────────────┘

第 1 層：`StitchToolClient`（トランスポート）

基盤となる層です。HTTP 経由で Stitch MCP サーバーに接続し、認証（API キーまたは OAuth）を処理し、任意の MCP ツール用の生の callTool(name, params) を公開します。完全な制御が必要な場合は、この層を直接使用できます。

第 2 層：生成されたドメインクラス（ドメイン）

Stitch、Project、Screen は、2 つのソースファイルから自動生成されます：

tools-manifest.json - すべての MCP ツールの名前、説明、入力スキーマのスナップショットです。
domain-map.json - ツールをドメインクラスとメソッドに割り当てる、手作業で作成されたマッピングです。

生成スクリプトが両方のファイルを読み取り、generated/src/ に TypeScript クラスを出力します。各メソッドは callTool の薄いラッパーで、パラメータのマッピングとレスポンスの解析を処理します。

生成はコンテンツハッシュでロックされています。マニフェストまたはドメインマップが実際に変更されたときにだけ、再生成で差分が生まれます。これにより不要な変更を防ぎます。

第 3 層：`stitch` シングルトン（利便性）

環境変数から StitchToolClient を遅延初期化し、メソッド名に応じて呼び出しを Stitch ドメインクラスまたは StitchToolClient に委譲する Proxy オブジェクトです。

stitch.projects() と書くと、プロキシは Stitch.projects() にルーティングします。stitch.callTool(...) と書くと、StitchToolClient.callTool() にルーティングします。

アイデンティティマップパターン

stitch.project(id) と new Project(client, id) は、API 呼び出しを行わずにハンドルを作成します。ID を解析し（projects/ プレフィックスがあれば除去）、すぐに .generate()、.screens()、.getScreen() を呼び出せる Project オブジェクトを返します。

以前の操作でプロジェクト ID をすでに把握している場合に便利です。再取得する必要はありません。

AI SDK アダプター

stitchTools()（@google/stitch-sdk/ai 由来）は、SDK を Vercel AI SDK エコシステムに橋渡しします。同じ tools-manifest.json を読み取り、generateText() と streamText() に互換性のある Record<string, Tool> を生成します。

アダプターは ai パッケージに実行時の依存関係を一切持ちません。Symbol.for("vercel.ai.schema") を使ってツールスキーマ形式を再構築し、AI SDK のコードを一切インポートせずに内部プロトコルに合わせています。これにより、ドメイン API だけを使う利用者にとって SDK は軽量なままです。

エラーハンドリング

すべてのドメインメソッドはエラーを内部で捕捉し、構造化されたエラーコードを持つ StitchError インスタンスとして再スローします。これにより、捕捉すべきエラータイプが 1 つにまとまります：

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

try {
  await screen.edit("...");
} catch (e) {
  if (e instanceof StitchError) {
    console.error(e.code, e.message);
  }
}