/stitch-mcp-upload-design-md

name: stitch-mcp-upload-design-md
description: Uploads a DESIGN.md file to a Stitch project as the first half of turning it into a Stitch Design System. Always paired with stitch-mcp-create-design-system-from-design-md, which must be called immediately after.
allowed-tools:
  - "stitch*:*"
  - "Bash"
  - "Read"

Stitch MCP — Upload DESIGN.md

Uploads a DESIGN.md file into a Stitch project. This is step one of a two-step pair: the upload creates a screen instance holding the design doc, and `create_design_system_from_design_md` then turns that instance into a real Design System.

**On its own, this tool does nothing useful.** Uploading without the follow-up leaves an orphan screen instance and no design system. Always run both.

Critical prerequisite

**Only use this skill when the user explicitly mentions "Stitch"** in their request. Never trigger Stitch operations silently during regular conversation.

When to use

• The user has a DESIGN.md and wants it applied as a Stitch Design System
• You've just produced a DESIGN.md with `stitch-design-md` and want it driving generation
• The user says "use my design doc in Stitch", "make a design system from DESIGN.md"

Step 1: Read and encode the file

The tool takes base64, not raw markdown. The decoded content **must be valid UTF-8** — uploads with invalid bytes are rejected outright.

# macOS (BSD base64 — no -w flag, and it does not wrap by default)
base64 -i DESIGN.md

# Linux (GNU base64 — -w 0 disables line wrapping)
base64 -w 0 DESIGN.md

> Google's tool description says `base64 -w 0`, which fails on macOS with `invalid option -- w`. Use `-i` there. Getting this wrong produces a confusing shell error rather than an API error, so check your platform first.

Wrapped base64 (with embedded newlines) is a common cause of rejected uploads. Both commands above emit a single unbroken line.

Step 2: Call the MCP tool

{
  "name": "upload_design_md",
  "arguments": {
    "projectId": "3780309359108792857",
    "designMdBase64": "IyBEZXNpZ24gU3lzdGVtCgpDb2xvcnM6IC4uLg=="
  }
}

`projectId` is **numeric only** — no `projects/` prefix. Passing the prefixed path here fails.

Step 3: Capture the screen instance — CRITICAL

The upload creates a **screen instance**, and the next tool needs two identifiers from it. Fetch them with `get_project` (which does take the `projects/` prefix):

{
  "name": "get_project",
  "arguments": { "name": "projects/3780309359108792857" }
}

From the returned `screenInstances`, take the newest entry and record both:

| Field | Example | Notes | |-------|---------|-------| | `id` | `a1b2c3d4e5f6` | The **screen instance** id | | `sourceScreen` | `projects/3780.../screens/98b5...` | Full resource path |

**The trap:** `id` is the screen *instance* id, **not** the source screen id. They are different values and passing the source screen id as `id` fails. Google's own schema calls this out in bold, which is usually a sign it bites people.

Step 4: Immediately call the follow-up

Hand both values straight to `stitch-mcp-create-design-system-from-design-md`. Don't stop between the two steps or report success to the user yet — there's no design system until the second call returns.

ID format rules (critical — different tools need different formats)

| Tool | ID format required | |------|-------------------| | `upload_design_md` | Numeric only: `3780309359108792857` | | `create_design_system_from_design_md` | Numeric only, plus the screen-instance pair | | `get_project` | Full path: `projects/3780309359108792857` |

Integration

• Produce the DESIGN.md first with `stitch-design-md`
• Always follow with `stitch-mcp-create-design-system-from-design-md`
• Once the design system exists, apply it with `stitch-mcp-apply-design-system` or pass its asset id to `generate_screen_from_text`