영어 | 한국어

대상 아키텍처

Secret MCP

웹 디자인 분석, 스크린샷-대-명세 워크플로우, 프런트엔드 재구축 계획을 위한 증거 기반 MCP 서버.

npx -y secret-design-mcp

Secret MCP는 GDWEB에서 최신 디자인 참고자료를 검색하고 검색 결과마다 별도의 LLM 요청과 별도의 DESIGN_INDEX 파일을 생성하는 로컬 Model Context Protocol(MCP) 서버입니다. 각 파일에는 제공된 시각적 증거로 추적 가능한 페이지 및 경로별 레이아웃, 내비게이션, 픽셀 좌표, 색상, 컴포넌트, 반응형 사양이 포함됩니다.

Secret MCP라는 이름은 이 프로젝트가 비밀 기능이나 개인 데이터를 제공한다는 의미가 아닙니다. 디자인 웹사이트를 중심으로 MCP 서버를 구축한다는 아이디어로 프라이빗 저장소에서 실험할 때 사용한 프로젝트 이름입니다. 이 프로젝트의 현재 목적은 공개 디자인 참고자료에서 재현 가능한 구조적 증거를 추출하여 LLM이 새 프로젝트에 적용할 수 있는 작업물별 사양서로 만드는 것입니다.

여러 작업의 이미지와 설명이 단일 LLM 컨텍스트나 문서에 결합되는 일은 없습니다. 서버는 검색 결과를 서버 내부에서 순차적으로 처리하고, 각 작업에 대해 독립적인 MCP sampling/createMessage 요청을 생성하며, 해당 작업의 파일을 저장한 후에만 다음 작업으로 진행합니다. 별도의 로컬 웹 애플리케이션에서 한 번에 하나의 작업을 선택하고, 소스 증거, 측정된 색상 및 좌표, LLM 계약, 생성 로그, 최종 문서를 검토하고 이후 검색의 제외 목록을 관리할 수 있습니다.

Related MCP server: Refero MCP

연구 노트

MCP 샘플링을 통한 증거 격리 멀티모달 디자인 분석

워킹 페이퍼 및 구현 보고서 · Secret MCP v0.6.0 · 비동료 검토

초록

Secret MCP는 공개 웹페이지 스크린샷을 구현 지향 디자인 사양으로 변환하는 감사 가능한 파이프라인을 구현합니다. 이 시스템은 데스크톱 및 모바일 시각 증거를 준비하고, 크롭 좌표와 대표 픽셀 색상을 기록하며, 참조물당 한 번씩 클라이언트 측 MCP 샘플링을 호출합니다. 여러 디자인 참조물을 하나의 프롬프트에 연결하는 워크플로우와 달리 Secret MCP는 참조물의 정체성을 요청 경계이자 산출물 경계로 취급합니다. 즉, 참조물 하나는 하나의 샘플링 요청, 하나의 요청 계약, 하나의 DESIGN_INDEX 문서를 생성합니다. 각 요청은 includeContext: none을 요청하고 경로, 지오메트리, 컴포넌트, 디자인 토큰, 반응형 동작, 접근성, 구현 작업, 승인 기준, 불확실성을 다루는 동일한 19개 섹션 사양 계약을 적용합니다. 이 보고서는 프로토콜 수준의 격리와 산출물 생성을 평가하며, 특정 언어 모델, 프롬프트 또는 재구성 방법이 더 우수하다고 주장하지 않습니다. 라이브 스모크 테스트로 요청 경계를 검증하고, 보존된 3개 참조 실행으로 기술적 측정값과 정성적 구현 사례를 제공합니다.

연구 질문

형식적 시스템 모델

참조물 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"]

그림 1. 금융 쿼리(gdweb-26905 제외 후 n = 2개 참조 샘플링)를 사용하여 2026-08-22에 기록된 라이브 스모크 테스트. 각 요청에는 자체 참조 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]

그림 2. 보존된 실행 2026-07-29T15-54-10-483Z-5c70317e(n = 3개 참조)의 기술적 측정값. 이 실행은 총 816.9KB의 증거 이미지 12개를 준비하고 96개의 대표 색상 측정값을 기록했습니다. 총 27,391개의 공백 구분 토큰과 187.0KB 크기의 DESIGN_INDEX 문서 3개를 생성했습니다. 세 문서 모두 1~19번 제목을 포함하지만, 제목 존재가 의미적 정확성을 보장하지는 않습니다.

정성적 사례 연구

그림 3. GDWEB 증거 뷰어에서 생성된 대한항공 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. 웹 애플리케이션 시작

MCP 서버와 웹 애플리케이션 모두에 DESIGN_INDEX_OUTPUT_DIR을 동일한 값으로 설정하여 두 프로세스가 동일한 출력 디렉터리를 읽도록 하세요.

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

브라우저에서 다음 주소를 여세요.

http://127.0.0.1:4317

웹 애플리케이션에는 생성 실행 목록, 작업별 진행 상황, GDWEB 증거 이미지, 측정된 좌표 및 팔레트, LLM에 전송된 사양 계약, 최종 Markdown, 생성 타임스탬프가 표시됩니다. 문서와 증거는 읽기 전용이며, 검색에서 제외 및 제외 제거만 이후 검색에 사용되는 필터를 변경합니다.

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 메시지를 교환합니다. 별도의 웹 뷰어 프로세스만 기본적으로 포트 4317을 사용합니다.

샘플링을 지원하지 않는 호스트를 위한 직접 샘플링 클라이언트

외부 MCP 호스트가 sampling/createMessage에 응답할 수 없는 경우 서버를 수정할 필요가 없습니다. 별도의 MCP 프로토콜 클라이언트가 dist/index.js에 직접 연결하여 sampling: {}을 알리고, 새 임시 작업 공간에서 새 Codex LLM 프로세스를 시작하여 모든 샘플링 요청을 처리할 수 있습니다.

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 호스트가 되며, 작업별 출력 예산에 충분히 긴 도구 호출 제한 시간을 사용해야 하며 단일 영구 LLM 대화를 통해 여러 샘플링 요청에 응답해서는 안 됩니다.

4. LLM에 요청

별도의 /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.

호스트 LLM은 generate-gdweb-design-indexes 도구를 한 번 호출합니다. MCP 서버는 검색을 수행하고 작업별 LLM 요청을 내부적으로 분리합니다.

수동 도구 호출 형식은 아래와 같습니다.

{
  "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 토큰입니다. 클라이언트는 예외적으로 큰 다중 페이지 증거 세트에 대해 최대 262144 토큰까지 요청할 수 있습니다.

limit: 3인 경우 기본 실행은 최대 3개의 독립적인 131072 토큰 출력을 요청할 수 있으며, 작업들이 하나의 131072 토큰 풀을 공유하지는 않습니다. 연결된 샘플링 클라이언트와 선택된 모델은 요청된 출력 크기를 지원해야 합니다. 모델이 stopReason: maxTokens를 반환하면 서버는 해당 작업을 실패로 처리하고 잘린 DESIGN_INDEX를 완료로 저장하지 않습니다.

도구가 완료되면 실행 ID, 실행 매니페스트 경로, 작업별 문서 경로 및 웹 뷰어 URL을 반환합니다.

엔드투엔드 예시: GDWEB 명세에서 Godot 항공 웹사이트까지

실제 예시에서 Secret MCP는 2026년과 2025년에 GDWEB에 등록된 항공 수상작 3개를 찾아 각 작업에 대해 독립적인 LLM 요청을 통해 DESIGN_INDEX를 생성한 다음, Korean Air 참조의 구조를 Godot 항공 프로젝트 웹사이트에 적용했습니다.

완성된 AEROFLOW 웹사이트는 Korean Air 웹사이트의 클론이 아닙니다. 명세의 정보 계층, 내비게이션, 액션 패널, 섹션 배치 및 반응형 원칙을 사용하면서 새로운 브랜드, 카피, 항공 이미지, 콘텐츠를 도입합니다. 이 예시는 결과 디자인이 참조와 달라도 측정 가능한 구조적 증거가 개성 있는 정체성을 지닌 완성도 높은 웹사이트를 여전히 만들어낼 수 있음을 보여줍니다.

예시 실행

# 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 탭에는 독립적인 LLM 요청에 전송된 데스크톱 및 모바일 이미지, 타일 좌표, 축소 비율, 대표 색상이 표시됩니다.

3. 독립적인 LLM 요청 계약

Request Contract는 페이지 분리, 내비게이션, 섹션 경계, HEX/RGB/HSL 색상, 컴포넌트, 반응형 매트릭스, 수용 기준을 기록합니다. 이 계약은 결과물이 피상적인 분위기 요약에 그치지 않게 하며, 다른 LLM이 사용할 수 있는 구현 명세로 만듭니다.

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"]

다음 경계 조건이 필수적입니다.

• 여러 작업의 이미지나 명세 본문이 하나의 배치로 외부 호스트 LLM에 반환되는 일은 없습니다.

• limit: 3인 경우 서버는 정확히 최대 3개의 상호 독립적인 LLM 샘플링 요청을 수행합니다.

• 모든 샘플링 요청은 includeContext: none을 사용합니다.

• 샘플링 요청에는 단일 작업의 메타데이터와 이미지 타일만 포함됩니다.

• 이전 작업의 ID, 이미지, 분석 문서는 다음 작업의 요청에 절대 전달되지 않습니다.

• 웹 뷰어에서 제외된 작업은 샘플링 요청이 생성되기 전에 검색 결과에서 제거됩니다.

• 서버는 현재 샘플링 응답을 파일로 저장한 후에만 다음 작업을 시작합니다.

• 마지막에는 생성된 파일 경로, 사용된 모델, 성공 또는 실패 상태만 호스트에 반환됩니다.

즉, 이는 호스트 LLM이 모든 결과를 한 번에 읽고 통합 요약을 생성하던 이전 아키텍처가 아닙니다.

웹 뷰어

웹 뷰어는 2.5초마다 DESIGN_INDEX_OUTPUT_DIR/.secret-mcp-runs를 읽습니다. MCP 생성 프로세스와 웹 서버 사이에 별도의 데이터베이스나 디버깅 연결은 없습니다.

인터페이스에는 다음 영역이 포함됩니다.

• 생성 실행: 쿼리, 요청된 수, 허용 연도, 전체 상태

• 작업 목록: 각 gdweb-<work-number>에 대한 진행률 및 증거 이미지 수

• 작업 세부 정보: 선택된 단일 작업의 명세, 증거 이미지 및 측정값, 요청 계약, 생성 로그

• 검색 제외: 선택한 작업을 향후 검색에서 제외하거나 다시 포함하고 전체 제외 목록을 관리

실행에 작업이 3개 포함되면 아래와 같이 문서도 3개 생성됩니다.

.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의 전체 데스크톱 캡처는 매우 길고 크기가 수 메가바이트에 달할 수 있습니다. 원본 base64 데이터를 샘플링 요청에 직접 보내면 MCP 전송 한도를 초과하거나 비전 모델이 미세한 구조적 세부 정보를 놓칠 수 있습니다.

각 작업에 대한 요청을 생성하기 전에 gdweb-sampling-images.ts는 다음 작업을 수행합니다.

• sgbn=1로 GDWEB 데스크톱 등록 이미지를 로드합니다.

• sgbn=3로 GDWEB 모바일 등록 이미지를 로드합니다.

• 데스크톱 이미지를 최대 너비 1200px로 크기를 조정합니다.

• 긴 페이지를 높이 1600px의 겹치는 세로 타일로 분할합니다.

• 모바일 이미지를 별도의 증거로 유지합니다.

• MCP 샘플링 요청 크기를 줄이기 위해 증거를 JPEG로 압축합니다.

• 모든 타일에 대해 원본 및 준비된 캔버스 크기, 배율, 준비된 x/y/width/height 좌표, 소스 공간 좌표, 소스 URL을 기록합니다.

• 모든 타일에서 대표 색상 8개를 측정하고 HEX, RGB, HSL 및 픽셀 적용 범위를 기록합니다.

한 작업의 여러 타일은 동일한 작업별 샘플링 요청에 포함됩니다. 서로 다른 작업의 타일은 같은 요청에 절대 포함되지 않습니다.

대표 색상은 정규화된 스크린샷 픽셀에서 샘플링한 측정값입니다. 시각적 비교를 위한 정밀한 증거이지만 JPEG 오류와 이미지 콘텐츠가 값에 영향을 주기 때문에 소스 사이트의 CSS 변수로 제시되어서는 안 됩니다. 생성 계약은 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까지 설정할 수 있습니다.

작업 메타데이터

DESIGN_INDEX 명세

모든 독립 샘플링 요청에는 secret-mcp/design-index/v2 계약이 포함됩니다. 결과 파일명은 DESIGN_INDEX_gdweb-<strNo>.md입니다.

작품마다 파일이 하나씩 생성되지만, 각 파일은 페이지 및 경로 인벤토리로 시작하며 검증된 모든 페이지에 대해 완전한 섹션을 반복합니다. 이 계약은 긴 스크롤 캡처 내의 섹션을 별도의 페이지로 간주하지 않으며, 증거 콜라주에 별도의 화면이 명확히 보일 때만 페이지를 분할합니다.

모든 문서는 아래의 19개 번호 매겨진 섹션을 모두 포함해야 합니다.

모든 주요 판단에는 다음 증거 수준 중 하나가 표시됩니다.

• OBSERVED: GDWEB 이미지 또는 메타데이터에서 직접 확인됨

• MEASURED: 제공된 픽셀 좌표 또는 측정된 팔레트에서 수치적으로 검증됨

• INFERRED: 동일한 결과를 재현하기 위해 합리적으로 추론됨

• UNKNOWN: 정적 증거만으로는 검증할 수 없으며 사실로 단정해서는 안 됨

다른 LLM은 완성된 문서만으로 컴포넌트 트리, 토큰, 반응형 규칙, 에셋, 구현 순서, 검증 항목을 도출할 수 있어야 합니다.

노출된 도구

서버는 현재 5개의 MCP 도구를 노출합니다.

디자인 계획, 레이아웃 분석, 구현 명세에는 generate-gdweb-design-indexes를 사용하고, 가벼운 목록 요청에는 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 파일을 생성합니다.

• 제외된 작품은 이후 검색 결과나 샘플링 요청에 포함되지 않습니다.

• 명세 계약에는 페이지별, 내비게이션, 좌표, 색상 요구 사항이 포함됩니다.

• 실행 매니페스트 증거에는 타일 좌표와 측정된 팔레트가 기록됩니다.

런타임 환경 변수

문서

• 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, and Diyi Yang. Design2Code: Benchmarking Multimodal Code Generation for Automated Front-End Engineering. NAACL 2025. 실제 환경의 스크린샷-코드 변환 평가와 시각적 및 요소 수준 지표를 소개합니다. 논문

2. Bryan Wang, Gang Li, Xin Zhou, Zhourong Chen, Tovi Grossman, and Yang Li. Screen2Words: Automatic Mobile UI Summarization with Multimodal Learning. 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, and Daniel Fried. VisualWebArena: Evaluating Multimodal Agents on Realistic Visually Grounded Web Tasks. ACL 2024. 시각적으로 기반한 웹 에이전트 평가의 중요성과 난이도를 입증합니다. 논문

4. Model Context Protocol. Sampling specification. 클라이언트 매개 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}
}