Agentic Design System

ads-mcp

Agentic Design System 的本地 MCP 适配器。它将 ADS 渲染、确定性门禁、评估回执和决策溯源整合为一个稳定的三工具接口，供编码 Agent 使用。

从 npm 运行

将服务指向你希望 ADS 检查其 UI 的项目：

npx --yes [email protected] --root /absolute/path/to/project

MCP 服务无需下载浏览器即可连接，因此冷启动的客户端可以在启动时间预算内发现其工具。首次进行网页渲染之前，请验证或安装一次 Chromium：

npx --yes [email protected] doctor
npx --yes [email protected] setup

如果缺少 Chromium，ads_render 会保留一次被阻止的运行，并附上相同的安装命令，而不是超时或伪造证据。操作者也可以将 PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH 设置为现有且兼容的 Chromium 可执行文件路径。

从源代码构建

在 ADS 仓库中：

npm --prefix packages/ads-mcp install
npm --prefix packages/ads-mcp run build
node packages/ads-mcp/dist/cli.js --root /absolute/path/to/project

可选服务标志：

• --runs-dir <relative-path> 更改项目根目录下的运行目录。默认值为 .ads/runs。
• --allow-origin <origin> 允许一个非本地 HTTP(S) 来源。若要添加更多来源，请重复使用该标志。
• --timeout-ms <number> 更改每个工具的超时时间。默认值为 30 秒。
• --judge-command、--judge-provider 和 --judge-model 用于配置显式的视觉评审适配器。--judge-arg 可重复使用。
• --swiftui-command 用于配置 SwiftUI 快照适配器。--swiftui-arg 和 --swiftui-detector 可重复使用；--swiftui-renderer 用于在运行清单中标注渲染器。

客户端配置

将已发布的软件包用作本地 stdio 服务。替换项目路径：

{
  "mcpServers": {
    "ads": {
      "command": "npx",
      "args": [
        "--yes",
        "[email protected]",
        "--root",
        "/absolute/path/to/project"
      ]
    }
  }
}

服务初始化说明会告知客户端先进行渲染和评估：

ads_render -> ads_evaluate

ads_trace 为条件调用。只有在读取运行清单并确认其中至少包含一个已观察到的技能文件、源文件和构件文件后，才调用它。使用清单中记录的准确根目录相对路径和摘录。切勿编造溯源路径，也不要用提示词标签或 URL 替代。

注册表名称：io.github.aa-on-ai/agentic-design-system。

对于 URL 目标，默认状态使用原始 URL。每个请求的非默认状态都会以 #state=<name> 的形式加载，因此应用应从 location.hash 读取 state 参数。

协议与扩展策略

该服务基于拆分的 MCP TypeScript SDK v2 软件包构建，并通过 serveStdio 启动。一个二进制文件同时接受旧版 initialize 客户端，以及通过 server/discover 协商 2026-07-28 协议的现代客户端。

运行标识符是由 <root>/.ads/runs 支持的持久句柄，而非 MCP 会话标识符。 因此，在同一项目文件系统上，即使客户端、服务和服务实例均为全新实例，也能恢复渲染、评估、追踪和资源读取。

该服务会声明稳定的 MCP Apps 扩展 io.modelcontextprotocol/ui。每个 ADS 工具都链接到 ui://ads/review，这是一个独立的 text/html;profile=mcp-app 资源，可内嵌展示证据、门禁、发现、阻塞项和决策追踪。该应用使用 2026-01-26 Apps 协议，并且只会向兼容的宿主请求服务器工具和服务器资源访问权限。不支持 Apps 的宿主仍可使用相同的三个工具和资源界面。

当前的扩展决策是经过慎重考虑的：

• ADS 不会声明 io.modelcontextprotocol/tasks 扩展。渲染和评估仍是有界的同步调用，因为目前尚不需要异步生命周期；只有在有明确的长时间运行操作，并验证了 TypeScript SDK 和宿主路径后，ADS 才会采用该扩展。它不会使用已弃用的核心任务术语。
• 本地 stdio 不会添加身份验证层。未来任何远程传输在启用前，都必须实现当前 MCP OAuth/OIDC 授权模型。
• 文件系统运行存储适用于单一本地项目根目录，且独立于 MCP 会话。托管或复制运行需要共享的持久存储和并发控制，之后才能声称具备相同的恢复保证。

工具

ads_render

渲染允许的 URL、根目录范围内的 TSX 组件，或启动时配置的 SwiftUI 目标。该工具会捕获所请求的状态和视口，运行适用的平台门禁，并返回 ads://runs/... 资源。

{
  "target": { "type": "url", "url": "http://127.0.0.1:3000/orders" },
  "states": ["default", "loading", "empty", "error"],
  "viewports": [{ "width": 390, "height": 844 }, { "width": 1280, "height": 800 }],
  "waitFor": "main",
  "provenance": {
    "observedSkillFiles": ["skills/design-review/SKILL.md"],
    "sourceFiles": ["brief.md"],
    "artifactFiles": ["src/Orders.tsx"]
  }
}

只有在 axe、溢出、地标和实时区域、所请求的状态、CLS 以及触控目标门禁都有可用的通过证据时，渲染才会标记为 complete。缺少浏览器依赖、超时和门禁失败都会返回保留的 blocked 运行结果，而不会虚报成功。

SwiftUI 通过外部快照适配器使用相同的公共工具：

{
  "target": {
    "type": "swiftui",
    "projectPath": "Orders.xcodeproj",
    "scheme": "Orders",
    "sourcePath": "Orders/ContentView.swift",
    "configuration": "Debug",
    "device": "iPhone 16 Pro"
  },
  "states": ["default", "loading", "empty", "error"],
  "viewports": [{ "width": 393, "height": 852 }]
}

ads_evaluate

规范化已渲染的运行结果，并可选择将其与另一个运行结果进行比较。默认的 judge.mode: "none" 保持不使用模型，并在确定性门禁通过时返回 needs_human。 judge.mode: "configured" 会调用服务器启动时选定的视觉评审适配器，并返回 类型化的判定、量规评分、发现和下一轮修订提示词。

{
  "runId": "run_...",
  "compareToRunId": "run_optional_baseline",
  "rubric": {
    "task": "Make the orders workflow understandable on mobile and desktop",
    "criteria": [
      { "name": "Design Quality", "weight": 35 },
      { "name": "Originality", "weight": 30 },
      { "name": "Craft", "weight": 20 },
      { "name": "Functionality", "weight": 15 }
    ]
  },
  "judge": { "mode": "configured" }
}

服务器会在接受结果前，验证量规评分的确切键、ADS 发现类别、严重性、证据链接、规范化截图区域以及判定一致性。缺失、超时或不一致的评审输出会返回 blocked，绝不会判定为通过。

ads_trace

根据渲染时哈希处理的文件验证最终决策。规则文件必须记录为已观察，源文件和产物文件必须存在且未发生变化，摘录必须完全一致，并且所有证据 URI 都必须解析到同一运行结果内。

对于没有捕获来源信息的纯 URL 检查，请在 ads_evaluate 后停止。如果客户端仍调用 ads_trace，服务器会返回一条可操作的 trace not applicable 错误，而不会解析调用方自行编造的路径。

{
  "runId": "run_...",
  "context": "Orders responsive repair",
  "decisions": [
    {
      "id": "mobile-primary-action",
      "decision": "Keep the primary action reachable on mobile.",
      "artifact": { "path": "src/Orders.tsx", "location": "Primary action row" },
      "rule": {
        "path": "skills/design-review/SKILL.md",
        "excerpt": "All consequential controls need a visible, reachable interaction target."
      },
      "sourceConstraint": {
        "path": "brief.md",
        "excerpt": "The primary action must remain reachable on mobile."
      },
      "evidence": ["ads://runs/run_.../evidence"]
    }
  ]
}

工件与安全

运行工件位于 <root>/.ads/runs/<runId>/ 下。工具会返回简短的结构化结果，以及指向清单、渲染证据、屏幕截图、评估回执、报告、轨迹和轨迹验证的只读资源链接。

resources/list 会枚举最近的运行工件，以便客户端在工具响应丢失后找回这些工件。资源 URI 是稳定的逻辑标识符，而非磁盘路径。例如， ads://runs/<runId>/screenshots/default-390x844.png 对应 <root>/.ads/runs/<runId>/evidence/default-390x844.png；客户端应使用 resources/read。

• 不提供任意命令工具，也不允许调用方选择输出路径。
• 项目文件读取和运行写入都限制在 --root 下，包括符号链接检查。
• URL 输入必须使用 HTTP(S)。默认允许 localhost；其他来源需要在启动时加入允许列表。
• 拒绝包含凭据的 URL，并从回执中移除常见的秘密查询参数。
• 外部适配器以固定 argv 进程运行，不使用 shell。可执行文件必须是绝对路径，且 stdout 有长度限制。
• 模型调用必须同时满足启动配置和每次评估的 judge.mode: "configured"；提供方、模型和调用次数都会写入回执。

验证

npm test

测试套件涵盖旧版初始化和现代 server/discover、MCP App 握手和内联审核操作、完整的 MCP 客户端序列、跨服务运行恢复、Chromium URL 和 TSX 组件捕获、命令适配器 JSON 交换、已配置的视觉判定、SwiftUI 快照证据、渲染对比、资源读取、重复阶段回执、超时和证据不完整时的行为、路径遍历、符号链接逃逸、来源拒绝以及轨迹故障。

当前限制

• 仅支持本地 stdio。不支持远程 HTTP、OAuth 或托管服务。
• MCP App 是可选的渐进增强；原生渲染仍取决于宿主是否实现稳定的 Apps 扩展。
• 不会主动公布 Tasks。
• 浏览器获取需通过 ads-mcp setup 显式执行；MCP 启动时绝不会下载 Chromium。
• 核心包不捆绑提供方 SDK，不选择模型，也不提供通用的 Xcode 快照测试框架。运营者需为其环境提供明确的命令适配器。
• SwiftUI 证据取决于已配置适配器的构建、状态注入和检测能力。
• 默认路径保持确定性，并返回 needs_human；自动判定需要明确选择启用。

完整接口请参阅规范 API 契约和命令适配器协议。