Wahajolla/annotate

Anotar

El usuario hace clic en un elemento de una página, escribe una nota, y Claude recibe la nota con un selector, texto cercano, rectángulo delimitador y URL, para que pueda encontrar el elemento en el código y corregirlo.

Construido sobre Agentation: la barra de herramientas agentation (React 18+, solo escritorio) y el servidor de notas agentation-mcp (API HTTP sobre SQLite, más herramientas MCP opcionales).

Elige primero el modo

Pregunta al usuario si no está claro:

• Local: solo el usuario y Claude, en esta máquina. El servidor de notas se ejecuta en localhost:4747. No se despliega nada. Este es el modo por defecto.
• Compartido: los colegas comentan en un sitio alojado y todos ven las notas de todos. Necesita un servidor de notas en un host HTTPS público. Consulta references/shared.md. Esa página describe la arquitectura y los requisitos; el usuario elige el alojamiento.

Dónde va la barra de herramientas

Elige según qué sea la página. Las mismas opciones funcionan en ambos modos; solo cambian endpoint y session.

1. Dentro de la app React del usuario. npm i -D agentation, luego renderízala junto a la app, protegida para que nunca llegue a producción:

   {import.meta.env.DEV && <Agentation endpoint="http://localhost:4747" />}
   

   Añade useHashLocation para enrutadores hash y appName para etiquetar los comentarios.
2. Cualquier página HTML que controle, sea React o no. Añade una sola etiqueta script. El cargador monta la barra en su propio contenedor y su propio root de React, por lo que no toca la página anfitriona:

   <script type="module" src="https://cdn.jsdelivr.net/gh/Wahajolla/[email protected]/embed/annotator.js?endpoint=http://localhost:4747"></script>
   

   Parámetros de consulta: endpoint, session, app, hash=1. Alternativamente, define window.ANNOTATOR_CONFIG = {endpoint, session, app, hash} antes de que se cargue el script.
3. Cualquier sitio, sin tocar su código. Usa un bookmarklet. Dale al usuario esta línea para guardar como marcador; al hacer clic, activa y desactiva la barra:

   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)})()
   

   Limitaciones que debes comentar al usuario:
   • Los sitios con una Política de Seguridad de Contenido (CSP) estricta (GitHub, muchos bancos y grandes aplicaciones) bloquean los scripts inyectados, por lo que la barra no aparecerá allí.
   • En un sitio público https:// que se comunica con localhost, el navegador puede solicitar acceso a la red local: permítelo.
   • El servidor de notas debe permitir el origen de ese sitio (ver CORS más abajo).
   • Las notas están vinculadas a la URL del sitio, y los borradores locales de la barra se guardan en el localStorage de ese sitio.
4. Extensión de Chrome. Esta es la forma más robusta de anotar cualquier sitio. Se activa con un clic o Alt+Mayús+A, funciona en sitios con CSP estricto (GitHub, Notion, etc.) y no necesita configuración CORS: las solicitudes pasan por la extensión. Instalación: descarga annotator-extension.zip de https://github.com/Wahajolla/annotator-skill/releases/latest, luego chrome://extensions → Modo desarrollador → Cargar descomprimida. El servidor de notas se configura en las opciones de la extensión. Por defecto es http://localhost:4747; para el modo compartido, usa la URL alojada más el id de sesión. La sincronización en vivo es mediante sondeo cada 5 segundos. Si el servidor de notas no está disponible, la extensión muestra una tarjeta "Servidor de notas fuera de línea" con el comando de inicio, y #annotator-ext-root recibe data-annotator-server="offline" ("online" cuando responde): si estás controlando el navegador, compruébalo antes de decirle al usuario que sus notas se guardaron. En las opciones, "Iniciar sesión con GitHub" firma cada nota con el inicio de sesión del usuario, para que las notas de los colegas muestren quién las dejó.

Sin endpoint, la barra se ejecuta en modo solo copia. Las notas permanecen en el navegador y el usuario presiona Copiar y pega el markdown en el chat. Esto no necesita servidor, así que úsalo cuando el usuario solo lo quiera una vez.

Modo local

1. Ejecuta el servidor de notas. Elige uno:

   • MCP (mejor para uso repetido). Con el visto bueno del usuario: claude mcp add agentation -- npx -y agentation-mcp server. Claude Code lo inicia con cada sesión, y las herramientas agentation_* aparecen después de reiniciar: get_all_pending, resolve, reply y watch_annotations para bucles automáticos.
   • HTTP simple (sin reinicio). Ejecuta npx -y agentation-mcp server como comando en segundo plano y lee las notas a través de HTTP (ver más abajo).

   Verifícalo con curl http://localhost:4747/health, que debería devolver {"status":"ok"}.

2. CORS. Por defecto solo se permiten orígenes de desarrollo (localhost, *.localhost, 127.0.0.1, IPs privadas, .local, .test, .internal). Para un bookmarklet en un sitio público, inicia el servidor con AGENTATION_CORS_ORIGINS=https://ese-sitio.com (orígenes exactos, separados por comas). * también funciona, pero permite que cualquier pestaña abierta escriba notas, así que es mejor usar orígenes exactos.

3. Pon la barra en la página usando una de las opciones anteriores, con endpoint=http://localhost:4747.

4. Verifica. Añade una nota de prueba a través de la barra, comprueba que curl localhost:4747/pending la muestra, luego bórrala.

Las notas persisten en ~/.agentation/store.db.

Leer y actuar sobre las notas (ambos modos)

• MCP: agentation_get_all_pending, luego corrige el código, luego agentation_resolve con un breve resumen.
• HTTP: GET /pending (todas las notas abiertas), GET /sessions, GET /sessions/:id. Después de corregir una nota, envía PATCH /annotations/:id con {"status":"resolved"}.
• Quién la escribió: las notas de la extensión de Chrome con inicio de sesión de GitHub llevan authorId: "github:<login>", y por defecto el comentario comienza con @<login>: . Una nota sin authorId es anónima (cualquier otra forma de cargar la barra). Menciona al autor cuando informes.
• Los campos útiles son comment, url, element, elementPath, fullPath, nearbyText, selectedText, boundingBox y reactComponents (solo builds de desarrollo).
• Deja que el usuario decida antes de eliminar nada.

Mostrar notas para capturas de pantalla

Agentation solo muestra el texto de una nota mientras pasas el ratón sobre su marcador. Para mostrarlas todas a la vez, usa la capa de notas: un contorno, un número y una tarjeta de texto completo para cada nota. Cuando termine de dibujar, <html> recibe data-annotator-notes="<count>".

• El usuario, en Chrome: Alt+Mayús+N en la extensión (o clic derecho en el icono → Mostrar todas las notas en esta página).
• Tú, en una página que estás controlando (Playwright, Chrome DevTools MCP, etc.): define tus propias notas y carga la capa, luego espera el atributo y toma la captura:

  window.ANNOTATOR_NOTES = [
    { selector: "h1", comment: "Demasiado largo. Pon "Precios simples"", author: "claude" },
    { selector: "#cta", comment: "Usa el azul de la marca" },
  ]
  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)
  

  Cada nota incluye selector (o boundingBox: {x, y, width, height} en coordenadas de página), comment y un author opcional. Las notas cuyo selector no coincide con nada se omiten con una advertencia en consola, así que comprueba que el recuento coincida. En lugar de ANNOTATOR_NOTES, pasa ?endpoint=http://localhost:4747 para mostrar las notas del servidor para esa página; añade &all=1 para incluir las resueltas. Cargarlo de nuevo con un nuevo t oculta la capa.
• Los sitios con CSP estricto (GitHub y otros) bloquean ese script. En Playwright, crea el contexto con bypassCSP: true; de lo contrario, usa la extensión.
• Para hacer reales tus notas (el usuario también las ve en su barra y puede resolverlas): POST /sessions con {"url": "<url de la página>"} y luego POST /sessions/:id/annotations con comment, element, elementPath (un selector CSS), url, boundingBox y x/y (coordenadas de página). Luego muéstralas con ?endpoint=…. Pregunta primero al usuario: estas notas se vuelven compartidas.

Problemas comunes

• La barra es solo para escritorio.
• El servidor de notas no tiene autenticación, solo CORS. Cualquier persona cuyo origen de navegador esté permitido puede escribir y eliminar notas.
• useHashLocation mantiene las notas por #ruta. Activarlo más tarde no mueve las notas existentes.
• Agentation tiene licencia PolyForm Shield, que es adecuada para uso interno de comentarios.