Add optional Google Stitch MCP as a comp source. (#16)

Remote https://stitch.googleapis.com/mcp via env STITCH_API_KEY.
Not a core server. Not a UI implementer. Bank + Impeccable remain
the product path.

Author: kuker24

CHANGELOG.md

@@ -4,6 +4,17 @@
 
 None.
 
+## 1.8.2 — 2026-09-10
+
+Patch release adding Google Stitch as an optional remote MCP comp source. Total skills remain **62** (46 model-invoked, 16 manual slash commands).
+
+- Add optional Google Stitch remote MCP (`https://stitch.googleapis.com/mcp`) via `opencode-bf stitch enable`.
+- Support `{env:STITCH_API_KEY}` header interpolation or `--oauth` mode without headers.
+- Add `opencode-bf stitch disable` with surgical removal of only `mcp.stitch`.
+- Doctor: stitch is optional; absent != fail, schema violation = fail. Core servers remain 3 (`codebase-memory-mcp`, `context7`, `shadcn`).
+- Router: Stitch MCP is for screen/comp mock generation only, never an automatic production UI implementer. Product UI remains bank + Impeccable + Design V2 atoms + shadcn.
+- Impeccable: treat existing Stitch screens as approved comps; local atom shortlist remains mandatory.
+
 ## 1.8.1 — 2026-09-10
 
 Patch release for Design V2 atomic role locking and Impeccable atom handoff. Total skills remain **62** (46 model-invoked, 16 manual slash commands).

VERSION

@@ -1 +1 @@
-1.8.1
+1.8.2

docs/mcp.md

@@ -13,10 +13,13 @@ Owned:
 Optional:
 
 - `serena` — `opencode-bf serena enable` if the binary is on PATH
+- `stitch` — `opencode-bf stitch enable` (remote comp/mock source only; auth via `{env:STITCH_API_KEY}` or `--oauth`)
 - `exa` — foreign; never add/remove/overwrite
 
 Merge is parse-aware. Comment-free JSON is rewritten with `json.dumps`. JSONC with comments is patched surgically (owned MCP keys only). If surgical merge cannot be verified, install fails closed instead of destroying comments.
 
 Doctor reports `CONFIGURED` for owned MCP entries present in config. That is not a live connection. `opencode-bf doctor --deep` probes `opencode mcp list` per server/per line and **exits 1** unless every core server is `CONNECTED`. `DISCONNECTED`, `NOT_CHECKED`, `LISTED`, empty output, and command failure are not healthy. The substring `connected` inside `disconnected` is not treated as connected. ANSI codes are stripped before parse.
 
 `opencode-bf serena enable` adds Serena only if absent. JSONC comments, provider keys, and foreign MCP are preserved via the same surgical merge as core MCP. Invalid config fails closed.
+
+`opencode-bf stitch enable` configures Google Stitch as an optional remote comp/mock server (`https://stitch.googleapis.com/mcp`). It is not an owned core server and not a UI implementer. Keys are never written directly to config, only referenced via `{env:STITCH_API_KEY}` or omitted when using `--oauth`. `opencode-bf stitch disable` surgically removes only the stitch server key.

docs/routing.md

@@ -22,7 +22,7 @@ MANUAL_NOT_INVOKED
 
 Never list unused tools as used.
 
-UI direction from the bank routes to `found-this-design` first, which stops before component implementation. Visual UI and UI atoms (buttons, inputs, cards, nav) route to `impeccable` after Design V2 shortlist; BANK_MISS ≠ generate (+ shadcn/Design V2 internal). Motion UI routes to `emil-design-eng`. Still/ads/non-UI surface route to `visual-studio`. Scroll-led stories route to `scroll-craft`, while continuous camera 3D fly-throughs route to `scroll-world`.
+UI direction from the bank routes to `found-this-design` first, which stops before component implementation. Visual UI and UI atoms (buttons, inputs, cards, nav) route to `impeccable` after Design V2 shortlist; BANK_MISS ≠ generate (+ shadcn/Design V2 internal). Stitch MCP is for screen/comp generation only, then found-this-design or impeccable with Design V2 atom shortlisting; never implement production UI from Stitch alone. Motion UI routes to `emil-design-eng`. Still/ads/non-UI surface route to `visual-studio`. Scroll-led stories route to `scroll-craft`, while continuous camera 3D fly-throughs route to `scroll-world`.
 
 Browser verification follows four explicit doors: exploratory application UI routes to `playwright-qa`, persistent multi-account sessions route to `browser-act`, observed Chromium cause routes to `chrome-devtools-axi`, and button handler sequential undo / shared-store side effects route to `click-path-audit`.
 

lib/cli.py

@@ -25,6 +25,8 @@
     cmd_restore,
     cmd_restore_list,
     cmd_serena_enable,
+    cmd_stitch_disable,
+    cmd_stitch_enable,
     cmd_uninstall,
 )
 from lib.integrity import cmd_verify  # noqa: E402
@@ -98,6 +100,10 @@ def build_parser() -> argparse.ArgumentParser:
     se = sub.add_parser("serena")
     se.add_argument("action", choices=["enable"])
 
+    st = sub.add_parser("stitch", help="optional Google Stitch remote MCP")
+    st.add_argument("action", choices=["enable", "disable"])
+    st.add_argument("--oauth", action="store_true", help="use OAuth/Bearer auth instead of STITCH_API_KEY header")
+
     sd = sub.add_parser("smartdoc", help="document profiles, extract, status")
     add_smartdoc_cli(sd)
     sb = sub.add_parser("smartbook", help="reusable SmartBook lifecycle")
@@ -153,6 +159,10 @@ def main(argv: list[str] | None = None) -> int:
         return isolation_check(deep=args.deep)
     if cmd == "serena":
         return cmd_serena_enable()
+    if cmd == "stitch":
+        if args.action == "enable":
+            return cmd_stitch_enable(oauth=args.oauth)
+        return cmd_stitch_disable()
     if cmd == "smartdoc":
         return dispatch_smartdoc(args)
     if cmd == "smartbook":

lib/doctor.py

@@ -118,17 +118,32 @@ def mcp_status_map() -> dict[str, str]:
         try:
             data = jsonc.load_path(cfg)
         except (OSError, json.JSONDecodeError, ValueError):
-            return {k: "FAIL" for k in ("codebase-memory-mcp", "context7", "shadcn", "serena", "exa")}
+            return {k: "FAIL" for k in ("codebase-memory-mcp", "context7", "shadcn", "serena", "stitch", "exa")}
     mcp = data.get("mcp") or {}
     owned = {"codebase-memory-mcp", "context7", "shadcn"}
-    for name in ("codebase-memory-mcp", "context7", "shadcn", "serena", "exa"):
+    for name in ("codebase-memory-mcp", "context7", "shadcn", "serena", "stitch", "exa"):
         spec = mcp.get(name)
         if spec is None:
-            out[name] = "OPTIONAL_ABSENT" if name in {"serena", "exa"} else "FAIL"
+            out[name] = "OPTIONAL_ABSENT" if name in {"serena", "stitch", "exa"} else "FAIL"
+            continue
+        if not isinstance(spec, dict):
+            out[name] = "FAIL"
             continue
         if spec.get("enabled") is False:
             out[name] = "DISABLED"
             continue
+        if name == "stitch":
+            typ = spec.get("type")
+            url = spec.get("url")
+            if typ != "remote" or url != "https://stitch.googleapis.com/mcp":
+                out[name] = "FAIL"
+                continue
+            headers = spec.get("headers")
+            if headers is not None and not isinstance(headers, dict):
+                out[name] = "FAIL"
+                continue
+            out[name] = "CONFIGURED"
+            continue
         if name not in owned:
             out[name] = "FOREIGN"
             continue

lib/install.py

@@ -872,7 +872,7 @@ def take(src: Path, dest: Path) -> None:
         "modelInvokedSkills": meta["model"],
         "manualSkills": meta["manual"],
         "ownedMcp": list(OWNED_MCP),
-        "optionalMcp": ["serena", "exa"],
+        "optionalMcp": ["serena", "stitch", "exa"],
         "designBank": {
             "root": bank_root,
             "source": bank_source,
@@ -1291,3 +1291,81 @@ def cmd_serena_enable() -> int:
         path.write_text(jsonc.dumps(data), encoding="utf-8")
     info(f"enabled serena MCP in {path}")
     return 0
+
+
+def cmd_stitch_enable(oauth: bool = False) -> int:
+    if not oauth and not os.environ.get("STITCH_API_KEY", "").strip():
+        die("STITCH_API_KEY environment variable is empty (set STITCH_API_KEY or use --oauth)")
+    spec: dict[str, object] = {
+        "type": "remote",
+        "url": "https://stitch.googleapis.com/mcp",
+        "enabled": True,
+    }
+    if not oauth:
+        spec["headers"] = {
+            "X-Goog-Api-Key": "{env:STITCH_API_KEY}",
+        }
+    path = target_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if not path.is_file():
+        path.write_text(
+            jsonc.dumps({"$schema": "https://opencode.ai/config.json", "mcp": {"stitch": spec}}),
+            encoding="utf-8",
+        )
+        info(f"enabled stitch MCP in {path}")
+        return 0
+    raw = path.read_text(encoding="utf-8")
+    try:
+        data = jsonc.loads(raw)
+    except Exception as exc:
+        die(f"OPENCODE_CONFIG_INVALID: {exc}")
+    if not isinstance(data, dict):
+        die("OPENCODE_CONFIG_INVALID: root is not an object")
+    mcp = data.get("mcp") or {}
+    if not isinstance(mcp, dict):
+        die("OPENCODE_CONFIG_INVALID mcp")
+    if jsonc.contains_comments(raw):
+        try:
+            merged = jsonc.upsert_mcp_servers(raw, {"stitch": spec})
+            jsonc.loads(merged)
+            path.write_text(merged if merged.endswith("\n") else merged + "\n", encoding="utf-8")
+        except Exception as exc:
+            die(f"OPENCODE_CONFIG_JSONC_SURGICAL_FAILED: {exc}")
+    else:
+        data.setdefault("mcp", {})["stitch"] = spec
+        path.write_text(jsonc.dumps(data), encoding="utf-8")
+    info(f"enabled stitch MCP in {path}")
+    return 0
+
+
+def cmd_stitch_disable() -> int:
+    path = target_config_path()
+    if not path.is_file():
+        info("stitch MCP not present; nothing to disable")
+        return 0
+    raw = path.read_text(encoding="utf-8")
+    try:
+        data = jsonc.loads(raw)
+    except Exception as exc:
+        die(f"OPENCODE_CONFIG_INVALID: {exc}")
+    if not isinstance(data, dict):
+        die("OPENCODE_CONFIG_INVALID: root is not an object")
+    mcp = data.get("mcp") or {}
+    if not isinstance(mcp, dict):
+        die("OPENCODE_CONFIG_INVALID mcp")
+    if "stitch" not in mcp:
+        info("stitch MCP not present; nothing to disable")
+        return 0
+    if jsonc.contains_comments(raw):
+        try:
+            merged = jsonc.remove_mcp_servers(raw, ["stitch"])
+            jsonc.loads(merged)
+            path.write_text(merged if merged.endswith("\n") else merged + "\n", encoding="utf-8")
+        except Exception as exc:
+            die(f"OPENCODE_CONFIG_JSONC_SURGICAL_FAILED: {exc}")
+    else:
+        del data["mcp"]["stitch"]
+        path.write_text(jsonc.dumps(data), encoding="utf-8")
+    info(f"disabled stitch MCP in {path}")
+    return 0
+

rules/00-routing.md

@@ -59,6 +59,7 @@ Do not infer a model provider from a logical model name. Treat custom-gateway al
 - Matching or choosing a visual direction from the local design bank (Refero / Motionsites): `/found-this-design` first. Stop before component implementation. Then `/impeccable` after a pick. Bank root comes from `~/.config/opencode/bestfriend/config/design-bank.json` (optional override `OPENCODE_DESIGN_BANK`).
 - Visual UI once a world is chosen, the brief is already visual, or creating UI atoms (buttons, inputs, cards, nav): UI atoms → impeccable after Design V2 shortlist; BANK_MISS ≠ generate. Design V2 shortlist `kind=component` is an internal stage, never a separate specialist route. Do not run `/found-this-design` for atomic components.
 - Design Intelligence is an internal, lazy retrieval stage of Impeccable `new-work`, never a primary route or specialist. Design V2 is the same: an offline user bank, never a specialist.
+- Stitch MCP: screen/comp generation only; then found-this-design or impeccable + Design V2 atoms. Never implement production UI from Stitch alone. Treat existing Stitch screens as approved comps; local atom shortlist remains mandatory.
 - Installable UI components: MCP `shadcn` only. Do not add Magic UI, Kibo, 21st.dev, or community UI MCP servers.
 - Use the hub only when cwd has `components.json`. Never silent `shadcn init` on this adapter, a backend or Python tree, or a non-UI cwd.
 - Scroll-led storytelling (scroll is the timeline, scrollytelling, signature interaction): `/scroll-craft`. Ordinary scrollable UI stays `/impeccable`. `/scroll-craft` plus Continuous World: Scroll Craft writes the brief, then `/scroll-world`.
@@ -103,7 +104,7 @@ Do not infer a model provider from a logical model name. Treat custom-gateway al
 ## Plugins and extra MCP
 
 - No extra marketplace plugins. Foundation = skills + MCP + thin AGENTS.md + runtime helpers.
-- User MCP: `codebase-memory-mcp`, `context7`, and `shadcn` on; `serena` absent until a human enables it; `exa` foreign.
+- User MCP: `codebase-memory-mcp`, `context7`, and `shadcn` on; `serena` and `stitch` absent until a human enables them; `exa` foreign.
 - ECC / other harness overlays: `FOREIGN_ON_DEMAND`. Never add, remove, or merge foreign harness control planes or continuous-learning runtimes. Individual warehouse procedures ported in Wave 2 (agent-architecture-audit, cost-aware-llm-pipeline, eval-harness, prompt-optimizer, skill-stocktake) and Wave 3 (api-design, contract-first, automation-audit-ops, code-tour, click-path-audit) are first-party MIT skills. If external ECC is already present in user environment, do not merge and do not shadow.
 - FOREIGN vendor packs (e.g. `mongodb/agent-skills`, `supabase/agent-skills`, `vercel-labs/agent-skills`) stay off the overlay; user may `npx skills add mongodb/agent-skills|supabase/agent-skills` locally; never `frontend-design` for product UI.
 - Never auto-edit rules or skills from a learning log (no `/learn`, `/evolve`, or session-end skill writers).
@@ -115,6 +116,7 @@ Do not infer a model provider from a logical model name. Treat custom-gateway al
 - Do not load Wave 2 or Wave 3 warehouse skills unless the user explicitly names the job.
 - Do not use vendor `frontend-design` for product UI; UI direction stays `/found-this-design` and implementation stays `/impeccable`.
 - Do not print database connection strings, JWTs, or secret keys in Supabase, MongoDB, or Vercel ops.
+- Do not use Stitch as an automatic UI implementer or let it replace Design V2 atom shortlist.
 - Do not run `/found-this-design` for atomic components (button, input, card, nav); stay in `/impeccable`.
 - Do not auto-start `/grilling` for product interviews or planning; `/grill-with-docs` is the primary route.
 - Do not `@`-import the full routing or verification files into CLAUDE.md.

skills/impeccable/SKILL.md

@@ -22,6 +22,7 @@ Core principles:
    - If empty: report `BANK_MISS`; fall back to shadcn MCP only if cwd contains `components.json`. Never invent arbitrary hex, radius, or typography.
    - If hits exist: pick or take the top role-exact card, record `id`, `provider`, `role`, and `local_path` into `.impeccable/atoms.json` in user project cwd.
    - Implementation must mimic the structure and tokens of that atom + the visual world pack if pinned by `found-this-design`.
+   - If the user provides an existing Stitch screen / mock, treat it as an approved comp (comp-first build path); do not generate code directly from Stitch without shortlisting local Design V2 atoms for components.
    - Forbidden: `image_gen`, vendor `frontend-design`, or ungrounded model taste.
    - World or page-level layout still routes to `found-this-design` first when no world is pinned.
 

templates/AGENTS.md

@@ -33,7 +33,7 @@ repo/file → Codebase Memory MCP first (skip if no project for cwd) → Serena
 
 ## Specialists (load one)
 
-UI direction → skill `found-this-design` then `impeccable`. UI atoms (button, input, card, nav) after world/brief → impeccable after Design V2 shortlist; BANK_MISS ≠ generate (never `found-this-design` for buttons). Motion UI (easing, hover, seam) → `emil-design-eng`. Still/ads/non-UI surface → `visual-studio`. Scroll-led story → `scroll-craft`. Camera/3D world/diorama → `scroll-world`. Registry → shadcn MCP. Design Intelligence and Design V2 are internal to Impeccable `new-work`, never a route.
+UI direction → skill `found-this-design` then `impeccable`. UI atoms (button, input, card, nav) after world/brief → impeccable after Design V2 shortlist; BANK_MISS ≠ generate (never `found-this-design` for buttons). Motion UI (easing, hover, seam) → `emil-design-eng`. Still/ads/non-UI surface → `visual-studio`. Scroll-led story → `scroll-craft`. Camera/3D world/diorama → `scroll-world`. Registry → shadcn MCP. Design Intelligence and Design V2 are internal to Impeccable `new-work`, never a route. Stitch MCP = screen/comp generation only; then found-this-design or impeccable + Design V2 atoms. Never implement production UI from Stitch alone.
 
 Browser QA → skill `playwright-qa`. Explicit/session BrowserAct → `browser-act`. Observed cause → `chrome-devtools-axi` after `opencode-chromium-cdp` (`127.0.0.1:9223`). Never Google Chrome. Project E2E suites (Playwright Test/Cypress) stay authoritative for regressions.