annotate は何をしますか？
ユーザーがページ上の要素をクリックしてメモを書き、Claudeがそのメモをセレクタ、近傍テキスト、バウンディングボックス、URLとともに取得し、コード内の要素を見つけて修正できるようにします。
Agentation をベースに構築されています：agentation ツールバー（React 18+、デスクトップのみ）と agentation-mcp ノートサーバー（SQLite上のHTTP API、オプションのMCPツール付き）です。
最初にモードを選択
明確でない場合はユーザーに質問してください：
- ローカル: このマシン上でのユーザーとClaudeだけのモードです。ノートサーバーは
localhost:4747で実行されます。何もデプロイする必要はありません。デフォルトのモードです。 - 共有: 同僚がホストされたサイトにコメントし、全員がお互いのノートを見られるモードです。公開HTTPSホスト上にノートサーバーが必要です。references/shared.md を参照してください。このページにはアーキテクチャと要件が記載されており、ホスティングはユーザーが選択します。
ツールバーの設置場所
ページの種類に応じて選択します。どちらのモードでも同じオプションが使用できます。変更されるのは endpoint と session だけです。
- ユーザーのReactアプリ内に埋め込む。
npm i -D agentationを実行し、アプリの隣にレンダリングします。本番環境には到達しないようにゲートを設定してください：{import.meta.env.DEV && <Agentation endpoint="http://localhost:4747" />}useHashLocationを追加し、フィードバックにラベルを付けるためにappNameを追加します。 - Reactであるかどうかに関わらず、ユーザーが制御する任意のHTMLページ。 1つのスクリプトタグを追加します。ローダー はツールバーを独自のコンテナと独自のReactルートにマウントするため、ホストページには影響しません：
<script type="module" src="https://cdn.jsdelivr.net/gh/Wahajolla/[email protected]/embed/annotator.js?endpoint=http://localhost:4747"></script>endpoint,session,app,hash=1。または、スクリプトがロードされる前にwindow.ANNOTATOR_CONFIG = {endpoint, session, app, hash}を設定します。 - コードに触れずに任意のサイト。 ブックマークレットを使用します。ユーザーに次の行をブックマークとして保存するよう指示します。クリックするとツールバーの表示/非表示が切り替わります：
ユーザーに伝えるべき制限事項：javascript:(()=>{const s=document.createElement('script');s.type='module';s.src='https://cdn.jsdelivr.net/gh/Wahajolla/[email protected]/embed/annotator.js?endpoint=http://localhost:4747&t='+Date.now();document.head.appendChild(s)})()- 厳格なコンテンツセキュリティポリシー（CSP）を持つサイト（GitHub、多くの銀行、大規模アプリ）は注入されたスクリプトをブロックするため、ツールバーは表示されません。
localhostと通信する公開https://サイトでは、ブラウザがローカルネットワークアクセスを求める場合があります。許可してください。- ノートサーバーはそのサイトのオリジンを許可する必要があります（以下のCORSを参照）。
- ノートはサイトのURLに紐付けられ、ツールバーのローカル下書きはそのサイトのlocalStorageに保存されます。
- Chrome拡張機能。 任意のサイトに注釈を付ける最も堅牢な方法です。1回のクリックまたはAlt+Shift+Aで切り替え、厳格なCSPサイト（GitHub、Notionなど）でも動作し、CORSの設定は不要です。リクエストは拡張機能を通して行われます。インストール：https://github.com/Wahajolla/annotator-skill/releases/latest から
annotator-extension.zipをダウンロードし、chrome://extensions→ デベロッパーモード → パッケージ化されていない拡張機能を読み込む。ノートサーバーは拡張機能のオプションで設定します。デフォルトはhttp://localhost:4747です。共有モードの場合は、ホストされているURLとセッションIDを使用します。ライブ同期は5秒ごとにポーリングします。ノートサーバーに到達できない場合、拡張機能は開始コマンドとともに「Notes server is offline」カードを表示し、#annotator-ext-rootにdata-annotator-server="offline"が設定されます（応答すると"online"になります）。ブラウザを操作している場合は、ユーザーにノートが保存されたことを伝える前にこれを確認してください。オプションで「Sign in with GitHub」を有効にすると、すべてのノートにユーザーのログイン名が署名され、同僚のノートに誰が残したかが表示されます。
endpoint がない場合、ツールバーは コピーのみ で動作します。ノートはブラウザに残り、ユーザーが「コピー」を押してマークダウンをチャットに貼り付けます。サーバーは不要なので、ユーザーが一度だけ使用したい場合に使用します。
ローカルモード
-
ノートサーバーを起動します。 以下のいずれかを選択してください：
- MCP（繰り返し使用に最適）。 ユーザーの了承を得て：
claude mcp add agentation -- npx -y agentation-mcp serverを実行します。Claude Codeはセッションごとにサーバーを起動し、再起動後にagentation_*ツールが利用可能になります：get_all_pending、resolve、reply、ハンズフリーループ用のwatch_annotations。 - プレーンHTTP（再起動不要）。 バックグラウンドコマンドとして
npx -y agentation-mcp serverを実行し、HTTP経由でノートを読み取ります（以下を参照）。
curl http://localhost:4747/healthで確認します。{"status":"ok"}が返るはずです。 - MCP（繰り返し使用に最適）。 ユーザーの了承を得て：
-
CORS。 デフォルトでは開発用オリジンのみが許可されます（
localhost、*.localhost、127.0.0.1、プライベートIP、.local、.test、.internal）。公開サイトでブックマークレットを使用する場合は、AGENTATION_CORS_ORIGINS=https://that-site.com（正確なオリジン、カンマ区切り）でサーバーを起動します。*も使用できますが、開いているすべてのタブがノートを書き込めるようになるため、正確なオリジンを指定することをお勧めします。 -
上記のいずれかのオプションを使用して、ツールバーをページに配置します。
endpoint=http://localhost:4747を指定します。 -
確認。 ツールバーからテストノートを1つ追加し、
curl localhost:4747/pendingでそれが表示されることを確認し、削除します。
ノートは ~/.agentation/store.db に保存されます。
ノートの読み取りとアクション（両方のモード）
- MCP:
agentation_get_all_pendingで未解決のノートを取得し、コードを修正してから、agentation_resolveを短い要約とともに実行します。 - HTTP:
GET /pending（すべての未解決ノート）、GET /sessions、GET /sessions/:id。ノートを修正した後、PATCH /annotations/:idを{"status":"resolved"}で送信します。 - 誰が書いたか: GitHubサインインを使用したChrome拡張機能からのノートには
authorId: "github:<login>"が含まれ、デフォルトでコメントは@<login>:で始まります。authorIdがないノートは匿名です（他の方法でツールバーを読み込んだ場合）。報告時に作成者に言及してください。 - 有用なフィールドは
comment、url、element、elementPath、fullPath、nearbyText、selectedText、boundingBox、reactComponents（開発ビルドのみ）です。 - 何かを削除する前にユーザーに決定させてください。
スクリーンショット用のノート表示
Agentationは、マーカーにホバーしている間のみノートのテキストを表示します。すべてのノートを一度に表示するには、ノートレイヤーを使用します。各ノートに枠線、番号、全文カードが表示されます。描画が完了すると、<html> に data-annotator-notes="<count>" が設定されます。
- ユーザー（Chromeの場合）： 拡張機能でAlt+Shift+Nを押します（またはアイコンを右クリック → 「このページのすべてのノートを表示」）。
- あなた（操作しているページ上、Playwright、Chrome DevTools MCPなど）： 独自のノートを設定してレイヤーを読み込み、属性が設定されるのを待ってスクリーンショットを撮ります：
window.ANNOTATOR_NOTES = [ { selector: "h1", comment: "長すぎます。「シンプルな料金」にしてください", author: "claude" }, { selector: "#cta", comment: "ブランドの青色を使用してください" }, ] const s = document.createElement("script"); s.type = "module" s.src = "https://cdn.jsdelivr.net/gh/Wahajolla/[email protected]/embed/notes.js?t=" + Date.now() document.head.appendChild(s)selector（またはページ座標でのboundingBox: {x, y, width, height}）、comment、オプションのauthorを受け取ります。セレクタが何にも一致しないノートはコンソール警告とともにスキップされるため、カウントが一致することを確認してください。ANNOTATOR_NOTESの代わりに?endpoint=http://localhost:4747を渡すと、そのページのサーバーのノートが表示されます。&all=1を追加すると解決済みのノートも含まれます。新しいtで再度読み込むとレイヤーが非表示になります。 - 厳格なCSPサイト（GitHubなど）はそのスクリプトをブロックします。Playwrightでは、
bypassCSP: trueでコンテキストを作成してください。それ以外の場合は拡張機能を使用します。 - ノートを実際のものにするには（ユーザーもツールバーでそれらを表示でき、解決できるようになります）：
POST /sessionsを{"url": "<page url>"}で実行し、次にPOST /sessions/:id/annotationsをcomment、element、elementPath（CSSセレクタ）、url、boundingBox、x/y（ページ座標）とともに実行します。その後、?endpoint=…で表示します。最初にユーザーに確認してください。これらのノートは共有ノートになります。
落とし穴
- ツールバーはデスクトップのみです。
- ノートサーバーには認証はなく、CORSのみです。ブラウザのオリジンが許可されている人は誰でもノートの書き込みと削除ができます。
useHashLocationはノートを#routeごとに保持します。後で有効にしても、既存のノートは移動しません。- AgentationはPolyForm Shieldライセンスです。これは内部フィードバックでの使用に適しています。