Agentic Design System

ads-mcp

Agentic Design System 用のローカル MCP アダプターです。ADS のレンダリング、決定論的なゲート、評価レシート、意思決定の来歴を、コーディングエージェント向けの安定した 3 つのツールとして提供します。

npm から実行する

ADS に検査させたい UI があるプロジェクトをサーバーに指定します。

npx --yes [email protected] --root /absolute/path/to/project

MCP サーバーはブラウザーをダウンロードせずに接続するため、起動時の制限時間内に、起動直後のクライアントでもツールを検出できます。最初の Web レンダリングの前に、Chromium が利用可能か確認するか、一度インストールしてください。

npx --yes [email protected] doctor
npx --yes [email protected] setup

Chromium が見つからない場合、ads_render はタイムアウトしたり証拠を捏造したりせず、同じセットアップコマンドを示して実行をブロック状態のまま記録します。オペレーターは、既存の互換性のある Chromium 実行ファイルを PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH に設定することもできます。

ソースからビルドする

ADS リポジトリで次を実行します。

npm --prefix packages/ads-mcp install
npm --prefix packages/ads-mcp run build
node packages/ads-mcp/dist/cli.js --root /absolute/path/to/project

サーバーのオプションフラグ：

• --runs-dir <relative-path> は、プロジェクトルート配下の実行ディレクトリを変更します。デフォルトは .ads/runs です。
• --allow-origin <origin> は、ローカル以外の HTTP(S) オリジンを 1 つ許可します。追加のオリジンを許可するには、このフラグを繰り返し指定します。
• --timeout-ms <number> は、ツールごとのタイムアウトを変更します。デフォルトは 30 秒です。
• --judge-command、--judge-provider、--judge-model は、明示的なビジュアル判定アダプターを設定します。--judge-arg は複数回指定できます。
• --swiftui-command は、SwiftUI スナップショットアダプターを設定します。--swiftui-arg と --swiftui-detector は複数回指定できます。--swiftui-renderer は、実行マニフェスト内のレンダラーにラベルを付けます。

クライアントの設定

公開パッケージをローカルの stdio サーバーとして使用します。プロジェクトのパスを置き換えてください。

{
  "mcpServers": {
    "ads": {
      "command": "npx",
      "args": [
        "--yes",
        "[email protected]",
        "--root",
        "/absolute/path/to/project"
      ]
    }
  }
}

サーバーの初期化手順では、最初にレンダリングと評価を行うようクライアントに指示します。

ads_render -> ads_evaluate

ads_trace は条件付きです。実行マニフェストを読み、その中に観測されたスキルファイル、ソースファイル、アーティファクトファイルがそれぞれ少なくとも 1 つ含まれていることを確認してから呼び出してください。マニフェストに記録された、ルートからの相対パスと抜粋を正確に使用してください。来歴のパスを捏造したり、プロンプトのラベルや URL で代用したりしないでください。

レジストリ名：io.github.aa-on-ai/agentic-design-system。

URL ターゲットでは、デフォルト状態で元の URL を使用します。要求されたデフォルト以外の状態はすべて #state=<name> として読み込まれるため、アプリケーションは location.hash から state パラメーターを読み取る必要があります。

プロトコルと拡張機能の方針

このサーバーは、分割された MCP TypeScript SDK v2 パッケージを基盤としており、serveStdio を通じて起動します。1 つのバイナリで、従来の initialize クライアントと、server/discover を介して 2026-07-28 プロトコルをネゴシエートする最新のクライアントの両方を受け入れます。

実行識別子は、MCP セッション識別子ではなく、<root>/.ads/runs に保存される永続的なハンドルです。そのため、レンダリング、評価、トレース、リソースの読み取りは、同じプロジェクトのファイルシステム上で新しいクライアント、サーバー、サービスの各インスタンスを起動しても復元できます。

このサーバーは、安定版の MCP Apps 拡張機能 io.modelcontextprotocol/ui をアドバタイズします。各 ADS ツールは、証拠、ゲート、検出事項、ブロッカー、判断トレースをインライン表示できる、自己完結型の text/html;profile=mcp-app リソース ui://ads/review にリンクします。このアプリは 2026-01-26 Apps プロトコルを使用し、互換性のあるホストに対してサーバーツールとサーバーリソースへのアクセスのみを要求します。Apps に対応していないホストでも、同じ 3 つのツールとリソースの構成を利用できます。

現在の拡張機能に関する判断は、意図的に次のとおりです。

• ADS は io.modelcontextprotocol/tasks 拡張機能をアドバタイズしません。レンダリングと評価は、非同期ライフサイクルを必要としていないため、引き続き範囲を限定した同期呼び出しです。ADS がこの拡張機能を採用するのは、具体的な長時間実行操作があり、TypeScript SDK とホストの経路を検証できた場合に限ります。非推奨のコアタスク用語は使用しません。
• ローカルの stdio には認証レイヤーを追加しません。今後リモートトランスポートを導入する場合は、有効化する前に、現行の MCP OAuth/OIDC 認可モデルを実装する必要があります。
• ファイルシステムの実行ストアは、単一のローカルプロジェクトルート向けであり、MCP セッションから独立しています。ホスト環境またはレプリケーション環境で運用するには、同じ復旧保証を提供できるとする前に、共有の永続ストアと同時実行制御が必要です。

ツール

ads_render

許可された URL、ルート内に限定された TSX コンポーネント、または起動時に設定された SwiftUI ターゲットをレンダリングします。このツールは、要求された状態とビューポートをキャプチャし、該当するプラットフォームのゲートを実行して、ads://runs/... リソースを返します。

{
  "target": { "type": "url", "url": "http://127.0.0.1:3000/orders" },
  "states": ["default", "loading", "empty", "error"],
  "viewports": [{ "width": 390, "height": 844 }, { "width": 1280, "height": 800 }],
  "waitFor": "main",
  "provenance": {
    "observedSkillFiles": ["skills/design-review/SKILL.md"],
    "sourceFiles": ["brief.md"],
    "artifactFiles": ["src/Orders.tsx"]
  }
}

axe、オーバーフロー、ランドマークとライブリージョン、要求された状態、CLS、タッチターゲットの各ゲートで、利用可能な合格の証拠がそろった場合にのみ、レンダリングは complete になります。ブラウザーの依存関係が不足している場合、タイムアウトした場合、またはゲートに失敗した場合は、成功を偽って返す代わりに、blocked 状態の実行結果が保持されて返されます。

SwiftUI では、外部スナップショットアダプターを介して同じ公開ツールを使用します。

{
  "target": {
    "type": "swiftui",
    "projectPath": "Orders.xcodeproj",
    "scheme": "Orders",
    "sourcePath": "Orders/ContentView.swift",
    "configuration": "Debug",
    "device": "iPhone 16 Pro"
  },
  "states": ["default", "loading", "empty", "error"],
  "viewports": [{ "width": 393, "height": 852 }]
}

ads_evaluate

レンダリング済みの実行結果を正規化し、必要に応じて別の実行結果と比較します。デフォルトの judge.mode: "none" は引き続きモデルを使用せず、決定論的なゲートに合格した場合は needs_human を返します。judge.mode: "configured" では、サーバー起動時に選択されたビジュアル判定アダプターを呼び出し、型付きの判定結果、ルーブリックのスコア、検出事項、次の修正プロンプトを返します。

{
  "runId": "run_...",
  "compareToRunId": "run_optional_baseline",
  "rubric": {
    "task": "Make the orders workflow understandable on mobile and desktop",
    "criteria": [
      { "name": "Design Quality", "weight": 35 },
      { "name": "Originality", "weight": 30 },
      { "name": "Craft", "weight": 20 },
      { "name": "Functionality", "weight": 15 }
    ]
  },
  "judge": { "mode": "configured" }
}

サーバーは結果を受け入れる前に、ルーブリックのスコアキーが正確であること、ADS の検出事項カテゴリ、重大度、証拠リンク、正規化されたスクリーンショット領域、判定結果の整合性を検証します。判定出力がない場合、タイムアウトした場合、または整合性が取れない場合は、合格ではなく blocked を返します。

ads_trace

レンダリング中にハッシュ化されたファイルに照らして、最終判断を検証します。ルールファイルは観測済みとして記録されている必要があります。ソースファイルとアーティファクトファイルが存在し、変更されていないこと、抜粋が完全に一致すること、すべての証拠 URI が同じ実行結果内で解決できることが必要です。

キャプチャされた来歴情報のない URL のみの検査では、ads_evaluate の後に進まないでください。それでもクライアントが ads_trace を呼び出した場合、サーバーは呼び出し元が独自に指定したパスを解決せず、実行可能な対応を示す trace not applicable エラーを 1 つ返します。

{
  "runId": "run_...",
  "context": "Orders responsive repair",
  "decisions": [
    {
      "id": "mobile-primary-action",
      "decision": "Keep the primary action reachable on mobile.",
      "artifact": { "path": "src/Orders.tsx", "location": "Primary action row" },
      "rule": {
        "path": "skills/design-review/SKILL.md",
        "excerpt": "All consequential controls need a visible, reachable interaction target."
      },
      "sourceConstraint": {
        "path": "brief.md",
        "excerpt": "The primary action must remain reachable on mobile."
      },
      "evidence": ["ads://runs/run_.../evidence"]
    }
  ]
}

アーティファクトとセキュリティ

実行アーティファクトは <root>/.ads/runs/<runId>/ に保存されます。ツールは、マニフェスト、レンダリング済みの証拠、スクリーンショット、評価レシート、レポート、トレース、トレース検証への読み取り専用リソースリンクと、短い構造化された結果を返します。

resources/list は最近の実行アーティファクトを列挙するため、ツールの応答を失った場合でもクライアントは取得できます。リソース URI はディスクパスではなく、安定した論理識別子です。たとえば、ads://runs/<runId>/screenshots/default-390x844.png は <root>/.ads/runs/<runId>/evidence/default-390x844.png に対応します。クライアントは resources/read を使用してください。

• 任意のコマンドを実行するツールや、呼び出し元が出力先パスを選択する機能はありません。
• プロジェクトファイルの読み取りと実行時の書き込みは、シンボリックリンクの検査も含め、--root 配下に限定されます。
• URL 入力には HTTP(S) を使用する必要があります。デフォルトでは localhost が許可されますが、その他のオリジンには起動時の許可リスト設定が必要です。
• URL の認証情報は拒否され、一般的なシークレット用クエリパラメーターはレシートから秘匿されます。
• 外部アダプターは、シェルを介さず、固定された argv のプロセスとして実行されます。実行ファイルには絶対パスを指定する必要があり、stdout のサイズには上限があります。
• モデル呼び出しには、起動時の設定と、評価ごとの judge.mode: "configured" の両方が必要です。プロバイダー、モデル、呼び出し回数はレシートに記録されます。

検証

npm test

テストスイートでは、従来の初期化と最新の server/discover、MCP App のハンドシェイクとインラインレビューアクション、MCP クライアントの一連の処理、サーバーをまたいだ実行の復元、Chromium による URL と TSX コンポーネントのキャプチャ、コマンドアダプターとの JSON 交換、設定済みの視覚的判定、SwiftUI のスナップショット証拠、レンダリング結果の比較、リソースの読み取り、ステージレシートの繰り返し生成、タイムアウトと証拠不足時の挙動、パストラバーサル、シンボリックリンクによる逸脱、オリジンの拒否、トレースの失敗を網羅しています。

現在の制限事項

• ローカルの stdio のみです。リモート HTTP、OAuth、ホステッドサービスには対応していません。
• MCP App は任意のプログレッシブエンハンスメントです。ホストネイティブのレンダリングには、ホストが安定した Apps 拡張機能を実装している必要があります。
• タスクは意図的に公開されていません。
• ブラウザーの取得は ads-mcp setup から明示的に行います。MCP の起動時に Chromium がダウンロードされることはありません。
• コアパッケージにはプロバイダーの SDK はバンドルされておらず、モデルの選択や汎用的な Xcode スナップショットハーネスの提供も行いません。オペレーターは環境に合わせて明示的なコマンドアダプターを用意します。
• SwiftUI の証拠は、設定されたアダプターのビルド、状態の注入、検出機能に依存します。
• デフォルトのパスは引き続き決定論的で、needs_human を返します。自動判定は意図的にオプトイン方式です。

インターフェースの詳細については、正規の API 契約およびコマンドアダプタープロトコルを参照してください。