theyoungastronauts Skill: Visual Feedback with Agentation MCP
Overview
Use browser annotations to drive frontend fixes. Humans mark up the live page, Claude picks up annotations via MCP and resolves them — no copy-paste, no describing UI bugs in words.
When to Use
- Fixing visual/layout issues on a running web app
- Iterating on UI with a human reviewer annotating in-browser
- Any frontend task where "point at the broken thing" beats describing it
- NOT for backend-only work, API logic, or non-visual changes
Setup
1. Install the package
npm install agentation -D
2. Add the browser component
React / Next.js — in your root layout (e.g., src/app/layout.tsx):
import { Agentation } from "agentation";
// Inside <body>, after your content:
{process.env.NODE_ENV === "development" && <Agentation />}
Astro — create a React island wrapper:
// src/components/dev/AgentationOverlay.tsx
import { Agentation } from "agentation";
export default function AgentationOverlay() {
return <Agentation />;
}
Then include in your base layout (e.g., src/layouts/BaseLayout.astro):
---
import AgentationOverlay from '@/components/dev/AgentationOverlay.tsx';
---
<!-- Inside <body>, after <Footer /> -->
{import.meta.env.DEV && <AgentationOverlay client:only="react" />}
Astro requires @astrojs/react, react, and react-dom as dependencies.
3. Configure MCP
Option A — project .mcp.json (recommended, shared with team):
{
"mcpServers": {
"agentation": {
"command": "npx",
"args": ["agentation-mcp", "server"]
}
}
}
Option B — per-user CLI:
claude mcp add agentation -- npx agentation-mcp server
4. Verify
npx agentation-mcp doctor
The browser toolbar connects to an HTTP server (port 4747 default), which feeds annotations to Claude via MCP stdio.
MCP Tools Available
| Tool | Purpose |
|---|---|
agentation_list_sessions |
List active annotation sessions |
agentation_get_session |
Get annotations for a session |
agentation_get_pending |
Pending annotations for a session |
agentation_get_all_pending |
All pending across sessions |
agentation_acknowledge |
Mark annotation as seen |
agentation_resolve |
Mark annotation as fixed |
agentation_dismiss |
Dismiss an annotation |
agentation_reply |
Reply to an annotation thread |
agentation_watch_annotations |
Block until new annotations arrive |
Workflow
- Human opens the running app with the Agentation toolbar active
- Human clicks elements and leaves annotations (fix / change / question / approve)
- Annotations include CSS selectors and React component paths — use these to locate code
- Fetch pending annotations, acknowledge them, make the fix
- Mark resolved once the change is committed or verified
Hands-Free Mode
Use agentation_watch_annotations in a loop to auto-process feedback as it arrives. Good for rapid iteration sessions where the human is continuously reviewing.
Annotation Data
Each annotation includes:
- Element selector — CSS selector for the annotated DOM element
- Component path — React component tree path (when available)
- Intent —
fix,change,question, orapprove - Severity —
blocking,important, orsuggestion - Comment — Human's description of the issue
Common Mistakes
- Ignoring severity — address
blockingannotations beforesuggestion - Not acknowledging annotations — the human can't tell you've seen them
- Resolving without verifying — mark resolved only after the fix is confirmed
- Using watch mode without a batch window — set a reasonable timeout to avoid thrashing