visual-intent-layer

Visual Intent Layer

ブラウザーに表示されたインターフェイスを指し示し、変更内容を説明すると、エージェントがその正確な視覚的コンテキストをもとに作業できます。Visual Intent Layer は、保存済みの HTML ドキュメントやローカルのウェブアプリ向けのローカル MCP サーバー兼レビュー用サーフェスです。

概要

こんにちは、世界！このプロジェクトは、新しいものやランダムなもの、話題のものを試すためのテストベッドです！ テストしていたものを以下に記載します。

• pstack's verification skills
• matt's skills
• pi で openrouter 経由の ds v4.1 flash
• ...

主な機能

• 直接指し示す。 位置を文章で説明する代わりに、表示されている対象を指したり、ドラッグしたり、枠で囲んだりできます。
• コンテキスト付きの注釈。 複数の対象を 1 つの注釈にまとめ、必要に応じて参考画像を添付できます。
• 確認できる送信状態。 未送信と送信済みの注釈を、改訂履歴や解決状態とともにまとめて管理できます。
• 人による判断。 ブラウザーで結果を確認し、それぞれの注釈を手動で判断できます。
• デフォルトでローカル。 レビューデータはローカルマシンに保存されます。

モバイルアプリ、ネイティブウィンドウ、デザインファイル、PDF はサポート対象外です。

必要条件

• Node.js 20 以降
• サーバーを実行するマシン上のブラウザー
• エージェントにレビュー用サーフェスを使わせる場合は、MCP 対応エージェント

ホスト型アカウントや Rust ツールチェーンは不要です。

クイックスタート

ローカルの stdio サーバーをエージェントに登録してから、エージェントを再起動します。

{
  "mcpServers": {
    "visual-intent-layer": {
      "command": "npx",
      "args": ["-y", "--package", "visual-intent-layer@latest", "visual-intent-mcp"]
    }
  }
}

サーバーは画面を見るマシン上で実行する必要があります。そのマシン上でブラウザーを起動し、ループバックポートにバインドします。コンテナー内、リモートホスト上、またはクラウドエージェント内のサーバーでは、そのマシンのレビュー用サーフェスを表示できません。

レジストリに対応したクライアントは、公式 MCP Registry で io.github.willa-code/visual-intent-layer を検索できます。公式 MCP Registry はホスティングを行うのではなく、入手先を掲載しています。

claude mcp add visual-intent-layer -- npx -y --package visual-intent-layer@latest visual-intent-mcp

codex mcp add visual-intent-layer -- npx -y --package visual-intent-layer@latest visual-intent-mcp

-y --package visual-intent-layer@latest visual-intent-mcp

{
  "mcpServers": {
    "visual-intent-layer": {
      "command": "npx",
      "args": ["-y", "--package", "visual-intent-layer@latest", "visual-intent-mcp"]
    }
  }
}

エージェントを使わずにレビューを開始する

このパッケージにはローカル CLI も用意されています。

npx -y --package visual-intent-layer@latest visual-intent open --html ./checkout.html
npx -y --package visual-intent-layer@latest visual-intent open --app http://localhost:5173

各コマンドはデフォルトのブラウザーを開き、レビュー URL を表示します。ヘッドレス実行やスクリプトからの使用では --no-open を追加します。ローカルサービスのみを実行するには、次のコマンドを使います。

npx -y --package visual-intent-layer@latest visual-intent serve --port 3742

npm install -g visual-intent-layer の実行後は、visual-intent コマンドも使用できます。

データとプライバシー

サーバーは、デフォルトでレビュー用データを ~/.visual-intent-layer/data に書き込みます。エージェントの設定は書き込みません。パッケージをアンインストールしてもレビューは削除されません。レビューを削除する場合に限り、そのデータディレクトリを削除してください。

別のデータディレクトリを選ぶには VISUAL_INTENT_DATA_DIR を設定します。ブラウザーの自動起動を抑止するには VISUAL_INTENT_NO_OPEN=1 を設定します。

更新とアンインストール

@latest は npx がパッケージを取得するときに解決されるため、通常は手動で更新する必要はありません。pi-mcp-adapter は解決済みのコマンドを24時間キャッシュします。最新のパッケージを取得するには、~/.pi/agent/mcp-npx-cache.json を削除してください。バージョンを固定するには、エントリー内の @latest を特定のバージョンに置き換えます。また、グローバルインストールを更新するには、npm install -g visual-intent-layer@latest を実行してください。

アンインストールするには、追加したときと同じ方法でエントリーを削除します — claude mcp remove visual-intent-layer、codex mcp remove visual-intent-layer、またはクライアントの設定を編集します。docs/guide.md に、各クライアントで使用するファイルが記載されています。アンインストールしてもレビューは削除されません。削除するまでデータディレクトリに残ります。

ドキュメント

• docs/guide.md — 製品マニュアル、Review Surface、アノテーションモデル、MCP ツール、データ、スキーマ、開発、レイアウト。
• design.md — Review Surface の規範的な設計契約。
• docs/design-references.md — コンポーネントの参照資料と検証メモ。
• docs/reference-foundations.md — 候補となる参照基盤の比較。
• SECURITY.md — 脅威モデル、サポート対象バージョン、脆弱性開示プロセス。
• docs/adr/ — アーキテクチャ上の決定事項。
• docs/pi-validation.md — Pi の実環境検証チェックリスト。

ライセンス

Apache-2.0。