nano-step/open-design-mcp

open-design-mcp

Skill for using the open-design-mcp server — an MCP wrapper around the Open Design daemon. Teaches an LLM how to pick the right tool, set the right env vars, and recover from common errors.

Overview

open-design-mcp exposes 10 tools that fall into 5 workflows:

| Workflow | Tools | When | |---|---|---| | Read | od_list_projects, od_get_project | Exploring what exists. Read-only. Safe by default. | | Manage | od_create_project, od_update_project, od_delete_project | CRUD on projects. Delete is permanent — no undo. | | Format | od_compose_brief | Pure helper — combines Turn-1 form answers + brand-spec + page brief into a Turn-3 prompt string. No network, no env vars. | | Validate | od_lint_artifact | Cheap sanity-check on HTML before saving. | | Generate | od_generate_design, od_save_artifact, od_save_project_file | Streams an HTML design from a PRD using a Bring-Your-Own-Key LLM, then persists it to the global artifact store (od_save_artifact) or inside a project (od_save_project_file). |

All tools require OD_DAEMON_URL. Only od_generate_design additionally needs BYOK env vars (BYOK_BASE_URL, BYOK_API_KEY, BYOK_MODEL). That asymmetry matters — see references/environment-setup.md.

When to Use This Skill

Trigger on any of these:

| User intent | Recognize from | First tool to call | |---|---|---| | "Show me my projects" | "list projects", "what designs exist", "show all OD projects" | od_list_projects | | "Look at this project" | "get project X", "show artifacts for Y", "what's in this project" | od_get_project | | "Make a new project" | "create project", "start a new design project" | od_create_project | | "Rename / update project" | "change name", "update kind", "set fidelity to mid" | od_update_project | | "Delete project" | "remove project", "delete X" — confirm intent first | od_delete_project | | "Generate a design / mockup" | PRD provided + "make a design", "generate UI", "build a mockup" | od_generate_design | | "Compose a multi-page brief" | User answered discovery questions + has a brand spec + wants per-page prompts | od_compose_brief (then pass result to od_generate_design) | | "Save this HTML to a project" | "save inside the project", "show in OD viewer", "attach to project X" | od_save_project_file (after lint) | | "Save this HTML globally" | "persist", "save artifact", "store this design", standalone shareable URL | od_save_artifact (after lint) | | "Validate this HTML" | "lint", "check for issues", "is this valid?" | od_lint_artifact | | Any 401/403/404/422 from an od_* tool | Error message contains "od_" or "Open Design" | See references/errors.md |

Tool Catalog

Descriptions are verbatim from src/tools/*.ts — do not paraphrase when responding to users.

| Tool | Description | Env vars required | |---|---|---| | od_list_projects | List all projects from the configured Open Design daemon. Read-only; requires only OD_DAEMON_URL. | OD_DAEMON_URL | | od_get_project | Fetch a project + its artifact files. Read-only; requires only OD_DAEMON_URL. Output includes customInstructions if set on the project (user-supplied content). | OD_DAEMON_URL | | od_create_project | Create a new project on the Open Design daemon. Returns the project details and an auto-seeded conversation ID. Requires only OD_DAEMON_URL. | OD_DAEMON_URL | | od_update_project | Update a project on the Open Design daemon. At least one mutable field (name, customInstructions, kind, fidelity, linkedDirs) must be provided. Requires only OD_DAEMON_URL. | OD_DAEMON_URL | | od_delete_project | PERMANENTLY delete a project. The Open Design daemon removes the database row AND the on-disk project directory. This cannot be undone. Requires only OD_DAEMON_URL. | OD_DAEMON_URL | | od_save_artifact | Persist an HTML artifact to the daemon under a slug identifier. Writes to the global artifact store — NOT project-scoped. Requires only OD_DAEMON_URL. | OD_DAEMON_URL | | od_save_project_file | Persist a file (typically HTML from od_generate_design) INSIDE a project so it appears in od_get_project.files[] and renders in the daemon UI. Wraps POST /api/projects/:id/files. Daemon limit: ~5 MB content. | OD_DAEMON_URL | | od_lint_artifact | Validate an HTML artifact for structural issues. Returns text findings + optional agent message. | OD_DAEMON_URL | | od_compose_brief | Format a Turn 3 prompt for od_generate_design. Combines Turn 1 form answers, Turn 2 brand-spec, and the page brief into a single string that upstream Open Design recognizes. Pure function: no network, no env vars. | none | | od_generate_design | Generate a design artifact using BYOK. Composes the upstream Open Design system prompt and proxies through OD's /api/proxy/<provider>/stream endpoint. Requires BYOK_BASE_URL, BYOK_API_KEY, BYOK_MODEL env vars in addition to OD_DAEMON_URL. | OD_DAEMON_URL + BYOK_* |

Core Workflows

Workflow 1 — Explore (read-only, safe)

od_list_projects                 # see what exists
  → pick a project id
od_get_project {id}              # get details + artifact list

No BYOK needed. Use this any time the user asks "what's in OD?" before doing any writes.

Workflow 2 — Create and manage

od_create_project {              # body: name + kind required
  name: "Pricing page",
  kind: "prototype",             # one of: prototype | deck | template | image | doc | research | site
  fidelity: "mid"                # one of: low | mid | high
}
  → returns project id + auto-seeded conversationId

od_update_project {id, name: "...", customInstructions: "..."}   # partial update

od_delete_project {id}           # PERMANENT — always confirm with user first

The customInstructions field is how you bake design preferences ("dark mode", "rounded corners", "Tailwind v4") into all future generations on this project. Set it once on create or update — od_generate_design reads it.

Workflow 3 — Generate, lint, save (the main event)

This is the workflow most users actually want. Order matters:

1. (optional) od_create_project    # if no existing project
2. od_generate_design {            # the streaming one — takes 10–60s
     projectId: "...",
     prompt: "<the PRD or refinement instruction>",
     kind: "prototype"             # match the project's kind
   }
   → returns { html: "<!doctype html>..." }   # full HTML string

3. od_lint_artifact { html }       # CHEAP — always do this before saving
   → returns findings; if any are "error" severity, fix and regenerate

4. Save the result — pick ONE based on where you want the file to live:

   **Option A — global artifact store** (standalone, shareable URL):
   od_save_artifact {
     identifier: "pricing-v1",     # URL-safe slug, /^[a-z0-9-]+$/, 3–64 chars
     title: "Pricing Page v1",     # human-readable, 1–200 chars
     html
   }
   → returns saved path + URL under /app/.od/artifacts/<timestamp>-<identifier>/

   **Option B — inside the project** (appears in od_get_project.files[], renders in daemon UI):
   od_save_project_file {
     projectId,                    # the project you created in step 1
     name: "index.html",           # no path separators, 1–255 chars
     content: html                 # max ~5 MB
   }
   → file shows up in the project's viewer at /api/projects/<id>/files/<name>

Why lint before save: Saving bad HTML costs nothing technically, but linting catches malformed <head> or missing <!doctype> before you tell the user "done" — much better UX than silently shipping broken artifacts.

od_save_artifact vs od_save_project_file: Different storage scopes, not interchangeable. od_save_artifact writes to the daemon's global store (project-unaware) and is right when you want a standalone shareable URL. od_save_project_file writes inside a project's directory so it appears in od_get_project.files[] and renders under the project's UI. Use the project-scoped one when the design is meant to live with the project.

Streaming progress: od_generate_design emits MCP progress notifications every ~25 events. If you're driving from an LLM that exposes those, surface them to the user — generation can take a full minute and silent waits feel broken. See references/byok-providers.md for timeout tuning.

Workflow 4 — Iterate on a broken artifact

od_get_project {id}                # find existing artifact slug
  → read current html via the artifact list

od_generate_design {               # pass a refinement prompt
  projectId,
  prompt: "Fix the broken nav: it should be sticky and use the project's brand colors",
  kind: "prototype"
}
  → returns new html

od_lint_artifact { html }

# Save with the SAME identifier (od_save_artifact) or SAME name (od_save_project_file)
# as last time — both are upsert / last-writer-wins on their respective key.
od_save_artifact { identifier: "pricing-v1", title: "Pricing Page v1", html }
# OR
od_save_project_file { projectId, name: "index.html", content: html }

od_save_artifact is upsert-by-identifier — same identifier overwrites (with a fresh <timestamp>-<identifier> directory). od_save_project_file is upsert-by-name within the project — same name overwrites in place.

See references/workflows.md for fully worked examples with sample tool args.

Anti-Patterns

These all look reasonable and waste real time. Avoid them.

| Don't | Why | Do instead | |---|---|---| | Set BYOK_API_KEY in committed config or .env checked into git | Secrets leak. The proxy URL also identifies your provider account. | Export in shell session only, or use a secret manager. The .gitignore doesn't catch every variant of .env. | | Call od_generate_design before checking OD_DAEMON_URL reaches the daemon | Generation fails 30s in with a confusing error after streaming has already started. | od_list_projects first — it's a 50ms smoke test. | | Pick auth mode manually when you don't know the daemon's setup | Mode-aware 401 hints will tell you. | Leave OD_AUTH_MODE unset — src/config.ts infers from which creds you set. Only override when inference is wrong. | | Skip od_lint_artifact because "the LLM produced HTML so it must be valid" | LLM output frequently misses <!doctype>, has unclosed tags, or wraps the doc in markdown fences. | Always lint before save. Two extra seconds, prevents broken artifacts. | | Use od_delete_project to "clean up test data" without confirming | Daemon removes DB row AND filesystem dir. No undo. | Always show the user the project name + id and ask "delete this permanently? (y/n)" before calling. | | Pass a huge PRD as prompt and hope for the best | Generation is single-turn, no conversation memory. Long prompts get truncated or produce muddled output. | Set persistent design preferences via od_update_project { customInstructions }, then send focused page-specific prompts. | | Ignore OD_API_TOKEN errors on hosted OD | Hosted OD almost always sits behind nginx basic auth — OD_API_TOKEN (bearer) is the wrong mode. | Use OD_AUTH_MODE=basic + OD_BASIC_USER + OD_BASIC_PASS. See references/environment-setup.md. | | Treat od_generate_design streaming output as "almost done" | The HTTP request stays open the whole time — abort kills the generation. | Wait for the tool result. Don't issue a follow-up tool call until od_generate_design returns. | | Ask the user "what's your OD_DAEMON_URL?" before trying anything | The user already configured env vars in their MCP client's env block — re-asking is friction. | Just call the tool. The error message will tell you exactly what's missing (OD_DAEMON_URL errors fail at server startup, not at call-time). | | Try to point a single tool call at a different daemon ("just this one, hit the hosted URL") | OD_DAEMON_URL is read once at server startup from the MCP client's env block (#49). There is no per-call override and no tool accepts a daemonUrl arg. Trying to override mid-session wastes time. | Register two MCP server entries in ~/.config/opencode/opencode.json (or your client's equivalent) — e.g. open-design-local (env → http://ai-open-design:7456) and open-design-hosted (env → https://od.thnkandgrow.com/ + basic auth). Pick which one to call from the tool name prefix. See references/environment-setup.md §"Running against multiple daemons". |

Quick Start

Minimal setup for local Docker OD (no auth):

export OD_DAEMON_URL="http://localhost:7456"
# That's it. od_list_projects works now.

Adding BYOK so od_generate_design works:

export BYOK_BASE_URL="https://api.openai.com/v1"          # or your proxy
export BYOK_API_KEY="sk-..."
export BYOK_MODEL="gpt-4o-mini"                            # or "claude-sonnet-4-6", etc.
export BYOK_PROVIDER="openai"                              # default; one of: openai | anthropic | azure | google | ollama

Hosted OD behind basic auth:

export OD_DAEMON_URL="https://od.example.com"
export OD_AUTH_MODE="basic"
export OD_BASIC_USER="..."
export OD_BASIC_PASS="..."
# + BYOK_* as above for generation

Verification (does NOT need BYOK):

Call od_list_projects with no args.
  → If it returns projects (even empty array): daemon connection works.
  → If it returns 401: see references/errors.md
  → If it returns ECONNREFUSED: daemon isn't running at OD_DAEMON_URL.

References (load on demand)

• references/environment-setup.md — full env-var matrix, auth-mode auto-inference, eager-vs-lazy validation order. Read this when the user asks "how do I configure" or hits any setup error.
• references/byok-providers.md — per-provider config for openai/anthropic/azure/google/ollama, proxy patterns, timeout tuning. Read this when the user mentions a specific LLM provider or asks about cost/speed.
• references/workflows.md — three end-to-end walkthroughs with full tool args. Read this when the user wants a worked example.
• references/errors.md — error-to-fix table for 401/404/422/BYOK-lazy/timeout/connection-refused. Read this on any tool-call failure.

Related Documentation

• Repo README.md — human-facing tool list + installation
• docs/architecture/generate-design-flow.md — deep technical reference (8-phase sequence diagram, system-prompt composition stack) for contributors. Surface to users only if they want internals.
• Upstream Open Design: https://github.com/nexu-io/open-design