用 Agentation 把 UI 註解直接餵給 AI agent
跟 AI coding agent 說「這個按鈕往左一點」、「這裡間距怪怪的」，最後往往變成一大段文字描述，模型還是抓錯元素。這篇主要想分享給：平常用 Cursor、Claude Code 改前端，但又懶得截圖標箭頭的人。
Agentation 的做法很直接——在瀏覽器裡點元素、留註解，輸出結構化 context 給 agent 讀。我最近在這個站的 Next.js 專案裝好了，從 React component 到 Cursor MCP 都走過一遍，紀錄如下。
⸻
▍Agentation 是什麼？
dev-only 的 React overlay。開發模式下你可以：
- 點頁面上任何元素
- 寫要改什麼
- 複製 markdown，或同步到本機 MCP server
預設資料不會離開你的電腦。註解先留在瀏覽器，除非你手動複製，或接上 localhost。對設計師跟前端來說，跟 Cursor、Claude Code、Codex 這類工具搭起來，feedback loop 會緊很多。
❖ 關鍵句：不是截圖工具，是把「你手指指著哪裡」變成 agent 讀得懂的格式。
⸻
▍安裝與掛載
❶ 安裝套件
專案根目錄執行：
pnpm add agentation -D
裝在 dev dependency 就好，production 不需要。
❷ 掛到 app root
Next.js App Router 通常放在 src/app/layout.tsx：
import { Agentation } from "agentation";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<>
{process.env.NODE_ENV === "development" && <Agentation />}
<html lang="en">
<body>{children}</body>
</html>
</>
);
}
NODE_ENV 檢查很重要。Agentation 會讀 DOM，只該出現在本地開發，別帶進 production。
跑 pnpm dev，桌面瀏覽器打開網站就能看到 UI。（官方說不優化手機，別在手機上硬試。）
⸻
▍接上 AI agent：MCP 設定
手動複製貼上也行，但老實說，MCP 同步順很多。Agentation MCP server 提供 agentation_get_all_pending、agentation_list_sessions、agentation_resolve 等工具，agent 可以即時讀取、處理你的註解。
一鍵註冊（支援多種 agent）：
npx add-mcp "npx -y agentation-mcp server"
Cursor 手動設定 — 在 .cursor/mcp.json 加上：
{
"mcpServers": {
"agentation": {
"command": "npx",
"args": ["-y", "agentation-mcp", "server"]
}
}
}
驗證是否設定正確：
npx agentation-mcp doctor
預設 port 是 4747，要換的話加 --port 8080。改完 MCP config 記得重開 Cursor。
⸻
▍開啟即時同步
要讓 component 跟 server 連線，加上 endpoint：
<Agentation
endpoint="http://localhost:4747"
onSessionCreated={(sessionId) => {
console.log("Session started:", sessionId);
}}
/>
接上之後：
- 註解先存本地，server 在線才同步
- 重新整理頁面會回到同一個 session，不會洗出一堆重複註解
- agent 那邊 resolve / dismiss 的狀態，重連時以 server 為準
沒設 endpoint 也能用——一切留在瀏覽器，自己 copy markdown 貼給 agent。
⸻
▍實際工作流長怎樣
我現在大概是這樣跑：
- 開 dev server，打開要 review 的頁面
- 點元素加註解（「padding 加大」、「字重不對」、「連結應該去 /blog」）
- 在 Cursor 叫 agent 看 pending 的 Agentation feedback
- agent 改完，逐條 resolve
比截圖 → 描述 → 祈禱模型猜對節點，快不只一點。
⸻
▍安全與需求
官方文件 有幾點值得記：
- 預設不外傳 — 處理都在 client-side，除非你主動接 MCP
- 只連本機 — 有
endpoint也是打到你的 machine，不是第三方服務 - dev-only — 務必保留
NODE_ENV判斷
需求：React 18+、需要 DOM（component 掛在 layout / client boundary）、桌面瀏覽器。
⸻
❖ 【Asset】快速檢查清單
- [ ]
pnpm add agentation -D - [ ]
layout.tsx加上{process.env.NODE_ENV === "development" && <Agentation />} - [ ]
npx add-mcp "npx -y agentation-mcp server"或手動寫.cursor/mcp.json - [ ]
npx agentation-mcp doctor確認沒問題 - [ ] （選用）
endpoint="http://localhost:4747"開即時同步 - [ ] 重開 Cursor，跑一輪點選 → agent 修 → resolve
⸻
延伸閱讀
如果你每天都在跟 AI agent 改 UI，Agentation 算是那種裝了之後「怎麼以前沒有」的小工具。下次開 dev branch 試試看，你的「幫我改這塊」prompt 應該會短不少。