Website · Changelog · npm · GitHub

A stdio Model Context Protocol server that bridges coding agents (OpenCode, Claude Code, Cursor, Zed) to a running Open Design daemon — so you can list projects, fetch artifacts, and (in upcoming releases) generate full design artifacts via BYOK from inside your editor.

v0.17.0 — 13 MCP tools live. The server activates the full Open Design feature surface: list/inspect projects, save and lint artifacts, persist files inside projects, format Turn 3 prompts, and generate designs via BYOK with the full upstream system-prompt fidelity. See open OpenSpec changes for in-flight work and closed changes for historical decisions.

Only od_generate_design and od_generate_design_system require the BYOK vars. The other 11 tools work with just OD_DAEMON_URL (or no env vars in the case of od_compose_brief and od_extract_design_system).

od_save_project_file vs od_save_artifact: These two write tools serve different storage scopes. od_save_artifact writes to the daemon's global artifact store — useful for shareable URLs that aren't tied to a project. od_save_project_file writes inside a project's directory so the file appears in od_get_project.files[] and renders in the daemon's project UI. Use od_save_project_file when you want the generated design to live inside the project; use od_save_artifact for standalone, project-unaware artifacts.

When you invoke od_generate_design with a PRD-style prompt, the MCP server composes a ~20–50 KB system prompt locally (vendored composeSystemPrompt injects designer charter + kind-specific rules), then POSTs to the OD daemon's /api/proxy/<provider>/stream endpoint. The daemon is a thin pass-through proxy — it forwards to your BYOK provider, transcodes the upstream stream into its own SSE format, and streams tokens back. The MCP server accumulates deltas and emits notifications/progress every 25 tokens (only when the client supplied a progressToken, per MCP spec).

Typical timing: ~10 seconds for small sections (single hero, paragraph rewrite); 1–5 minutes for full pages; up to 10 minutes for complex multi-section designs. Set maxTokens (default 64000) to control completion length — full pages typically need 30000+ tokens; the daemon's silent default was 8192 (#36). Server timeout defaults to 10 minutes (OD_GENERATE_TIMEOUT_MS, configurable). On abort or timeout mid-stream, accumulated tokens are returned as partial HTML with a trailing <!-- Generation timed out... --> comment marker and isError: true — pair with od_save_artifact to checkpoint partial progress.

Full reference with file:line citations: docs/architecture/generate-design-flow.md.

sequenceDiagram
    autonumber
    participant E as Editor
    participant M as open-design-mcp
    participant D as OD daemon
    participant P as BYOK proxy
    E->>M: tools/call od_generate_design
    M->>M: composeSystemPrompt + lazy BYOK load
    M->>D: POST /api/proxy/openai/stream
    D->>P: POST /chat/completions stream true
    loop SSE tokens
        P-->>D: delta
        D-->>M: event delta
    end
    M-->>E: tool result HTML

For multi-page projects, generate a design system before any individual pages to ensure visual consistency:

1. Generate a design system: od_generate_design_system with your brand brief.
2. Save it inside the project: od_save_project_file with name: "design-system.html".
3. Link it: od_update_project with designSystemId: "design-system.html".
4. Generate pages: Every subsequent od_generate_design call with that projectId auto-injects the design system contract (strict mode by default).

The designSystemMode argument on od_generate_design controls enforcement:

• strict (default when linked) — pages MUST use documented tokens and components; violations caught by od_lint_artifact.
• advisory — prefer documented tokens; deviations should be justified.
• off — no injection, equivalent to pre-v0.17 behavior.

Use od_lint_artifact with designSystemHtml to verify pages conform (findings DS001–DS005). Use od_update_design_system to evolve the system over time without regenerating all pages.

This workflow is fully opt-in — projects without a linked design system behave exactly as before.

Known limitation in v0.17.0: Step 4 (auto-injection via designSystemId linkage) is currently a runtime no-op. The daemon's files-list endpoint returns metadata only — not file content — so od_generate_design cannot yet fetch and inject the linked design system. Until v0.18 adds a content endpoint, enforce design system adherence via od_lint_artifact + designSystemHtml (post-generation static checks DS001–DS005) and via od_compose_brief + designSystemSummary (Turn 3 prompt enrichment). Both paths are fully functional. See CHANGELOG.md v0.17.0 "Known Limitations".

Add the following entry to your MCP client config (OpenCode / Claude Code / Cursor / Zed):

{
  "mcp": {
    "open-design": {
      "command": "npx",
      "args": ["-y", "open-design-mcp"],
      "env": {
        // Pick the line that matches your deployment (see "Choosing OD_DAEMON_URL" below)
        "OD_DAEMON_URL": "http://ai-open-design:7456",
        "OD_API_TOKEN": "",                            // optional; bearer token if your daemon requires it
        // BYOK vars — only needed if you call od_generate_design
        "BYOK_BASE_URL": "https://your-ai-proxy.example.com/v1",
        "BYOK_API_KEY": "<provider-api-key>",
        "BYOK_MODEL": "open-design",
        "BYOK_PROVIDER": "openai"                      // optional; one of openai/anthropic/azure/google/ollama
      }
    }
  }
}

The server boots successfully with only OD_DAEMON_URL set — the BYOK vars are validated lazily when od_generate_design is invoked. This lets users explore via od_list_projects / od_get_project before wiring an AI provider.

The right value depends on where the Open Design daemon is running relative to the MCP server (which itself runs wherever your coding agent spawns it):

Quick diagnostic (run from the environment where the MCP server will spawn):

curl -fsS http://ai-open-design:7456/ && echo " OK"          # shared docker network
curl -fsS http://host.docker.internal:7456/ && echo " OK"    # host gateway
curl -fsS http://localhost:7456/ && echo " OK"               # native

Whichever one returns 200 is your correct OD_DAEMON_URL.

The server fails fast with a clear stderr message if OD_DAEMON_URL is missing or invalid. BYOK vars are checked only when od_generate_design is called — a missing var yields a friendly tool-level error (isError: true, text "BYOK not configured: missing ..."), never a crash.

If the OD daemon is behind a reverse proxy with HTTP Basic Auth (e.g. the publicly-hosted instance at https://od.thnkandgrow.com/), set OD_AUTH_MODE=basic with the matching credentials:

{
  "mcp": {
    "open-design": {
      "command": "npx",
      "args": ["-y", "open-design-mcp"],
      "env": {
        "OD_DAEMON_URL": "https://od.thnkandgrow.com/",
        "OD_AUTH_MODE": "basic",
        "OD_BASIC_USER": "<your-username>",
        "OD_BASIC_PASS": "<your-password>"
      }
    }
  }
}

The server emits Authorization: Basic <base64(user:pass)> on every request to the OD daemon. Embedded credentials in the URL (https://user:pass@host/) are rejected at startup — use the env vars instead.

nvm use            # picks Node 20 per .nvmrc
npm install
npm run lint
npm run typecheck
npm test
npm run build
npm run test:integration   # spawns dist/src/server.js, mocks the OD daemon, exercises all 8 tools

The engineering harness (docs/HARNESS.md) requires every feature, fix, or refactor to go through an OpenSpec proposal → deep-design → specs → implement → validate → review → PR → archive cycle. See docs/stories/ for in-flight stories.

This project vendors a subset of source from nexu-io/open-design (Apache License 2.0) so we can compose the same systemPrompt the Open Design web UI builds for its BYOK chat turns — without depending on the upstream's private @open-design/contracts package.

License compliance:

• A copy of the upstream LICENSE travels in vendor/od-contracts/LICENSE (§4(a)).
• Modifications to vendored files (if any) carry a MODIFICATION header per Apache 2.0 §4(b); see vendor/od-contracts/VENDORED_FROM.md Modifications section for the running log.
• Original upstream copyright notices in each vendored file are retained verbatim (§4(c)).
• Attribution is in vendor/od-contracts/NOTICE and referenced from the top-level NOTICE (§4(d)).

All vendored code is redistributed under the same Apache License 2.0.

Apache License 2.0. See LICENSE for the full text and NOTICE for attribution.

Copyright (c) 2026 kokorolx kokoro.lehoang@gmail.com.