yeongjin

Posted on Aug 22 Originally published at github.com

One Reference, One Request: Building an Evidence-Isolated Design Analysis MCP

#mcp #ai #webdev #opensource

Most screenshot-to-code workflows start with a simple idea: give a model several good references and ask it to synthesize a design. The practical problem is traceability. Once screenshots from different sites enter the same context, it becomes difficult to tell which reference supports a color, layout, component, or responsive rule.

I built Secret MCP to test a stricter boundary: one design reference produces one MCP sampling request and one implementation document.

Secret MCP is a local, open-source Model Context Protocol server. It searches GDWEB for recent public design references, prepares visual evidence for each work, and asks the connected MCP client to analyze every result independently. The output is not a mood board or a combined inspiration summary. It is a separate DESIGN_INDEX file for each reference, with routes, coordinates, colors, components, responsive behavior, accessibility requirements, implementation tasks, acceptance criteria, and explicit uncertainty labels.

Why isolate the references?

Suppose a search returns three works. A combined prompt can be convenient, but it creates an attribution problem: a later specification may contain the navigation of reference A, the color palette of reference B, and an inferred component from reference C without preserving those boundaries.

Secret MCP instead runs a sequential queue:

Search for eligible references.
Prepare desktop and mobile evidence for work 1.
Send one sampling/createMessage request with includeContext: none.
Save one DESIGN_INDEX_gdweb-<id>.md document.
Only then prepare the next work.

Formally, the prepared evidence for reference r_i is:

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

I is the set of prepared image tiles, B is the crop geometry, P is the representative-color measurement, M is source metadata, and C is the fixed 19-section specification contract. This is an operational isolation invariant. It does not claim that an external model provider has no memory outside the MCP message.

Turning long screenshots into inspectable evidence

Full-page design captures can be thousands of pixels tall. Sending the original image as one large base64 payload makes fine layout details easy to miss and can exceed transport limits. Before sampling, Secret MCP:

resizes desktop evidence to a maximum width of 1,200 pixels;
divides long pages into overlapping 1,600-pixel vertical tiles;
keeps mobile evidence separate;
records prepared and source-space coordinates for every tile;
measures eight representative colors per tile in HEX, RGB, and HSL;
labels measured values separately from inferred implementation tokens.

Coordinates map back to the original capture with:

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

The local viewer exposes the evidence, request contract, generation log, and final document for one work at a time.

What the current tests show

There are two deliberately small evaluations in version 0.6.0.

The live smoke test used two sampled references. Each request contained its own reference ID, zero occurrences of the other sampled ID, its own visual evidence, and includeContext: none. Two requests produced two Markdown files.

Sampling request	Own reference present	Other sampled reference present	Output documents
Request 1	1	0	1
Request 2	1	0	1

A preserved three-reference run recorded the following descriptive measurements:

Reference	Desktop source height	Prepared images	Image payload	Color measurements	Document tokens	Document size	Required headings
`gdweb-27294`	2,675 px	3	126.6 KB	24	7,921	54.0 KB	19/19
`gdweb-25378`	7,043 px	4	302.5 KB	32	9,953	69.8 KB	19/19
`gdweb-24234`	7,832 px	5	387.8 KB	40	9,517	63.2 KB	19/19

Across those three references, the pipeline prepared 12 evidence images totaling 816.9 decimal KB, recorded 96 representative-color measurements, and produced three documents totaling 27,391 whitespace-delimited tokens and 187.0 decimal KB.

These results verify request composition and artifact separation within the test scope. They do not establish superior design quality. The current evaluation has no control group, human rating, repeated trials, confidence intervals, or benchmark comparison. A 19/19 heading result measures structural completeness, not factual correctness.

From specification to a distinct implementation

The repository also preserves a qualitative case study. A Korean Air reference was converted into a per-work specification, then its information hierarchy and layout relationships were applied to a new Godot aviation project called AEROFLOW. The resulting site uses new branding, content, imagery, and functionality; it is not a pixel clone.

This case demonstrates that measured structural evidence can guide a concrete implementation while still allowing a different visual identity. It remains an existence example, not a controlled fidelity study.

The 19-section output contract

Every generated document must cover:

reconstruction goals and evidence coordinates;
site map, shared shell, and navigation;
per-page geometry and layout;
component abstraction and design tokens;
typography, assets, and responsive behavior;
interaction, accessibility, and data states;
frontend architecture and implementation tasks;
per-page acceptance criteria;
uncertainties and adopted decisions.

Major claims are marked OBSERVED, MEASURED, INFERRED, or UNKNOWN. This makes the document useful as an implementation handoff without pretending that static screenshots reveal invisible DOM structure or production CSS.

Running Secret MCP

Node.js 20.19 or later is required.

npx -y secret-design-mcp

An MCP client configuration looks like this:

{
  "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"
      }
    }
  }
}

The client must support MCP sampling/createMessage. The server is registered in the official MCP Registry as io.github.yyeongjin/secret-mcp, distributed on npm as secret-design-mcp, and licensed under MIT.

The full implementation, viewer screenshots, smoke test, generated specifications, and limitations are available in the Secret MCP repository.

Related work

Secret MCP is an implementation artifact adjacent to multimodal UI understanding and screenshot-to-code research. It has not been evaluated on the datasets used by the papers below, so their results should not be interpreted as Secret MCP results.

Si et al., Design2Code: Benchmarking Multimodal Code Generation for Automated Front-End Engineering, NAACL 2025.
Wang et al., Screen2Words: Automatic Mobile UI Summarization with Multimodal Learning, UIST 2021.
Koh et al., VisualWebArena: Evaluating Multimodal Agents on Realistic Visually Grounded Web Tasks, ACL 2024.
Model Context Protocol, Sampling specification.

Secret MCP v0.6.0 is software with a working implementation report, not a peer-reviewed publication.

DEV Community