内容
# 开放设计MCP
[网站](https://nano-step.github.io/open-design-mcp/) · [变更日志](https://nano-step.github.io/open-design-mcp/changelog.html) · [npm](https://www.npmjs.com/package/open-design-mcp) · [GitHub](https://github.com/nano-step/open-design-mcp)
一个_stdio_[模型上下文协议](https://modelcontextprotocol.io/)_服务器，连接编码代理（OpenCode、Claude Code、Cursor、Zed）到正在运行的[开放设计](https://github.com/nexu-io/open-design)守护进程 - 这样您就可以列出项目、获取工件，并且（在即将发布的版本中）通过BYOK从编辑器内部生成完整的设计工件。
## 状态
**v0.17.0 — 13 个 MCP 工具已上线。** 服务器激活了完整的开放设计功能表面：列出/检查项目、保存和检查工件、在项目中持久化文件、格式化Turn 3提示、并通过BYOK与完整的上游系统提示保真度生成设计。有关正在进行的开发，请参阅[开放规范变更](openspec/changes/)，并参阅[已关闭的变更](openspec/changes/archive/)获取历史决策。
## 工具
| 工具 | 动词 | 环境变量要求 | 描述 |
|---|---|---|---|
| `od_list_projects` | 读取 | `OD_DAEMON_URL` | 列出OD守护进程中的所有项目。返回 `{projects: [{id, name, kind?, status?}, …]}`。 |
| `od_get_project` | 读取 | `OD_DAEMON_URL` | 获取一个项目及其工件文件。合并 `GET /api/projects/:id` 和 `GET /api/projects/:id/files`。现在还显示自定义指令、保真度、技能ID、设计系统ID、创建时间、更新时间（当项目设置时） ([#56](https://github.com/nano-step/open-design-mcp/issues/56))。 |
| `od_create_project` | 写入 | `OD_DAEMON_URL` | 创建一个新项目。需要客户端提供的 `id` 匹配 `/^[A-Za-z0-9._-]{1,128}$/` 加上 `name`；可选 `kind`、`fidelity`、`customInstructions`、`skillId`、`designSystemId`、`pendingPrompt`。返回项目详细信息和自动生成的会话ID。`customInstructions` 也镜像到 `metadata.customInstructions` 以兼容守护进程 ([#43](https://github.com/nano-step/open-design-mcp/issues/43))。 |
| `od_update_project` | 写入 | `OD_DAEMON_URL` | 更新项目的名称、自定义指令或元数据。至少需要一个可变字段。`customInstructions` 也镜像到 `metadata.customInstructions` 以兼容守护进程 ([#43](https://github.com/nano-step/open-design-mcp/issues/43))。 |
| `od_delete_project` | 写入 | `OD_DAEMON_URL` | **永久** 删除一个项目（数据库行 + 磁盘目录）。无法撤销。 |
| `od_save_artifact` | 写入 | `OD_DAEMON_URL` | 将HTML工件持久化到守护进程的**全局** 工件存储中，位于 `/app/.od/artifacts/<timestamp>-<identifier>/index.html`。参数：`identifier`（URL安全斜杠， `/^[a-z0-9-]+$/`，3–64 个字符），`title`（人类可读，1–200 个字符），`html`（完整文档）。**不** 按项目范围划分 — 保存的工件不出现在 `od_get_project.files` 中。返回保存的路径 + URL。 |
| `od_save_project_file` | 写入 | `OD_DAEMON_URL` | 将文件持久化**到项目内部**，使其出现在 `od_get_project.files[]` 中，并在守护进程UI中渲染。包装 `POST /api/projects/:id/files`。参数：`projectId`（1–128 个字符），`name`（文件名，无路径分隔符，1–255 个字符），`content`（字符串，最大 ~5 MB）。与 `od_save_artifact`（全局存储）不同，这是按项目范围划分的 — 在您希望文件出现在项目查看器下时使用。 |
| `od_extract_design_system` | 读取 | 无 | 解析 `design-system.html` 工件并返回JSON清单 + 三个CSS块（`od-tokens`、`od-components`、`od-layout`）。纯函数 — 无网络调用，无环境变量。设计系统优先工作流的一部分。 |
| `od_generate_design_system` | 生成（流式） | `OD_DAEMON_URL` + `BYOK_BASE_URL` + `BYOK_API_KEY` + `BYOK_MODEL` | 通过BYOK生成设计系统工件（`design-system.html`）。生成令牌、组件和布局CSS，以及JSON清单和人类可审查的画廊。生成后验证确保输出具有所有必需的标记槽。 |
| `od_update_design_system` | 写入 | `OD_DAEMON_URL`（增量模式：无；语义模式：+ BYOK变量） | 更新现有的设计系统。两种模式：`semantic`（BYOK驱动的自然语言补丁）和 `delta`（确定性JSON合并，无网络）。每次成功更新都会增加 `data-od-version`。 |
| `od_lint_artifact` | 验证 | `OD_DAEMON_URL` | 检查原始HTML文档。仅接受 `{ html }` — 内联内容，而非项目/斜杠引用。返回发现结果 + 代理消息。新可选参数 `designSystemHtml` 启用设计系统特定的检查（DS001–DS005）。 |
| `od_compose_brief` | 格式化 | 无 | 格式化Turn 3提示以供 `od_generate_design` 使用。结合表单答案、品牌规范和页面简介为上游开放设计识别的字符串。纯函数 — 无网络，无环境变量。新可选参数 `designSystemSummary` 用于在Turn 3提示中包含设计系统上下文。 |
| `od_generate_design` | 生成（流式） | `OD_DAEMON_URL` + `BYOK_BASE_URL` + `BYOK_API_KEY` + `BYOK_MODEL`（`BYOK_PROVIDER` 可选，默认为 `openai`） | 通过BYOK管道生成设计。组合上游开放设计系统提示并通过OD守护进程的 `/api/proxy/<provider>/stream` 代理。返回累积的文本。从 `metadata.customInstructions` 读取 `customInstructions`，然后读取顶级字段 ([#43](https://github.com/nano-step/open-design-mcp/issues/43))。接受 `maxTokens`（默认为 64000）以控制完成长度 — 请参阅 [#36](https://github.com/nano-step/open-design-mcp/issues/36)。当 `projectId` 解析为具有 `designSystemId` 的项目时，自动注入设计系统合约。新可选参数 `designSystemMode`（`strict`/`advisory`/`off`）。 |
只有 `od_generate_design` 和 `od_generate_design_system` 需要BYOK变量。其他11种工具仅需 `OD_DAEMON_URL`（或在 `od_compose_brief` 和 `od_extract_design_system` 的情况下，无需任何环境变量）。
**`od_save_project_file` 与 `od_save_artifact`:** 这两种写入工具服务于不同的存储范围。`od_save_artifact` 将内容写入守护进程的**全局** 工件存储 — 有助于共享URL而不绑定到项目。`od_save_project_file` 将内容写入**项目目录**，因此文件出现在 `od_get_project.files[]` 中，并在守护进程的项目UI中渲染。在您希望生成的设计位于项目内时，请使用 `od_save_project_file`；在您希望独立于项目、无项目感知地创建工件时，请使用 `od_save_artifact`。
## 工作原理
当您使用PRD样式的提示调用 `od_generate_design` 时，MCP服务器会本地组合一个~20–50 KB的系统提示（`composeSystemPrompt` 注入设计师章程 + `kind` 特定规则），然后POST到OD守护进程的 `/api/proxy/<provider>/stream` 端点。守护进程是一个薄的直通代理 — 它转发到您的BYOK提供商，将上游流转码为其自己的SSE格式，并将令牌流式返回。MCP服务器累积增量并每25个令牌发出 `notifications/progress`（仅当客户端提供 `progressToken` 时，根据MCP规范）。
**典型时间：** ~10秒用于小部分（单个英雄，段落重写）；1–5分钟用于完整页面；最多10分钟用于复杂的多部分设计。设置 `maxTokens`（默认为64000）以控制完成长度 — 完整页面通常需要30000+令牌；守护进程的静默默认值为8192 ([#36](https://github.com/nano-step/open-design-mcp/issues/36))。服务器超时默认为10分钟（`OD_GENERATE_TIMEOUT_MS`，可配置）。在流式传输中止或超时时，累积的令牌作为部分HTML返回，并带有尾随的 `<!-- Generation timed out... -->` 注释标记和 `isError: true` — 与 `od_save_artifact` 配对以检查部分进度。
完整参考文件：[`docs/architecture/generate-design-flow.md`](./docs/architecture/generate-design-flow.md).
```mermaid
sequenceDiagram
autonumber
participant E as 编辑器
participant M as open-design-mcp
participant D as OD 守护进程
participant P as BYOK 代理
E->>M: 工具/调用 od_generate_design
M->>M: composeSystemPrompt + 延迟BYOK加载
M->>D: POST /api/proxy/openai/stream
D->>P: POST /chat/completions 流式 true
loop SSE 令牌
P-->>D: 增量
D-->>M: 事件增量
end
M-->>E: 工具结果 HTML
```
## 设计系统优先工作流
对于多页面项目，在任何单个页面之前生成设计系统以确保视觉一致性：
1. **生成** 设计系统：使用您的品牌简介调用 `od_generate_design_system`。
2. **保存** 它到项目内：使用 `od_save_project_file`，文件名 `"design-system.html"`。
3. **链接** 它：使用 `od_update_project`，`designSystemId: "design-system.html"`。
4. **生成页面**：每个后续的 `od_generate_design` 调用都自动注入设计系统合约（默认严格模式）。
`od_generate_design` 上的 `designSystemMode` 参数控制强制执行：
- `strict`（链接时默认为）— 页面 **必须** 使用记录的令牌和组件；通过 `od_lint_artifact` 捕获的违规行为。
- `advisory` — 优先使用记录的令牌；应有偏差的理由。
- `off` — 无注入，相当于 v0.17 之前的行为。
使用 `od_lint_artifact` 和 `designSystemHtml` 验证页面是否符合要求（发现 DS001–DS005）。使用 `od_update_design_system` 在不重新生成所有页面的情况下随时间演化系统。
此工作流是完全可选的 — 没有链接的设计系统的项目行为与以前完全相同。
> **v0.17.0 中的已知限制：** 步骤 4（通过 `designSystemId` 链接自动注入）当前在运行时是一个 no-op。由于守护进程的文件列表端点仅返回元数据 — 而不是文件内容 — 因此 `od_generate_design` 无法获取并注入链接的设计系统，直到 v0.18 添加内容端点为止。使用 `od_lint_artifact` + `designSystemHtml`（生成后静态检查 DS001–DS005）和 `od_compose_brief` + `designSystemSummary`（Turn 3 提示丰富）代替。两者都完全功能正常。参见 [CHANGELOG.md](./CHANGELOG.md) v0.17.0 "已知限制".
## 安装
在MCP客户端配置（OpenCode / Claude Code / Cursor / Zed）中添加以下条目：
```jsonc
{
"mcp": {
"open-design": {
"command": "npx",
"args": ["-y", "open-design-mcp"],
"env": {
// 选择符合您部署的选项（参见下面选择 `OD_DAEMON_URL`）
"OD_DAEMON_URL": "http://ai-open-design:7456",
"OD_API_TOKEN": "", // 可选；如果您的守护进程需要它，则为 bearer token
// BYOK 变量 — 仅在调用 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" // 可选；openai/anthropic/azure/google/ollama 之一
}
}
}
}
```
服务器仅在设置 **`OD_DAEMON_URL`** 时成功启动 — BYOK 变量在调用 `od_generate_design` 时延迟验证。这让用户可以通过 `od_list_projects` / `od_get_project` 进行探索，而无需配置AI提供商。
## 选择 `OD_DAEMON_URL`
正确的值取决于 **相对于MCP服务器** 的开放设计守护进程的位置（MCP服务器本身运行在编码代理启动的位置）：
| 您的设置 | `OD_DAEMON_URL` |
|---|---|
| MCP服务器和OD守护进程都在共享Docker网络上的容器中运行（例如，通过 [`ai-sandbox-wrapper`](https://github.com/kokorolx/ai-sandbox-wrapper) 使用 `--network ai-sandbox`）— **最常见** | `http://ai-open-design:7456` |
| MCP服务器在Docker容器中运行，OD守护进程在主机上原生运行（在主机端口 `7456` 上暴露） | `http://host.docker.internal:7456`（macOS / Windows Docker Desktop）<br>`http://172.17.0.1:7456`（Linux桥接网关） |
| MCP服务器和OD守护进程都在主机上原生运行（无Docker） | `http://localhost:7456` |
| OD容器通过 `ai-run open-design start --expose --port N` 启动到主机端口 `N` | `http://host.docker.internal:N`（从另一个容器内部）<br>`http://localhost:N`（从主机） |
**快速诊断**（从MCP服务器将运行的环境中运行）：
```bash
curl -fsS http://ai-open-design:7456/ && echo " OK" # 共享docker网络
curl -fsS http://host.docker.internal:7456/ && echo " OK" # 主机网关
curl -fsS http://localhost:7456/ && echo " OK" # 原生
```
无论哪一个返回 `200`，您的正确 `OD_DAEMON_URL` 就是它。
## 环境变量
| 变量 | 用途 | 由 | 默认值 |
|---|---|---|---|
| `OD_DAEMON_URL` | 开放设计守护进程基础URL — **参见上面选择 `OD_DAEMON_URL`** | **所有工具**（在启动时热校验） | — |
| `OD_API_TOKEN` | OD守护进程强制使用的Bearer令牌 | 可选 | `""`（不发送身份验证头） |
| `OD_AUTH_MODE` | 身份验证模式：`none`、`bearer`或`basic`。如果未设置（令牌集 → `bearer`；设置基本凭证 → `basic`；两者 → `none`） | 可选 | 推断 |
| `OD_BASIC_USER` | HTTP基本身份验证用户名 | `OD_AUTH_MODE=basic` | — |
| `OD_BASIC_PASS` | HTTP基本身份验证密码 | `OD_AUTH_MODE=basic` | — |
| `OD_GENERATE_TIMEOUT_MS` | 服务器端 `od_generate_design` 超时（毫秒）。从之前的120s增加到 [#33](https://github.com/nano-step/open-design-mcp/issues/33) 确认的完整页面生成后 | 可选 | `600000`（10分钟） |
| `BYOK_BASE_URL` | OpenAI兼容的AI提供商基础URL | 仅 `od_generate_design` （延迟校验） | — |
| `BYOK_API_KEY` | 提供商API密钥通过OD的 `/api/proxy/*/stream` 转发 | 仅 `od_generate_design` | — |
| `BYOK_MODEL` | 模型ID（例如 `open-design`、`claude-sonnet-4-6`) | | 仅 `od_generate_design` | — |
| `BYOK_PROVIDER` | 可选；openai/anthropic/azure/google/ollama 之一 | 可选 | `openai` |
如果OD守护进程后面有反向代理使用HTTP基本身份验证（例如位于 `https://od.thnkandgrow.com/` 的公开实例），请设置 `OD_AUTH_MODE=basic` 和匹配的凭证：
```jsonc
{
"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": "<您的用户名>",
"OD_BASIC_PASS": "<您的密码>"
}
}
}
}
```
服务器会在每次请求OD守护进程时发出 `Authorization: Basic <base64(user:pass)>`。嵌入URL中的凭证（`https://user:pass@host/`）在启动时被拒绝 — 请改用环境变量。
## 开发
```bash
nvm use # 选择Node 20 per .nvmrc
npm install
npm run lint
npm run typecheck
npm test
npm run build
npm run test:integration # 启动dist/src/server.js，模拟OD守护进程，测试所有8种工具
```
工程测试工具包 [`docs/HARNESS.md`](docs/HARNESS.md) 需要每个功能、修复或重构都经过开放规范提案 → 深度设计 → 规格 → 实现 → 验证 → 审查 → PR → 存档周期。参见 [`docs/stories/`](docs/stories/) 获取正在进行的开发故事。
## 依赖项
该项目从 [`nexu-io/open-design`](https://github.com/nexu-io/open-design) 供应商处获取源代码的子集（Apache License 2.0），因此我们可以组合与上游开放设计Web UI相同的 `systemPrompt` 以供BYOK聊天回合使用 — 而不依赖上游的私有 `@open-design/contracts` 包。
| 路径 | 上游 | 许可证 | 注释 |
|---|---|---|---|
| `vendor/od-contracts/` | [`nexu-io/open-design`](https://github.com/nexu-io/open-design) `packages/contracts/src/` | Apache-2.0 | 13个文件（7个运行时 + 6个仅类型）。固定的提交 + 重同步说明在 [`vendor/od-contracts/VENDORED_FROM.md`](vendor/od-contracts/VENDORED_FROM.md)。同步脚本位于 [`scripts/vendor-sync.sh`](scripts/vendor-sync.sh)。 |
**许可证合规性：**
- 上游LICENSE的副本位于 [`vendor/od-contracts/LICENSE`](vendor/od-contracts/LICENSE) (§4(a))。
- 对供应商文件的任何修改（如果有）都带有 `MODIFICATION` 标头，符合Apache 2.0 §4(b)；有关修改日志，请参见 [`vendor/od-contracts/VENDORED_FROM.md`](vendor/od-contracts/VENDORED_FROM.md) 修改部分。
- 每个供应商文件中保留原始上游版权声明 (§4(c))。
- 属性位于 [`vendor/od-contracts/NOTICE`](vendor/od-contracts/NOTICE) 和引用的顶级 [`NOTICE`](NOTICE) (§4(d))。
所有供应商代码均在相同的Apache License 2.0下重新分发。
## 许可证
Apache License 2.0。有关完整文本，请参见 [`LICENSE`](LICENSE)，有关属性，请参见 [`NOTICE`](NOTICE)。
(c) 2026 kokorolx <kokoro.lehoang@gmail.com>。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器