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

My old design-research workflow had six steps:

1. Search design galleries.
2. Open every promising result.
3. Save desktop and mobile screenshots.
4. Paste everything into one very long prompt.
5. Ask an AI coding agent for a frontend plan.
6. 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.