Secret MCP

English | 한국어

目标架构

---

Secret MCP

一个以证据为依据的 MCP 服务，用于网页设计分析、从截图生成规格说明的工作流，以及前端重构规划。

npx -y secret-design-mcp

Secret MCP 是一个本地模型上下文协议（MCP）服务，可在 GDWEB 搜索近期设计参考，并且为每条搜索结果分别发起 LLM 请求，并创建单独的 DESIGN_INDEX 文件。每个文件都包含可追溯至所提供视觉证据的页面和路由专属布局、导航、像素坐标、颜色、组件及响应式规格。

名称 Secret MCP 并不表示该项目提供秘密功能或私人数据。它是项目在一个私有仓库中尝试围绕设计网站构建 MCP 服务时使用的名称。项目目前的用途是从公开设计参考中提取可复现的结构证据，并为每个作品生成一份规格说明，供大模型应用于新项目。

来自多个作品的图像和描述绝不会合并到同一个 LLM 上下文或文档中。服务在服务端按顺序处理搜索结果，为每个作品单独创建 MCP sampling/createMessage 请求，保存该作品的文件，然后才继续处理下一个作品。另有一个独立的本地 Web 应用，可让你一次选择一个作品，查看其源证据、测量所得的颜色和坐标、LLM 契约、生成日志和最终文档，并管理后续搜索的排除列表。

研究说明

通过 MCP Sampling 实现证据隔离的多模态设计分析

工作论文与实现报告 · Secret MCP v0.6.0 · 未经同行评审

摘要

Secret MCP 实现了一条可审计的流水线，用于将公开网页截图转换为面向实现的设计规格。系统准备桌面端和移动端视觉证据，记录裁剪坐标和代表性像素颜色，并针对每个参考分别调用客户端侧的 MCP sampling。与将多个设计参考拼接到同一提示词中的工作流不同，Secret MCP 将参考的独立性同时视为请求边界和产物边界：一个参考生成一个 sampling 请求、一份请求契约和一份 DESIGN_INDEX 文档。每个请求都要求 includeContext: none，并采用相同的 19 部分规格契约，涵盖路由、几何尺寸、组件、设计令牌、响应式行为、无障碍、实现任务、验收标准和不确定性。本报告评估协议层面的隔离和产物生成；不声称某个大模型、提示词或重构方法优于其他方案。实时冒烟测试验证了请求边界，保留的一组三个参考的运行结果则提供了描述性测量数据和定性实现案例。

研究问题

问题	当前证据	状态
RQ1. MCP 设计分析工具能否维持每个请求只处理一个参考的隔离？	实时 sampling 冒烟测试，包括跨参考 ID 检查和输出文件检查	在测试范围内已验证
RQ2. 能否将截图证据转化为可审计的空间、颜色和文档产物？	保留的一组三个参考的运行结果，包含证据清单、契约和生成的文档	描述性验证
RQ3. 生成的规格能否指导独立的前端实现？	AEROFLOW 定性案例研究	初步结果；无对照比较

形式化系统模型

对于参考项 r_i，准备好的证据集包含图像切片 I、裁剪边界 B、代表性色彩测量值 P 和源元数据 M。固定的规范契约为 C；独立请求和生成的文档分别为 q_i 和 D_i。

E_i = { I_i,k, B_i,k, P_i,k, M_i }
q_i = sampling/createMessage(C, E_i; includeContext = none)
D_i = G_theta(q_i)

References(q_i) = { r_i }
For every i != j: referenceId(r_j) is absent from q_i

在准备好的切片内测量的坐标，按以下方式映射回原始截图。

x_source = (cropLeft + x_tile) / scaleX
y_source = (cropTop  + y_tile) / scaleY

这是操作层面的隔离不变量，并非声称存在统计独立性。服务端和冒烟测试可以检查请求内容和产物；但无法证明任意外部模型提供商会在 MCP 消息之外保留什么内容。

实证结果

协议隔离

flowchart LR
    R1["gdweb-26522"] --> Q1["Request 1<br/>5 evidence images<br/>includeContext: none"] --> D1["DESIGN_INDEX_gdweb-26522.md"]
    R2["gdweb-24516"] --> Q2["Request 2<br/>4 evidence images<br/>includeContext: none"] --> D2["DESIGN_INDEX_gdweb-24516.md"]

采样请求	包含 gdweb-26522	包含 gdweb-24516	输出文档
请求 1	1	0	1
请求 2	0	1	1

图 1。 2026-08-22 记录的实时冒烟测试，使用查询 금융（排除 gdweb-26905 后采样了 n = 2 个参考项）。每个请求都包含自己的参考 ID 和视觉证据，不包含其他采样参考项的 ID，并设置了 includeContext: none；运行生成了两个不同的 Markdown 文件。该测试验证可观察到的请求组成和文件分离情况，不验证协议之外的模型记忆行为。

运行记录测量值

xychart-beta
    title "Prepared evidence images per reference"
    x-axis ["gdweb-27294", "gdweb-25378", "gdweb-24234"]
    y-axis "Evidence images" 0 --> 5
    bar [3, 4, 5]

参考项	桌面端源高度	准备的图像	图像载荷	色彩测量值	文档词元数	文档大小	必需标题
gdweb-27294	2,675px	3	126.6KB	24	7,921	54.0KB	19/19
gdweb-25378	7,043px	4	302.5KB	32	9,953	69.8KB	19/19
gdweb-24234	7,832px	5	387.8KB	40	9,517	63.2KB	19/19

图 2。 来自已保留运行记录 2026-07-29T15-54-10-483Z-5c70317e 的描述性测量数据（n = 3 个参考项）。此次运行准备了 12 张证据图像，总计 816.9 十进制 KB，并记录了 96 项代表性色彩测量值。运行生成了三份 DESIGN_INDEX 文档，总计 27,391 个以空格分隔的词元，大小为 187.0 十进制 KB。三份文档均包含标题 1–19；标题齐全并不能证明语义正确。

定性案例研究

(a) 证据和测量值	(b) 每个参考项的 DESIGN_INDEX	(c) 规范驱动的实现

图 3。 一条已保留的定性追踪记录，展示了从 GDWEB 证据查看器，到生成的 Korean Air DESIGN_INDEX，再到 AEROFLOW 的过程。AEROFLOW 有意引入了新的品牌形象、内容、图像和功能；此示例旨在说明规范的使用方式，并非受控的视觉保真度对比。

解读与局限

• 实时隔离结果的样本量为 n = 2；已记录产物分析的样本量为 n = 3。二者均不足以支持关于设计质量或模型性能的广泛结论。
• 当前评估没有对照组、人工评分、重复试验、置信区间，也没有与截图转代码基线进行比较。
• 代表性色彩是在调整尺寸、进行 JPEG 归一化和通道量化后测量的。这些是截图证据，并不能证明源网站的 CSS 令牌。
• 19/19 结果衡量的是必需标题是否存在。未来的基准测试必须单独评估事实依据、坐标误差、色差、响应式行为和实现保真度。
• 定性实现只是一个存在性示例，并不能证明 Secret MCP 提升了重建质量。

使用

1. 安装和构建

需要 Node.js 20.19 或更高版本。

可以通过以下命令启动已发布的 MCP 服务：

npx -y secret-design-mcp

如果还需要本地查看器，或想处理源代码，请克隆代码仓库：

git clone https://github.com/yyeongjin/secret_mcp.git
cd secret_mcp
npm install
npm run build

2. 启动 Web 应用

为 MCP 服务和 Web 应用设置相同的 DESIGN_INDEX_OUTPUT_DIR 值，以确保两个进程读取同一个输出目录。

DESIGN_INDEX_OUTPUT_DIR=/absolute/path/to/design-index npm run web

在浏览器中打开以下地址。

http://127.0.0.1:4317

Web 应用会显示生成运行列表、各作品的进度、GDWEB 证据图像、测量坐标和配色方案、发送给大模型的规范契约、最终 Markdown，以及生成时间戳。文档和证据均为只读；只有 Exclude from search 和 Remove exclusion 会更改后续搜索所用的筛选条件。

3. 注册 MCP 服务

{
  "mcpServers": {
    "secret-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "secret-design-mcp"
      ],
      "env": {
        "DESIGN_INDEX_OUTPUT_DIR": "/absolute/path/to/design-index",
        "SECRET_MCP_WEB_ORIGIN": "http://127.0.0.1:4317"
      }
    }
  }
}

对于源代码检出，请将 command 和 args 替换为 "command": "node" 和 "args": ["/absolute/path/to/secret_mcp/dist/index.js"]。

MCP 客户端必须支持 sampling/createMessage。客户端不支持采样时，服务会返回明确的错误，而不会运行将多个作品放入同一上下文的回退方案。

MCP stdio 服务本身不会打开 HTTP 端口。客户端会将 node dist/index.js 作为子进程启动，并通过 stdio 交换 JSON-RPC 消息。默认情况下，只有单独的 Web 查看器进程会使用端口 4317。

适用于不支持采样的宿主的直接采样客户端

外层 MCP 宿主无法响应 sampling/createMessage 时，无需修改服务。单独的 MCP 协议客户端可以直接连接到 dist/index.js，声明 sampling: {}，并通过在全新的临时工作区中启动一个全新的 Codex 大模型进程来处理每个采样请求。

const client = new Client(
  { name: 'secret-mcp-sampling-client', version: '1.0.0' },
  { capabilities: { sampling: {} } }
);

client.setRequestHandler(CreateMessageRequestSchema, async request => {
  const workspace = await mkdtemp('secret-mcp-sampling-');
  const response = await launchFreshCodex({
    workspace,
    messages: request.params.messages,
    systemPrompt: request.params.systemPrompt,
  });

  return {
    model: response.model,
    role: 'assistant',
    content: { type: 'text', text: response.markdown },
  };
});

采样处理程序必须仅将当前请求中的文本块和证据图像复制到该工作区。不得重用其他作品的 Codex 对话、进程、工作目录、响应文件或消息历史记录。工作区会启动一个新的 Codex 进程，等待其返回完整的 Markdown 响应，将该响应返回给待处理的 MCP 采样调用，之后在服务保存该作品的契约、证据和文档后即可移除工作区。

服务仍控制顺序队列：作品 1 返回并保存之前，不会准备作品 2。这样一来，全新的进程和工作区在执行层面等同于协议层面的 includeContext: none 边界，同时无需在服务中添加合并回退方案。直接客户端将成为具备采样能力的 MCP 宿主；它应将工具调用超时设置得足够长，以适应每个作品的输出预算，并且绝不能通过一个持久的大模型对话来响应多个采样请求。

4. 请求大模型

无需单独的 /web-design 斜杠命令。

Find three recent design references on GDWEB that are suitable for a Godot project website.
Analyze every search result through a completely independent LLM request,
and create one reproducible DESIGN_INDEX document for each result.
Inside each document, separate every visible page into its own page specification,
and specify everything from navigation and section coordinates to exact color formats and responsive values.

宿主大模型会调用一次 generate-gdweb-design-indexes 工具。MCP 服务执行搜索，并在内部拆分针对各个作品的大模型请求。

手动调用工具的格式如下。

{
  "name": "generate-gdweb-design-indexes",
  "arguments": {
    "query": "game portfolio",
    "limit": 3,
    "awardOnly": true,
    "includePreviousYear": true,
    "language": "English",
    "outputDirectory": "/absolute/path/to/design-index",
    "maxTokens": 131072
  }
}

如果省略 outputDirectory，工具会使用 DESIGN_INDEX_OUTPUT_DIR 环境变量。如果该变量也不存在，则使用服务工作目录下的 design-index 目录。

maxTokens 是每个作品的输出预算，不是整个运行共用的预算，也不会在多个页面之间平均分配。单个作品可能包含多个可见页面或路由，并且每个页面都必须重复 19 节约定中完整的页面专属部分。因此，默认值和最小值均为 131072 个 token。对于特别庞大的多页面证据集，客户端最多可以请求 262144 个 token。

使用 limit: 3 时，默认运行最多可请求三个各自独立的 131072 个 token 输出；作品不会共用一个 131072 个 token 的预算池。连接的采样客户端和所选模型必须支持所请求的输出大小。如果模型返回 stopReason: maxTokens，服务会将该作品视为失败，而不会将被截断的 DESIGN_INDEX 保存为完整结果。

工具完成后，会返回运行 ID、运行清单路径、各作品的文档路径以及网页查看器 URL。

端到端示例：从 GDWEB 规范到 Godot 航空网站

在这个实际示例中，Secret MCP 找到了 2026 年和 2025 年在 GDWEB 注册的三款航空类获奖作品，通过独立的大模型请求为每款作品创建了一个 DESIGN_INDEX，然后将大韩航空参考作品的结构应用于一个 Godot 航空项目网站。

最终完成的 AEROFLOW 网站并非大韩航空网站的克隆。它借鉴了规范中的信息层级、导航、操作面板、版块布局和响应式原则，同时采用了全新的品牌、文案、航空图片和内容。这个示例表明，即使最终设计与参考作品有所不同，经过量化的结构证据仍能打造出精致且具有独特品牌形象的网站。

运行示例

# 1. Build
npm install
npm run build

# 2. Per-work document web viewer
DESIGN_INDEX_OUTPUT_DIR="$PWD/tmp/design-index/aviation-godot-20260730" npm run web

# 3. Specification-driven result website
python3 -m http.server 4320 \
  --bind 127.0.0.1 \
  --directory tmp/showcase/aviation-godot/generated-site

启动进程后，打开以下页面。

• 各作品的规范网页查看器：http://127.0.0.1:4317/?run=2026-07-29T15-54-10-483Z-5c70317e
• AEROFLOW 结果网站：http://127.0.0.1:4320

1. 各作品的规范结果

从左侧的运行列表中逐个选择作品。右侧只会显示所选作品的最终 DESIGN_INDEX，不会混入其他作品的内容。

2. 证据图像与测量结果

Evidence 标签页显示发送给独立大模型请求的桌面端和移动端图像、图块坐标、缩减比例以及代表色。

3. 独立大模型请求约定

Request Contract 记录了页面拆分、导航、版块边界、HEX/RGB/HSL 颜色、组件、响应式矩阵和验收标准。该约定可防止最终结果沦为肤浅的氛围总结，并将其转化为其他大模型可用的实现规范。

4. 生成过程

Generation Log 展示了从搜索和证据准备，到针对每个作品单独发起 LLM 请求、保存文档，再到完整运行结束的流程。本次运行分别为全部三个作品发起了 includeContext: none 请求。

5. 由规范驱动的 AEROFLOW 首屏

我们将 Korean Air 参考设计中观察到的明亮航空门户和操作面板结构改编到了 Godot 项目中。品牌、飞机图片、文案和功能均专为本成果打造。

6. 项目亮点

我们将预订和促销卡片结构重新用于项目核心内容：飞行区域、玻璃驾驶舱和实时天气。

7. 开发日志和快捷入口

我们将源参考中的通知和服务快捷入口重新设计为构建历史、开发进度、飞行模型、航电、媒体、控制和路线图导航。

8. 媒体和页脚

最后的区域包含项目媒体、开发、支持和许可证链接，之后是独立项目页脚。

此成果展示的内容

• 新项目可以采用经过验证的信息层级和布局关系，而无需复制参考设计的标志、商标、文案或图片。
• 将静态截图转换为导航、像素边界、颜色标记、组件和响应式矩阵，可以提供足够详细的信息，让另一个 LLM 制定具体的实现计划。
• 即使使用相同的结构性证据，全新设计的内容、品牌和视觉素材也能打造与源设计截然不同的鲜明风格。
• Secret MCP 旨在从优秀设计中提取结构性证据，并据此为新项目构建精致的网站，而非逐像素复刻源设计。

规范和请求约定

• Korean Air DESIGN_INDEX 规范
• 独立 LLM 请求约定
• 运行清单
• 生成的网站源文件

这些链接直接指向仓库中包含的实际文件。同样的产物也通过相对符号链接归集在 tmp/showcase/aviation-godot 下，便于本地运行和浏览。

核心执行架构

flowchart TD
    User["User request"] --> Host["Host LLM"]
    Host --> Tool["One generate-gdweb-design-indexes call"]
    Tool --> Exclusions["Load the exclusion list managed in the web viewer"]
    Exclusions --> Search["Search GDWEB internally and filter work IDs"]
    Search --> Queue["Keep results inside the server"]
    Queue --> R1["Work 1 images + specification contract"]
    R1 --> S1["Independent sampling/createMessage request 1"]
    S1 --> F1["Save DESIGN_INDEX_gdweb-1.md"]
    F1 --> R2["Work 2 images + specification contract"]
    R2 --> S2["Independent sampling/createMessage request 2"]
    S2 --> F2["Save DESIGN_INDEX_gdweb-2.md"]
    F2 --> More["Repeat sequentially for every work"]
    More --> Manifest["Record per-work evidence and status in run.json"]
    Manifest --> Web["Inspect one work at a time in the local web viewer"]
    Manifest --> Status["Return only file paths and statuses to the host"]

以下边界至关重要。

• 多个作品的图片或规范正文绝不会作为一个批次返回给外部宿主大模型。
• 使用 limit: 3 时，服务恰好执行最多三次相互独立的大模型采样请求。
• 每次采样请求都使用 includeContext: none。
• 每次采样请求只包含一个作品的元数据和图片切片。
• 上一个作品的 ID、图片和分析文档绝不会传入下一个作品的请求。
• 在创建任何采样请求之前，网页查看器中排除的作品都会从搜索结果中移除。
• 服务只有在将当前采样响应保存到文件后，才会开始处理下一个作品。
• 最后，只会向宿主返回生成的文件路径、所用模型以及成功或失败状态。

换句话说，这并非早期那种由宿主大模型一次性读取所有结果并生成综合摘要的架构。

网页查看器

网页查看器每 2.5 秒读取一次 DESIGN_INDEX_OUTPUT_DIR/.secret-mcp-runs。MCP 生成进程与 Web 服务器之间没有单独的数据库或调试连接。

界面包含以下区域。

• 生成运行：查询、请求数量、允许的年份和整体状态
• 作品列表：每个 gdweb-<work-number> 的进度和证据图片数量
• 作品详情：所选作品的规范、证据图片和测量结果、请求约定以及生成日志
• 搜索排除项：将所选作品排除在后续搜索之外、重新纳入该作品，以及管理完整的排除列表

当一次运行包含三个作品时，还会生成如下所示的三份文档。

.secret-mcp-runs/<run-id>/
├── run.json
├── contracts/
│   ├── gdweb-26905.md
│   ├── gdweb-26522.md
│   └── gdweb-xxxxx.md
├── evidence/
│   ├── gdweb-26905_desktop_01-of-05.jpg
│   ├── gdweb-26522_desktop_01-of-04.jpg
│   └── ...
└── documents/
    ├── DESIGN_INDEX_gdweb-26905.md
    ├── DESIGN_INDEX_gdweb-26522.md
    └── DESIGN_INDEX_gdweb-xxxxx.md

run.json 并非用于合并多个作品文档正文的文件。它是一个查看器清单，只包含每个作品的文件路径、状态、时间戳、模型和证据列表。

搜索排除列表

在网页查看器中选择 Exclude from search，会将作品编号保存到以下文件。

DESIGN_INDEX_OUTPUT_DIR/.secret-mcp/exclusions.json

• 历史运行记录和生成的文档绝不会被删除。
• 新的 generate-gdweb-design-indexes 和 search-gdweb-designs 运行会在选择前过滤作品编号。
• 为避免因排除项导致返回的结果过少，搜索会读取更多 GDWEB 候选项，并从未排除的作品中选出指定数量的 limit。
• 选择 Remove exclusion 后，该作品从下一次搜索起会重新符合条件。
• MCP 服务和网页查看器必须使用相同的 DESIGN_INDEX_OUTPUT_DIR，才能共享同一排除列表。

图像处理

GDWEB 的完整桌面截图可能非常高，文件大小也可能达到数 MB。直接在采样请求中发送原始 Base64 数据，可能会超出 MCP 传输限制，或导致视觉模型无法捕捉细微的结构细节。

在为每个作品创建请求之前，gdweb-sampling-images.ts 会执行以下操作。

• 加载 GDWEB 桌面版注册图像，使用 sgbn=1
• 加载 GDWEB 移动版注册图像，使用 sgbn=3
• 将桌面图像调整至最大宽度 1200px
• 将长页面拆分为高度为 1600px、彼此重叠的纵向切片
• 将移动版图像作为单独的证据保留
• 将证据压缩为 JPEG，以减小 MCP 采样请求的大小
• 记录每个切片的原始画布尺寸和处理后画布尺寸、缩放比例、处理后的 x/y/width/height 坐标、源空间坐标及源 URL
• 测量每个切片中的八种代表色，并记录 HEX、RGB、HSL 和像素覆盖率

同一作品的多个切片会包含在同一个该作品专用的采样请求中。不同作品的切片绝不会包含在同一个请求中。

代表色是从归一化后的截图像素中采样测得的。这些数值是进行视觉比较的精确证据，但不能将其作为源网站的 CSS 变量，因为 JPEG 误差和图像内容都会影响数值。生成约定会区分 MEASURED 颜色和 INFERRED 实现令牌。

服务不会打开作品的线上生产网站，也不会抓取其 DOM。视觉证据仅限于 GDWEB 上登记的图像和元数据。

GDWEB 搜索

设计搜索不会使用浏览器自动化、Bing、Brave 或 DuckDuckGo。

Query
  -> POST https://www.gdweb.co.kr/sub/search.asp
  -> form field: Txt_word=<query>
  -> parse the GDWEB result HTML
  -> collect work number, category, and registration year
  -> retain only the current and previous year
  -> load GDWEB detail metadata and registered images

时效策略

• 如果省略 year，则使用当前运行时年份。
• includePreviousYear 默认为 true。
• 在 2026 年运行时，默认仅允许登记于 2026 年和 2025 年的作品。
• 设置 includePreviousYear: false 时，仅允许目标年份的作品。
• awardOnly 默认为 true，因此会排除没有奖项名称的作品。
• limit 可设为 1 至 10。

作品元数据

字段	说明
strNo	GDWEB 作品编号，也用作文档文件名
txtFgbn	GDWEB 作品类别值
title	作品标题
gdwebUrl	GDWEB 作品详情页
registeredDate / registeredYear	登记日期及用于筛选的年份
award	奖项名称
concept	设计概念
primaryColor	主色
productionCompany	制作公司
desktopImageUrl	GDWEB 桌面版截图（sgbn=1）
mobileImageUrl	GDWEB 移动版截图（sgbn=3）

DESIGN_INDEX 规范

每个独立的采样请求都包含 secret-mcp/design-index/v2 合约。生成的文件名为 DESIGN_INDEX_gdweb-<strNo>.md。

每个作品对应一个文件，但每个文件都以页面和路由清单开头，并为每个已验证页面重复一份完整的子章节。合约不会将长滚动截图中的各个区块误认为独立页面；只有当证据拼图中清晰显示不同屏幕时，才会拆分页面。

每份文档都必须包含以下全部 19 个编号章节。

区域	必需规范
重建目标	参考 ID、目标保真度、路由、目标视口和非目标项
证据与坐标系	图像 ID、原始／处理后尺寸、缩放比例、切片坐标、源空间坐标和去除重叠的方法
站点地图	已验证页面和路由、用途、证据图像、共享外壳、当前激活的菜单项和置信度
共享应用外壳	全局背景、容器、边距、叠加层、页面外框和堆叠上下文
导航	桌面和移动端高度、Logo／菜单坐标、间距、触控区域，以及激活／悬停／聚焦／打开状态
逐页规范与坐标表	每个页面的画布模型、区块顺序、x/y/宽度/高度、布局、状态、数据和证据等级
布局深入分析	DOM、grid/flex、轨道、最小／最大值、比例、间距、溢出、sticky、absolute 和 z-index
组件抽象	与页面关联的组件树、props、变体、插槽、状态、事件和数据契约
设计令牌与精确颜色	HEX/RGB/HSL/alpha、用途、测量坐标、置信度、容差和 CSS 变量
字体排版	按角色划分的字体族、px/rem、字重、行高、字距、对齐、截断和响应式取值
资源与图标	所属页面和区块、显示尺寸、宽高比、裁剪、焦点、object-fit、加载和回退策略
响应式矩阵	宽度为 1440/1280/1024/768/390/360px 时的容器、列、顺序、可见性、导航和间距
交互与动效	每种状态下的颜色、不透明度、变换、时长、缓动、键盘操作和减少动态效果时的行为
无障碍	每个页面的 landmark、标题、焦点、菜单语义、标签、替代文本、对比度和触控目标
数据与内容	页面实体、字段、计数、排序、格式、本地化，以及加载／空／错误状态样例
前端架构	路由、目录、页面／共享模块、设计令牌、资源、状态，以及服务端／客户端边界
实现任务图	测量、外壳、导航、逐页任务 ID、依赖项、交付物和完成标准
逐页验收标准	坐标、颜色和字体排版容差；视口对比；溢出；资源；键盘操作；以及性能
不确定项与决策	逐页及逐区块的 UNKNOWN、采用的值、备选方案、置信度和所需的额外证据

每项重要判断都必须标注以下证据等级之一。

• OBSERVED：可直接从 GDWEB 图像或元数据中看到
• MEASURED：已根据提供的像素坐标或测量所得的调色板进行数值验证
• INFERRED：为复现相同结果而合理推断
• UNKNOWN：无法通过静态证据验证，不得作为事实断言

仅凭完整文档，另一个大模型就必须能够推导出组件树、设计令牌、响应式规则、资源、实现顺序和验证项。

暴露的工具

该服务当前暴露五个 MCP 工具。

工具	用途
generate-gdweb-design-indexes	搜索 GDWEB，为每个结果单独发起 LLM 请求，并保存文档
search-gdweb-designs	返回 GDWEB 参考列表，不生成规格说明
full-web-search	搜索整个网络并提取完整页面内容
get-web-search-summaries	返回通用搜索的标题、URL 和描述
get-single-web-page-content	提取已知普通网页的完整内容

将 generate-gdweb-design-indexes 用于设计规划、布局分析、实现规格说明和 DESIGN_INDEX 请求。仅在需要轻量列表时使用 search-gdweb-designs。

源码结构

secret_mcp/
├── src/
│   ├── index.ts                         MCP tool registration and sampling requests
│   ├── dashboard-server.ts              Local web server and document/exclusion APIs
│   ├── design-index-run-store.ts         Run manifest and per-work artifact records
│   ├── design-exclusion-store.ts         Add/remove persistent search exclusions
│   ├── design-index-paths.ts             Shared MCP/viewer output-path resolution
│   ├── gdweb-design-search.ts           GDWEB search, year filtering, and registered-image loading
│   ├── gdweb-design-index-generator.ts  Sequential per-work generation and Markdown saving
│   ├── gdweb-sampling-images.ts         Long-capture resizing, tiling, and compression
│   ├── design-spec-contract.ts          Required DESIGN_INDEX specification contract
│   ├── search-engine.ts                 General Bing, Brave, and DuckDuckGo search
│   ├── enhanced-content-extractor.ts    General webpage content extraction
│   ├── browser-pool.ts                  Browser pool for general content extraction
│   ├── rate-limiter.ts                  General-search request limits
│   ├── types.ts                         Search and tool types
│   └── utils.ts                         URL, text, and timestamp utilities
├── web/
│   ├── index.html                       Web viewer interface
│   ├── styles.css                       Desktop and mobile layout
│   └── app.js                           Run refresh and per-work document switching
├── .github/workflows/
│   ├── ci.yml                           Build, lint, and package validation
│   ├── gdweb-smoke.yml                  Live GDWEB search and image validation
│   └── release.yml                      Release-package generation
├── tmp/DESIGN_CONTEST_SITES.md          Design competition and award website list
├── tmp/reconstructions/
│   └── gdweb-27294-godot/               Specification-driven AEROFLOW static website
├── tmp/showcase/aviation-godot/
│   ├── DESIGN_INDEX.md                   Relative symbolic link to the per-work specification
│   ├── REQUEST_CONTRACT.md               Relative symbolic link to the independent request contract
│   ├── RUN_MANIFEST.json                 Relative symbolic link to the run manifest
│   ├── generated-site/                   Relative symbolic link to the result website
│   └── screenshots/                      Run and result screens used by this README
├── mcp.json                             MCP registration example
└── package.json

开发与验证

npm run build
npm run lint
npm run smoke:gdweb-isolation
npm run web

隔离冒烟测试会连接一个支持采样的模拟 MCP 客户端，并验证以下行为。

• 搜索结果数量等于采样请求数量。
• 每个采样请求恰好包含一个参考 ID。
• 请求中不会混入其他作品的 ID。
• 每个请求都使用 includeContext: none。
• 每个请求都包含 GDWEB 图片。
• 每个结果都会生成单独的 Markdown 文件。
• 被排除的作品不会进入后续搜索结果或采样请求。
• 规格说明契约包含每个页面、导航、坐标和颜色要求。
• 运行清单证据会记录图块坐标和测得的调色板。

运行时环境变量

名称	默认值	描述
DESIGN_INDEX_OUTPUT_DIR	./design-index	存储生成文档的目录
SECRET_MCP_WEB_ORIGIN	http://127.0.0.1:4317	MCP 结果中包含的网页查看器地址
SECRET_MCP_WEB_HOST	127.0.0.1	Web 服务器绑定地址
SECRET_MCP_WEB_PORT	4317	Web 服务器端口
MCP_SAMPLING_TIMEOUT_MS	1800000	每个独立的单作品 LLM 请求超时时间，单位为毫秒
MAX_CONTENT_LENGTH	500000	从普通网页提取的页面正文最大长度
DEFAULT_TIMEOUT	6000	普通 HTTP 和浏览器请求的超时时间
MAX_BROWSERS	3	普通内容提取使用的最大浏览器数量
BROWSER_TYPES	chromium,firefox	普通搜索和内容提取使用的浏览器
BROWSER_HEADLESS	true	Playwright 是否以无头模式运行
FORCE_MULTI_ENGINE_SEARCH	false	普通搜索时是否比较每个搜索引擎
DEBUG_BROWSER_LIFECYCLE	false	是否打印浏览器生命周期日志

文档

• MCP API 文档
• 设计大赛和获奖网站列表
• 全新克隆后的重新验证记录
• Yeong Coffee DESIGN_INDEX，韩文历史输出
• Yorien DESIGN_INDEX，韩文历史输出
• Ggublack Chicken DESIGN_INDEX，韩文历史输出
• Korean Air DESIGN_INDEX 规格说明，韩文历史输出
• Korean Air 独立请求契约

相关工作与参考文献

Secret MCP 是一项实现成果，与多模态 UI 理解和截图转代码研究密切相关。目前尚未使用下列论文所采用的数据集或指标进行评估，因此不得将这些论文的结果解读为 Secret MCP 的结果。

1. Chenglei Si、Yanzhe Zhang、Ryan Li、Zhengyuan Yang、Ruibo Liu 和 Diyi Yang。Design2Code：面向自动化前端工程的多模态代码生成基准测试。 NAACL 2025。介绍了真实场景下的截图转代码评估，以及视觉和元素级指标。论文
2. Bryan Wang、Gang Li、Xin Zhou、Zhourong Chen、Tovi Grossman 和 Yang Li。Screen2Words：使用多模态学习自动生成移动 UI 摘要。 UIST 2021。研究了结合截图、文本、结构和 UI 语义的表示方法。论文
3. Jing Yu Koh、Robert Lo、Lawrence Jang、Vikram Duvvur、Ming Chong Lim、Po-Yu Huang、Graham Neubig、Shuyan Zhou、Ruslan Salakhutdinov 和 Daniel Fried。VisualWebArena：评估真实场景中具有视觉依据的多模态 Agent。 ACL 2024。阐明了具有视觉依据的 Web Agent 评估的重要性和难度。论文
4. Model Context Protocol。**Sampling 规范。**定义了由客户端中介的 sampling/createMessage，包括请求消息、模型偏好、令牌预算和上下文控制。规范

引用

Secret MCP 目前是一款附有可用研究说明的软件，而非经过同行评审的出版物。

@software{jo2026secretmcp,
  author  = {{조영진}},
  title   = {Secret MCP: Evidence-Isolated Multimodal Design Analysis through MCP Sampling},
  year    = {2026},
  version = {0.6.0},
  url     = {https://github.com/yyeongjin/secret_mcp},
  note    = {Software artifact and working implementation report}
}

研究论文

• Secret MCP：根据 Web 截图生成有证据界限且上下文隔离的设计规范 — arXiv:2608.24944