Secret MCP

英語 | 韓国語

目標アーキテクチャ

---

Secret MCP

ウェブデザイン分析、スクリーンショットから仕様書を作成するワークフロー、フロントエンド再構築計画のための、エビデンスに基づく MCP サーバーです。

npx -y secret-design-mcp

Secret MCP はローカルの Model Context Protocol (MCP) サーバーです。GDWEB を検索して新しいデザインの参考資料を見つけ、検索結果ごとに個別の LLM リクエストと個別の DESIGN_INDEX ファイルを作成します。各ファイルには、提供された視覚的エビデンスをたどって確認できる、ページおよびルートごとのレイアウト、ナビゲーション、ピクセル座標、色、コンポーネント、レスポンシブ仕様が含まれます。

Secret MCP という名前は、プロジェクトが秘密の機能や非公開データを提供することを意味するものではありません。デザイン関連のウェブサイトを扱う MCP サーバーの構築を試みるため、非公開リポジトリ内で使用していたプロジェクト名です。現在のプロジェクトの目的は、公開されているデザインの参考資料から再現可能な構造的エビデンスを抽出し、LLM が新しいプロジェクトに適用できる、制作物ごとの仕様書に変換することです。

複数の制作物の画像と説明が、単一の LLM コンテキストやドキュメントにまとめられることはありません。サーバーは検索結果を内部で順番に処理し、制作物ごとに独立した MCP sampling/createMessage リクエストを作成して、その制作物のファイルを保存してから次の制作物に進みます。別途用意されたローカルのウェブアプリケーションでは、一度に1つの制作物を選択し、そのソースエビデンス、測定された色と座標、LLM コントラクト、生成ログ、最終ドキュメントを確認できるほか、以降の検索で使用する除外リストを管理できます。

研究ノート

MCP Sampling によるエビデンスを分離したマルチモーダルデザイン分析

ワーキングペーパー兼実装レポート · Secret MCP v0.6.0 · 査読なし

要旨

Secret MCP は、公開ウェブページのスクリーンショットを実装向けのデザイン仕様書に変換する、監査可能なパイプラインを実装しています。このシステムはデスクトップとモバイルの視覚的エビデンスを用意し、切り抜き座標と代表的なピクセルカラーを記録したうえで、参考資料ごとに一度、クライアント側の MCP sampling を呼び出します。複数のデザイン参考資料を1つのプロンプトに連結するワークフローとは異なり、Secret MCP は参考資料の識別性をリクエストの境界と成果物の境界の両方として扱います。1つの参考資料から、1つの sampling リクエスト、1つのリクエストコントラクト、1つの DESIGN_INDEX ドキュメントが生成されます。各リクエストでは includeContext: none を指定し、ルート、ジオメトリ、コンポーネント、デザイントークン、レスポンシブ動作、アクセシビリティ、実装タスク、受け入れ基準、不確実性を網羅する同一の19セクションの仕様コントラクトを適用します。このレポートでは、プロトコルレベルの分離と成果物の生成を評価します。特定の言語モデル、プロンプト、再構築手法が別のものより優れているとは主張しません。ライブスモークテストでリクエストの境界を検証し、保存された3つの参考資料を使った実行結果から、記述的な測定値と定性的な実装事例を提示します。

研究課題

課題	現在のエビデンス	ステータス
RQ1. MCP デザイン分析ツールは、1リクエストにつき1つの参考資料という分離を維持できますか？	参照 ID 間の検査と出力ファイルの確認を含むライブ sampling スモークテスト	テスト範囲内で検証済み
RQ2. スクリーンショットのエビデンスを、監査可能な空間・色・ドキュメントの成果物に変換できますか？	エビデンスマニフェスト、コントラクト、生成ドキュメントを含む、3つの参考資料を使った保存済みの実行結果	記述的に検証済み
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ファイルが2つ生成されました。このテストで検証できるのは、観察可能なリクエストの構成とファイルの分離であり、プロトコル外部でのモデルの記憶動作ではありません。

記録された実行時の測定値

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 ドキュメントを3件生成し、空白区切りのトークン数は合計27,391、サイズは合計187.0十進KBでした。3件すべてに見出し1～19が含まれていますが、見出しの有無は意味的な正確さを示すものではありません。

定性的なケーススタディ

(a) エビデンスと測定値	(b) 参照ごとの DESIGN_INDEX	(c) 仕様に基づく実装

図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. 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 のエビデンス画像、測定された座標とパレット、LLM に送信された仕様コントラクト、最終的な 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 メッセージをやり取りします。デフォルトでポート 4317 を使用するのは、別プロセスとして実行される Web ビューアーのみです。

サンプリングに対応していないホスト向けの直接サンプリングクライアント

外側の 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 プロセスを 1 つ起動し、Markdown 応答がすべて返されるまで待機してから、その応答を保留中の MCP サンプリング呼び出しに返します。サーバーがその制作物のコントラクト、エビデンス、ドキュメントを保存した後、ワークスペースを削除できます。

サーバーは引き続き順次キューを制御します。制作物 1 の処理が完了して保存されるまでは、制作物 2 の準備は始まりません。これにより、サーバーに統合フォールバックを追加せずに、新しいプロセスとワークスペースをプロトコルレベルの includeContext: none と同等の実行レベルの境界として利用できます。直接接続するクライアントがサンプリング対応の MCP ホストになります。制作物ごとの出力予算を処理できるよう、ツール呼び出しのタイムアウトを十分に長く設定し、1 つの永続的な 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 ツールを 1 回呼び出します。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 は作品ごとの出力上限であり、実行全体で共有する上限でも、ページ間で均等に分割する上限でもありません。1 つの作品には、複数の表示ページやルートが含まれる場合があり、各ページには 19 セクションの仕様のうち、そのページに固有の部分をすべて記載する必要があります。そのため、デフォルト値と最小値は 131072 トークンです。非常に大規模な複数ページのエビデンスセットの場合、クライアントは最大 262144 トークンをリクエストできます。

limit: 3 の場合、デフォルトの実行では、独立した 131072 トークンの出力を最大 3 件リクエストできます。各作品は、単一の 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. 作品ごとの仕様結果

左側の実行リストから、作品を 1 件ずつ選択します。右側には、ほかの作品の内容を混在させず、選択した作品の最終版 DESIGN_INDEX のみが表示されます。

2. エビデンス画像と測定値

Evidence タブには、独立した LLM リクエストに送信されたデスクトップ版とモバイル版の画像、タイルの座標、縮小率、代表色が表示されます。

3. 独立した LLM リクエストの仕様

Request Contract には、ページの分離、ナビゲーション、セクションの範囲、HEX/RGB/HSL の色、コンポーネント、レスポンシブマトリックス、受け入れ基準が記録されています。この仕様によって、結果が表面的なムードの要約にとどまるのを防ぎ、別の LLM が利用できる実装仕様になります。

4. 生成プロセス

Generation Logには、検索とエビデンスの準備から、作品ごとに独立して行われたLLMリクエスト、ドキュメントの保存、実行全体の完了までの流れが表示されます。この実行では、3作品すべてを個別の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 の場合、サーバーは相互に独立したLLMサンプリングリクエストを最大3回、正確に実行します。
• すべてのサンプリングリクエストで includeContext: none を使用します。
• サンプリングリクエストに含まれるのは、1作品分のメタデータと画像タイルのみです。
• 前の作品のID、画像、分析ドキュメントが、次の作品のリクエストに渡されることはありません。
• ウェブビューアーで除外された作品は、サンプリングリクエストが作成される前に検索結果から削除されます。
• サーバーは、現在のサンプリング応答をファイルに保存してから、次の作品の処理を開始します。
• 最後にホストへ返されるのは、生成されたファイルパス、使用したモデル、成功または失敗のステータスのみです。

つまり、ホストLLMがすべての結果を一度に読み込み、まとめて要約する以前のアーキテクチャとは異なります。

ウェブビューアー

ウェブビューアーは、2.5秒ごとに DESIGN_INDEX_OUTPUT_DIR/.secret-mcp-runs を読み込みます。MCP生成プロセスとウェブサーバーの間に、独立したデータベースやデバッグ用の接続はありません。

インターフェースには、次の領域があります。

• 生成実行：クエリ、要求数、許可された年、全体のステータス
• 作品リスト：各 gdweb-<work-number> の進捗状況と証拠画像の数
• 作品の詳細：選択した1作品の仕様書、証拠画像と測定値、リクエストコントラクト、生成ログ
• 検索除外：選択した作品を今後の検索から除外する、再び含める、除外リスト全体を管理する

実行に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 の、縦方向に重なり合うタイルに分割します
• モバイル画像を個別のエビデンスとして保持します
• エビデンスを JPEG に圧縮し、MCP サンプリングリクエストのサイズを削減します
• 元のキャンバスと処理後のキャンバスの寸法、スケール係数、処理後の x/y/width/height 座標、元画像上の座標、および各タイルのソース URL を記録します
• 各タイルから代表色を 8 色測定し、HEX、RGB、HSL、およびピクセル占有率を記録します

1 つの作品の複数のタイルは、同じ作品専用のサンプリングリクエストに含めます。異なる作品のタイルを同じリクエストに含めることはありません。

代表色は、正規化されたスクリーンショットのピクセルからサンプリングした測定値です。視覚的な比較のための正確なエビデンスですが、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 まで設定できます。

作品のメタデータ

フィールド	説明
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 です。

1つの制作物につき1ファイルですが、各ファイルはページとルートの一覧から始まり、検証済みの各ページについて完全なサブセクションを繰り返します。このコントラクトでは、長いスクロール画像内のセクションを別々のページとは見なしません。エビデンスのコラージュに個別の画面が明確に含まれている場合に限り、ページを分割します。

すべてのドキュメントに、以下の19個の番号付きセクションをすべて含める必要があります。

領域	必須仕様
再構築の目標	参照 ID、目標とする忠実度、ルート、対象ビューポート、対象外の事項
エビデンスと座標系	画像 ID、元画像と準備済み画像の寸法、スケール、タイル座標、ソース座標、重複の除去方法
サイトマップ	検証済みのページとルート、目的、エビデンス画像、共通シェル、アクティブなメニュー、確信度
共通アプリシェル	全体の背景、コンテナー、ガター、オーバーレイ、ページの外枠、スタッキングコンテキスト
ナビゲーション	デスクトップとモバイルの高さ、ロゴ／メニューの座標、間隔、タッチ領域、アクティブ／ホバー／フォーカス／開いた状態
ページ別仕様と座標テーブル	各ページのキャンバスモデル、セクションの順序、x／y／幅／高さ、レイアウト、状態、データ、エビデンスレベル
レイアウトの詳細	DOM、grid／flex、トラック、最小／最大値、比率、間隔、オーバーフロー、sticky、absolute、z-index
コンポーネントの抽象化	ページに紐づくコンポーネントツリー、props、バリアント、スロット、状態、イベント、データコントラクト
トークンと正確な色	HEX／RGB／HSL／アルファ値、用途、測定座標、確信度、許容差、CSS 変数
タイポグラフィ	用途別のフォントファミリー、px／rem、ウェイト、行の高さ、文字間隔、配置、省略表示、レスポンシブ時の値
アセットとアイコン	ページとセクション、表示サイズ、アスペクト比、トリミング、焦点、object-fit、読み込み、フォールバック戦略
レスポンシブ対応マトリクス	1440／1280／1024／768／390／360px でのコンテナー、列、順序、表示状態、ナビゲーション、間隔
インタラクションとモーション	各状態の色、不透明度、変形、時間、イージング、キーボード操作、動きを抑える設定時の動作
アクセシビリティ	ページごとのランドマーク、見出し、フォーカス、メニューのセマンティクス、ラベル、代替テキスト、コントラスト、タッチターゲット
データとコンテンツ	ページエンティティ、フィールド、件数、並び順、形式、ローカライズ、読み込み／空／エラー時のフィクスチャ
フロントエンドアーキテクチャ	ルート、ディレクトリ、ページ／共有モジュール、トークン、アセット、状態、サーバー／クライアントの境界
実装タスクグラフ	計測、シェル、ナビゲーション、ページごとのタスク ID、依存関係、成果物、完了基準
ページ別の受け入れ基準	座標、色、タイポグラフィの許容差、ビューポート比較、オーバーフロー、アセット、キーボード、パフォーマンス
不確実性と決定事項	ページ別およびセクション別の UNKNOWN、採用した値、代替案、確信度、追加で必要なエビデンス

主な判断には、以下のいずれかのエビデンスレベルを付けます。

• OBSERVED：GDWEB 画像またはメタデータで直接確認できる
• MEASURED：提供されたピクセル座標または測定済みのパレットから数値で検証されている
• INFERRED：同じ結果を再現するために妥当に推測されている
• UNKNOWN：静的なエビデンスからは検証できず、事実として断定してはならない

別の LLM が、完成したドキュメントだけをもとにコンポーネントツリー、トークン、レスポンシブルール、アセット、実装順序、検証項目を導き出せる必要があります。

公開されているツール

サーバーは現在、5 つの MCP ツールを公開しています。

ツール	目的
generate-gdweb-design-indexes	GDWEB を検索し、結果ごとに独立した LLM リクエストを実行して、ドキュメントを保存します
search-gdweb-designs	仕様を生成せずに、GDWEB の参考リストを返します
full-web-search	一般のウェブを検索し、ページ全体のコンテンツを抽出します
get-web-search-summaries	一般検索のタイトル、URL、説明を返します
get-single-web-page-content	一般のウェブページ全体のコンテンツを抽出します

デザイン計画、レイアウト分析、実装仕様、DESIGN_INDEX のリクエストには 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 が 1 つだけ含まれる。
• 他の作品の 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	ウェブサーバーのバインドアドレス
SECRET_MCP_WEB_PORT	4317	ウェブサーバーのポート
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：現実的で視覚に基づく Web タスクにおけるマルチモーダルエージェントの評価。 ACL 2024。視覚に基づく Web エージェントの評価の重要性と難しさを示しています。論文
4. Model Context Protocol。サンプリング仕様。 リクエストメッセージ、モデルの優先設定、トークン予算、コンテキスト制御を含む、クライアントを介した 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