domscribe

Domscribe

Domscribe は、実行中の UI とソースコードをつなぎます。レンダリングされた各要素を正確なソースの場所に対応付け、実行時のコンテキスト（props、state、DOM）をリアルタイムで取得します。次の 2 つの方向で機能します。

• UI → コード：ユーザーがブラウザー内の要素をクリックすると、Domscribe はソースの場所、実行時のコンテキスト、ユーザーの意図を含むアノテーションとして取得します。あなたがそれを引き受けて実装します。
• コード → UI：ソースファイルを編集中に、要素が実行時にどのように表示されるかを知りたい場合は、ファイルと行を指定して、ライブの props、state、DOM スナップショットを取得します。

セットアップ／初期化

domscribe.status が active: false を返す場合、このワークスペースでは Domscribe がまだ設定されていません。Domscribe バンドラープラグインを設定して開発サーバーを起動すると、.domscribe/ ディレクトリが自動的に作成されます。設定するには、次の手順に従ってください。

1. 休止状態を確認する — domscribe.status を呼び出します。active: false の場合は続行します。応答内の cwd を確認します。
2. フレームワークを検出する — package.json（cwd にあるもの、または domscribe.config.json が存在する場合はその appRoot にあるもの）を読み取り、以下の表に照らして依存関係を確認します。
3. パッケージマネージャーを検出する — プロジェクトルートにどのロックファイルが存在するか確認します。
4. パッケージをインストールする — Bash 経由で適切なインストールコマンドを実行します（例：pnpm add -D @domscribe/next）。
5. バンドラーの設定を編集する — 設定ファイルを読み取り、統合パターンを適用します。各フレームワークの正確なインポート、変換、例については、references/config-patterns.md を読み込みます。
6. .gitignore を更新する — .domscribe がまだ記載されていない場合は、# Domscribe artifacts コメントと .domscribe のエントリーを追加します。
7. ユーザーに知らせる — 開発サーバーを起動（または再起動）するよう伝えます。Domscribe は初回起動時に自動的に有効になります。

フレームワークの検出

package.json の dependencies と devDependencies を確認します。上から順に照合し、最初に一致したものを採用します。

Dependency	Framework
next	next
nuxt	nuxt
react + vite	react-vite
react (no vite)	react-webpack
vue + vite	vue-vite
vue (no vite)	vue-webpack
vite only	other-vite
webpack only	other-webpack

パッケージの対応表

Framework	Package	Config file
next	@domscribe/next	next.config.ts
nuxt	@domscribe/nuxt	nuxt.config.ts
react-vite	@domscribe/react	vite.config.ts
react-webpack	@domscribe/react	webpack.config.js
vue-vite	@domscribe/vue	vite.config.ts
vue-webpack	@domscribe/vue	webpack.config.js
other-vite	@domscribe/transform	vite.config.ts
other-webpack	@domscribe/transform	webpack.config.js

パッケージマネージャーの検出

Lockfile	Package manager
pnpm-lock.yaml	pnpm
yarn.lock	yarn
bun.lock / bun.lockb	bun
(none)	npm

インストールコマンドの形式：<pm> add -D <package>（pnpm/yarn/bun）、または npm install -D <package>。

モノレポプロジェクト

プロジェクトルートに appRoot フィールドを含む domscribe.config.json が存在する場合、フロントエンドアプリはそのサブディレクトリにあります。パッケージをインストールし、appRoot を基準にバンドラー設定を探します。

プロジェクトがモノレポと思われる場合（例：apps/、packages/ ディレクトリ、package.json 内のワークスペース設定がある場合）で、domscribe.config.json が存在しないときは、フロントエンドアプリがどのディレクトリにあるかユーザーに確認します。その後、プロジェクトルートに domscribe.config.json を作成します。

{ "appRoot": "apps/web" }

セットアップ後

.domscribe/ ディレクトリが存在しない場合、MCP サーバーは休止モードで起動します。ユーザーが開発サーバーを起動すると、バンドラープラグインが .domscribe/ を自動的に作成します。新しいワークスペースを検出して、すべてのツールを利用できるアクティブモードに移行するには、MCP サーバーを再起動する必要があります。

コンポーネントの編集（コード → UI）

ランタイムの状態を照会する理由： ソースコードだけでは、コンポーネントが実際に受け取った props、条件分岐が描画されたかどうか、適用された CSS クラス、ユーザーに表示されるテキストはわかりません。domscribe.query.bySource を使えば、ブラウザー上の実際の状態を確認できます。

照会するとよいケース（次のタスクに役立ちます）：

• 表示・スタイルの不具合 — 「ボタンの色が違う」。照会すると、実際の className、インラインスタイル、計算済み属性がわかり、どの CSS が優先されているかを確認できます。
• 条件付き描画の不具合 — 「このセクションが表示されない」。照会すると、rendered: false が返されるか、条件を制御する実際の props／状態が表示されます。
• props の追跡 — 「タイトルが 'undefined' と表示される」。照会すると、実際に渡されている値を含む componentProps が表示され、値の受け渡しが途切れている箇所を特定できます。
• 編集内容の確認 — 編集後、同じ場所を照会して、DOM、props、テキストが期待どおりに更新されたことを確認できます（HMR によって変更が反映されています）。

照会しなくてよいケース（往復の手間を省けます）：

• 純粋なロジックの変更（ユーティリティ、DOM 出力のないフック、API 呼び出し）
• 新しいファイルやコンポーネントを一から作成する場合（まだ照会するものがありません）
• リファクタリング（名前変更、抽出、移動）
• 型エラーやビルド失敗（コンパイラーが問題をすでに示しています）

前提条件： ランタイムの照会には、ユーザーの開発サーバーが起動しており、対象コンポーネントが開いているブラウザータブで描画されている必要があります。domscribe.query.bySource を呼び出す前に、対象のページを開いているかユーザーに確認してください。browserConnected: false または runtime.rendered: false が返された場合は、コンポーネントが描画されるページに移動してから再試行するようユーザーに依頼してください。

ワークフロー：

1. ページが開いていることを確認する — 対象コンポーネントがあるページをブラウザーで開いているか、ユーザーに確認します。開いていない場合は、まずそのページに移動するよう依頼します。
2. 編集前（上記のケースに該当する場合）：ファイルパスと行番号を指定して domscribe.query.bySource を呼び出します。runtime.componentProps、runtime.componentState、runtime.domSnapshot を確認します。
3. コンポーネントのソースコードを編集します。
4. 編集後： domscribe.query.bySource を再度呼び出し、ライブブラウザーで変更が反映されたことを確認します。

クイックコマンド（MCP プロンプト）

コマンド	用途
process_next	キュー内の次の注釈を処理する
check_status	システムの健全性とキューの件数を確認する
explore_component	コンポーネント内の要素を一覧表示する
find_annotations	注釈の履歴を検索する

全ツールリファレンス

以下のツール名は、MCP への登録名（例：domscribe.query.bySource）を使用しています。クライアントによっては、これらの名前が別の名前にマッピングされている場合があります。環境で domscribe MCP サーバーに公開されているツール名を使用してください。

ソースの照会（コード → UI）

ツール	用途
domscribe.query.bySource	ソースの場所（ファイル＋行）に対応するランタイムコンテキストを取得する
domscribe.manifest.query	ファイル、コンポーネント、タグ名からマニフェストのエントリーをすべて検索する
domscribe.manifest.stats	マニフェストのカバレッジ統計（エントリー／ファイル／コンポーネントの件数）

要素の特定（UI → コード）

ツール	用途
domscribe.resolve	要素 ID に対応するソースの場所を取得する
domscribe.resolve.batch	複数の要素 ID を特定する

アノテーションのワークフロー

ツール	目的
domscribe.annotation.process	次のキュー内のアノテーションを取得する（アトミック）
domscribe.annotation.respond	実装内容のメッセージを保存する
domscribe.annotation.updateStatus	processed または failed に設定する
domscribe.annotation.list	ステータス別にアノテーションを一覧表示する
domscribe.annotation.get	アノテーションの詳細を取得する
domscribe.annotation.search	要素、ファイル、またはテキストで検索する

システム

ツール	目的
domscribe.status	リレーの状態、マニフェスト、キュー数を確認する

domscribe.query.bySource の使用方法

ソースファイルの作業中に、実行時に要素がどのように表示されるかを確認するには、ファイルパスと行番号を指定してクエリします。

入力：

• file（必須）：マニフェストに記録されている絶対ファイルパスです。正確なパスを確認するには、domscribe.manifest.query を使用します。
• line（必須）：行番号（1 始まり）です。
• tolerance（任意）：対象行から N 行以内の要素を照合します（デフォルト：0、完全一致）。
• column（任意）：特定の列に絞り込みます（0 始まり）。
• includeRuntime（任意）：マニフェストのデータだけが必要な場合は、ブラウザーへのクエリをスキップします（デフォルト：true）。

出力：

• sourceLocation：確認済みのファイル、行範囲、タグ名、コンポーネント名です。
• runtime：ブラウザーからのライブデータ（接続されている場合）です。componentProps、componentState、domSnapshot（タグ、属性、innerText）が含まれます。
• browserConnected：WebSocket 経由でブラウザークライアントが接続されているかどうかを示します。

正確な行が分からない場合は、まず domscribe.manifest.query を使用してください。ファイル、コンポーネント、またはタグに一致するすべてのエントリが返されるので、その中から domscribe.query.bySource の対象を指定できます。

アノテーションのライフサイクル

queued → processing → processed
                   ↘ failed (with errorDetails)
       any status → archived

• queued：エージェントが取得するのを待っています
• processing：エージェントが作業中です（アトミックに取得済み）
• processed：実装が正常に完了しました
• failed：実装できませんでした（errorDetails を含めてください）
• archived：アクティブなキューから削除されました

アノテーションのワークフロー

1. domscribe.annotation.process を使ってアノテーションを取得します

2. レスポンスを確認します：

   • userIntent：ユーザーの要望（例：「このボタンを赤くする」）
   • sourceLocation.file：ソースファイルのパス
   • sourceLocation.line：行番号
   • sourceLocation.componentName：React/Vue コンポーネント名
   • element.innerText：表示されているテキスト（要素が正しいことを確認してください）
   • runtimeContext.componentProps：現在のプロパティ値

3. sourceLocation.file:sourceLocation.line に移動します

4. userIntent に基づいて変更を実装します

5. domscribe.query.bySource を使って検証します。同じファイルと行を指定して呼び出し、ライブブラウザーに変更が反映されていることを確認します（HMR によってページは更新されています）

6. アノテーション ID と実施内容を説明するメッセージを添えて、domscribe.annotation.respond でレスポンスを保存します

7. domscribe.annotation.updateStatus でステータスを processed（または errorDetails を添えて failed）に設定し、アノテーションを完了します

エラー処理

状況	対応
found: false	一致するものがありません。キューが空か、マニフェストにエントリがありません
browserConnected: false	実行時データは利用できませんが、マニフェストのデータは引き続き返されます
ソースファイルが見つからない	詳細を添えて failed に設定します
意図が曖昧	実装する前にユーザーに確認を求めます
一部のみ成功	processed に設定し、レスポンスに制限事項を記載します
実装できない	理由を説明する errorDetails を添えて failed に設定します

主な原則

• userIntent を注意深く読みます。これはユーザーの実際の言葉です
• 変更の前後に、domscribe.query.bySource を使って実行時の状態を確認します
• 変更対象の要素が正しいことを確認するには、element.innerText を使います
• runtimeContext を使って、現在のコンポーネントの状態を把握します
• 変更は必要最小限に絞ります
• domscribe.annotation.respond を使って、明確な説明を提供します
• domscribe.annotation.search で検索し、関連する過去の作業を確認します