Annotate

사용자가 페이지에서 요소를 클릭하고 메모를 작성하면, Claude가 선택자, 근처 텍스트, 바운딩 박스 및 URL과 함께 메모를 받아 코드에서 해당 요소를 찾아 수정할 수 있습니다.

Agentation 기반: agentation 툴바(React 18+, 데스크톱 전용)와 agentation-mcp 메모 서버(SQLite 기반 HTTP API, 추가 MCP 도구 포함).

먼저 모드를 선택하세요

명확하지 않다면 사용자에게 물어보세요:

로컬(Local): 사용자와 Claude만 이 머신에서 사용합니다. 메모 서버는 localhost:4747에서 실행됩니다. 배포할 필요가 없습니다. 기본값입니다.
공유(Shared): 동료들이 호스팅된 사이트에 댓글을 달고, 모든 사람이 모든 메모를 볼 수 있습니다. 공개 HTTPS 호스트에 메모 서버가 필요합니다. references/shared.md를 참조하세요. 해당 페이지에는 아키텍처와 요구사항이 설명되어 있습니다. 사용자가 호스팅 방식을 선택합니다.

툴바를 어디에 둘까

페이지의 종류에 따라 선택하세요. 두 모드에서 동일한 옵션이 작동합니다. endpoint와 session만 변경됩니다.

사용자의 React 앱 내부. npm i -D agentation을 실행한 다음, 프로덕션에 배포되지 않도록 게이트를 설정하여 앱 옆에 렌더링합니다:
```
{import.meta.env.DEV && <Agentation endpoint="http://localhost:4747" />}
```
해시 라우터를 위해 useHashLocation을 추가하고, 피드백을 라벨링하기 위해 appName을 추가하세요.
React가 아니더라도 사용자가 제어하는 모든 HTML 페이지. 스크립트 태그 하나를 추가하세요. 로더는 자체 컨테이너와 자체 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)})()
```
사용자에게 알려야 할 제한 사항:
- 엄격한 Content-Security-Policy가 있는 사이트(GitHub, 많은 은행 및 대형 앱)는 삽입된 스크립트를 차단하므로 툴바가 나타나지 않습니다.
- localhost와 통신하는 공개 https:// 사이트에서 브라우저가 로컬 네트워크 액세스를 요청할 수 있습니다. 허용하세요.
- 메모 서버는 해당 사이트의 출처를 허용해야 합니다(CORS 아래 참조).
- 메모는 사이트의 URL에 연결되며, 툴바의 로컬 임시 저장소는 해당 사이트의 localStorage에 저장됩니다.
Chrome 확장 프로그램. 모든 사이트에 주석을 달 수 있는 가장 강력한 방법입니다. 한 번 클릭하거나 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초마다 폴링합니다. 메모 서버에 연결할 수 없으면 확장 프로그램은 시작 명령어와 함께 "메모 서버가 오프라인입니다" 카드를 표시하고, #annotator-ext-root에 data-annotator-server="offline"이 설정됩니다(서버가 응답하면 "online"으로 변경). 브라우저를 제어하는 경우 사용자에게 메모가 저장되었다고 말하기 전에 이를 확인하세요. 옵션에서 "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"}를 반환해야 합니다.
CORS. 기본적으로 개발 출처만 허용됩니다(localhost, *.localhost, 127.0.0.1, 개인 IP, .local, .test, .internal). 공개 사이트의 북마클릿을 사용하려면 AGENTATION_CORS_ORIGINS=https://that-site.com으로 서버를 시작하세요(정확한 출처, 쉼표로 구분). *도 작동하지만 모든 열린 탭이 메모를 작성할 수 있으므로 정확한 출처를 선호합니다.
위 옵션 중 하나를 사용하여 툴바를 페이지에 배치하고 endpoint=http://localhost:4747을 사용하세요.
확인. 툴바를 통해 테스트 메모를 하나 추가하고, 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 라이선스로, 내부 피드백 용도로 사용하기에 적합합니다.

Annotate (웹페이지 주석 도구)