DEV Community: Yeongjin Jo

I Turned 3 Web Design References into 3 Build-Ready Specs with One MCP Prompt

Yeongjin Jo — Mon, 24 Aug 2026 15:52:28 +0000

My old design-research workflow had six steps:

Search design galleries.
Open every promising result.
Save desktop and mobile screenshots.
Paste everything into one very long prompt.
Ask an AI coding agent for a frontend plan.
Realize the answer has quietly blended all the references together.

The sixth step was the real problem.

The colors came from one site. The navigation came from another. A mobile interaction appeared that I could not find in any screenshot. The answer sounded confident, but the source of each decision had disappeared.

I wanted a different handoff: one reference in, one implementation plan out.

So I built Secret MCP, an MCP server that searches public website references, prepares visual evidence, and saves a separate build-ready DESIGN_INDEX for every selected result.

Here is one of those documents in the local viewer:

The entire workflow starts with one prompt

Find three recent aviation websites on GDWEB. Analyze each reference separately and save one implementation-ready design index for each result.

Secret MCP handles the rest inside the tool:

search
  → prepare desktop and mobile evidence
  → measure visible colors and coordinates
  → create one isolated model request per reference
  → save one DESIGN_INDEX per reference

The connected AI client does not receive a pile of references and a request to “figure it out.” It calls one MCP tool. The server keeps the queue, finishes the first reference, saves its document, and only then prepares the next one.

That detail matters more than it sounds.

What “build-ready” means here

A screenshot is useful inspiration. It is not a frontend specification.

A useful handoff needs to answer questions such as:

Which routes and page regions are visible?
How are the header, navigation, hero, sections, and footer arranged?
Which colors were measured from the supplied pixels?
What should become a token, component, or reusable pattern?
What changes between desktop and mobile?
Which behavior is visible, and which behavior is still unknown?
What should a developer implement first?
How will someone decide whether the result is acceptably close?

Each generated DESIGN_INDEX follows the same 19-section contract. It covers routes, geometry, components, design tokens, responsive behavior, accessibility, implementation tasks, acceptance criteria, and uncertainty.

More importantly, the document distinguishes four kinds of claims:

MEASURED — derived from pixels or recorded coordinates
OBSERVED — directly visible in the supplied evidence
INFERRED — a reasonable implementation choice, but not directly visible
UNKNOWN — something a static image cannot establish

That small vocabulary makes the output much easier to trust. “The menu opens on hover” and “the screenshot shows a menu” are no longer treated as the same statement.

The evidence stays available beside the document:

The test that convinced me to keep building it

I preserved a real three-reference aviation run instead of showing a perfect toy example.

That run produced:

3 independent references
12 prepared evidence images
96 representative-color measurements
3 separate DESIGN_INDEX documents
27,391 whitespace-delimited tokens across the documents
all 19 required sections in every document

Those numbers do not prove that an AI can recreate any website perfectly. That is not the claim.

They prove something narrower and more useful: the pipeline can take several references, preserve their identities, create a complete artifact for each one, and leave enough evidence to inspect how the result was produced.

I then used one of the specifications to build a new aviation concept called AEROFLOW. It has its own brand, copy, imagery, and functionality; the document guided the structure and implementation rather than supplying a pixel clone.

Why this is an MCP server instead of another screenshot app

A screenshot app usually gives me another place to upload files and another result I must manually move into my project.

MCP changes the handoff.

The same AI client that is helping me plan or code can discover the tool, call it in natural language, receive the saved document paths, and continue working from one selected plan. The research becomes part of the development workflow instead of a separate browser chore.

The important boundary looks like this:

reference A → model request A → DESIGN_INDEX_A.md → saved
reference B → model request B → DESIGN_INDEX_B.md → saved
reference C → model request C → DESIGN_INDEX_C.md → saved

Each model request uses includeContext: none. Images and metadata from different references are never deliberately concatenated into the same request or output document.

This is an observable request boundary, not a magical privacy promise. It says what the server sends and which artifacts it saves. It does not claim control over what an external model provider retains.

Try it in under a minute

Secret MCP is published on npm and runs with Node.js 20.19 or later:

npx -y secret-design-mcp

Add it to a compatible MCP client:

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

Then start with one reference:

Find one recent GDWEB website in a category I know well. Generate its DESIGN_INDEX and return the saved file path.

Starting with one makes the evaluation simple. Open the file and ask:

Could another developer begin planning this page without seeing my original chat?

If the answer is yes, try three references and compare the completed plans after generation. If the answer is no, the weak section is exactly the feedback I want.

When I would use it

Secret MCP is useful when:

I have public website inspiration but no design source of truth yet.
I want several directions explored without blending them.
I need a durable handoff for another developer or coding agent.
I want to trace a questionable recommendation back to its screenshot, coordinate, color measurement, or request contract.

It is not the tool I would choose for editing an approved Figma file, automating a live browser, or cloning a screenshot pixel for pixel. It sits earlier in the workflow: between “find useful references” and “start building.”

One compatibility check

The current release requires an MCP client that supports sampling/createMessage. If the client does not support MCP Sampling, Secret MCP stops with an explicit error instead of falling back to a combined prompt.

That limitation is intentional. A convenient fallback that mixes every reference into one context would recreate the exact problem the tool was built to avoid.

You can install the current package here: secret-design-mcp on npm.

If you try it, tell me which section of the generated DESIGN_INDEX was hardest to act on. “This part is too vague to build” is more useful feedback than a generic thumbs-up.

I Gave an AI Three Design References. It Invented a Fourth.

Yeongjin Jo — Sat, 22 Aug 2026 20:31:07 +0000

Secret MCP started with a familiar frontend problem: I opened too many tabs.

I saved one award-winning airline site for its navigation, another for its pacing, and a third for the way it handled mobile. Then I gave the screenshots to an AI coding agent and asked for an implementation plan.

What came back looked polished. It was also impossible to trust.

The palette seemed to belong to one site. The header resembled another. The mobile behavior was not visible in any of them. By the time the agent flattened everything into “a clean, modern experience,” I no longer had three references. I had a fourth design with no clear source.

That failure is why I built Secret MCP.

Secret MCP searches GDWEB from an MCP client and turns every selected website into its own evidence-backed frontend plan. One reference goes into one model request. One implementation-ready DESIGN_INDEX comes out.

Search, screenshots, measurements, responsive observations, and file output happen in the same workflow. The result is not another chat answer to scroll past. It is a local document that a developer—or the next coding agent—can build from.

Here is the difference I wanted in practice:

Before
search → open tabs → save screenshots → write a giant prompt → untangle the answer

With Secret MCP
ask once → find references → analyze each separately → save separate build plans

I will show the real output in a moment. First, it helps to explain why I made this an MCP server instead of another screenshot-to-code page.

Why MCP, though?

A script could download the images. A web app could display them. Neither would solve the handoff I cared about.

If MCP is new to you, the useful definition is simple: it gives an AI application a standard way to call tools outside the model. In this case, it connects a sentence such as “find three aviation references” to a real search-and-analysis pipeline.

That changes the experience in four ways.

The agent can discover the tool. Secret MCP describes what it accepts and what it returns, so you ask for an outcome instead of operating the pipeline by hand.
The research stays beside the project. The same client that helps plan or code the site can call the design tool and receive the saved document paths.
The workflow is repeatable. Search filters, image preparation, evidence labels, the document structure, and output naming do not depend on remembering yesterday's prompt.
The result can feed the next tool. A saved DESIGN_INDEX can guide a coding agent, a Figma workflow, component selection, or later browser QA.

The current version also lets the connected MCP client perform the model request. Secret MCP does not need its own LLM API key; it asks a compatible client to generate the document through MCP Sampling. That choice comes with a compatibility tradeoff, which I will be honest about below.

What this produced in a real project

Here is the result first.

AEROFLOW is a new aviation website with its own name, copy, imagery, and functionality. Its structure was built from one of the design specifications produced in a preserved Secret MCP run.

That run began with three aviation references from GDWEB. A request can be as direct as:

Find three recent aviation websites on GDWEB. Analyze them separately and save an implementation-ready design index for each one.

Secret MCP searched inside the server, prepared the desktop and mobile evidence, and made three separate model requests. It wrote three separate Markdown files. Only after the first file was saved did the second reference enter the pipeline.

For the Korean Air reference, the output was not “use a premium blue palette and generous whitespace.” It described the visible page structure, navigation, section geometry, measured colors, component candidates, responsive evidence, implementation order, and QA criteria. Claims that could not be verified from the screenshots were not presented as facts.

This was the moment the project became useful to me. I could hand the document to another coding session without replaying the original research conversation. And when something looked wrong, I could open the viewer and trace it backward instead of starting over.

The real alternative is a screenshot folder

It is tempting to compare every MCP server with every other MCP server. That is not how I choose tools in practice.

The workflow Secret MCP replaces is manual: search for sites, open each result, save images, paste everything into one conversation, explain the desired output, and then reconstruct where the answer came from. It works. I did it for a long time. It just gets fragile when the number of references or the depth of the handoff grows.

Other MCP tools solve adjacent jobs well:

If I already have an approved Figma file, I would use the Figma MCP server to bring frames, variables, components, and design-system context into development.
If I need an agent to navigate, click, or inspect a live page, I would use Playwright MCP.
If I need broad web, news, image, or local search, Brave Search MCP is built for that surface.
If I want to search a component catalog and install or generate UI, I would use 21st MCP.

Secret MCP starts earlier than those implementation steps. Use it when you have public website inspiration but no design source of truth yet—and the thing you need next is a full-page plan with evidence behind it.

That also makes the tools complementary. A workflow can begin with Secret MCP for reference research, move through Figma or a component library for design and implementation, and finish with browser automation for QA.

What I actually wanted the document to do

I did not want a design critique. I wanted a build handoff.

Each DESIGN_INDEX begins with the evidence it was allowed to use and then turns the visible design into decisions a developer can act on:

a page and route inventory
header, navigation, section, and footer structure
visible coordinates and spatial relationships
representative colors and reusable design tokens
component boundaries, states, and asset guidance
desktop-to-mobile observations and unknowns
accessibility notes, implementation tasks, acceptance criteria, and QA tolerances

Every important statement carries one of four labels:

MEASURED: derived from pixels or recorded coordinates
OBSERVED: directly visible in the supplied evidence
INFERRED: a reasonable implementation decision, but not directly visible
UNKNOWN: something a static screenshot cannot establish

Those labels are deliberately unglamorous. They stop a confident sentence from quietly becoming a fact.

How it avoids inventing the fourth design

The unusual part of Secret MCP is not the search. It is where the search results are allowed to go.

If the server returned three references to the host and asked the host to analyze them later, all three could already be sitting in one conversation. The mixing would begin before the analysis did.

So the generation tool keeps the result queue inside the server. For each reference, it prepares only that work's images and metadata, sends one sampling/createMessage request with includeContext: none, saves the response, and then advances to the next item.

reference A → request A → DESIGN_INDEX_A.md → saved
reference B → request B → DESIGN_INDEX_B.md → saved
reference C → request C → DESIGN_INDEX_C.md → saved

The fixed contract, evidence manifest, and generation log are preserved with each work. A smoke test checks that the number of results matches the number of model requests, that every request contains exactly one reference ID, and that each response creates a separate file.

That is an observable boundary, not a magical privacy claim. It does not say what an external model provider retains. It says exactly what Secret MCP sends in each request and leaves the artifacts needed to verify it.

A few ways to use it

Start from a blank page. Ask for recent references in a category and generate one plan before touching the component tree.

Find a recent GDWEB reference for a technology landing page. Create one DESIGN_INDEX I can use to plan a new React site.

Explore several directions without blending them. Generate three documents independently, then compare the finished plans after each reference has been described on its own terms.

Find three finance websites from 2025–2026. Keep their analyses separate. After the files are saved, return only their paths and statuses.

Give another agent a durable handoff. Point a coding session at one DESIGN_INDEX instead of reattaching the screenshots and retelling the design intent.

Read DESIGN_INDEX_gdweb-<id>.md. Build the page in this repository with new branding and content. Treat UNKNOWN claims as decisions to confirm, not facts.

Audit a bad result. Open the local viewer, select the reference, and move from the questionable paragraph back to its contract, image tile, crop coordinates, and generation event.

You do not have to run the expensive path every time. search-gdweb-designs returns a lightweight reference list when discovery is enough. generate-gdweb-design-indexes performs the evidence preparation and document generation. The server also exposes general web-search and page-content tools for supporting research around a project.

Try one reference, not three

Secret MCP is open source under MIT and published on npm as secret-design-mcp. It requires Node.js 20.19 or later.

Add it to a compatible MCP client:

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

Then ask for one design you can evaluate quickly:

Find one recent GDWEB website in a category you know well. Generate its DESIGN_INDEX and return the saved file path.

Open the file and ask one question: could another developer begin planning from this without seeing my original chat?

One limitation to check first

Version 0.6.0 requires a client that supports MCP sampling/createMessage. If the capability is unavailable, Secret MCP stops with an explicit error instead of falling back to a combined prompt.

Sampling was deprecated in MCP protocol version 2026-07-28. It remains available during the protocol's deprecation window, but the project needs to migrate to direct provider calls. The rule I intend to preserve is more important than the mechanism: a fresh model request and a fresh workspace for every reference.

Secret MCP is not a pixel-cloning tool, and the preserved aviation run is not a benchmark proving that it produces better websites. It is a working, inspectable pipeline for moving from public design research to a frontend specification without losing track of the source.

That is the whole reason it exists.

If that is a gap in your workflow, try Secret MCP on GitHub. If the document is useful, a star helps other developers find it. If it gets something wrong, open an issue with the reference ID, evidence tile, and section that failed. That is feedback I can trace all the way through the run.