DevTool MCP

agnt

为你的 AI 编码 Agent 赋予浏览器超能力。

什么是 agnt？

agnt 是一种专为 AI 辅助开发时代打造的新型工具。它充当 AI 编码 Agent 与浏览器之间的桥梁，拓展氛围编程时的可能性。

当你使用 Claude Code、Cursor 或其他 AI 编码工具进行开发时，agnt 可以让你的 Agent：

• 看到你看到的内容 - 截屏、DOM 检查和可视化调试
• 直接听取你的意见 - 从浏览器向 Agent 发送消息
• 一起勾画创意 - 直接在 UI 上绘制线框图
• 实时调试 - 捕获错误、网络流量和性能指标
• 在任何设备上测试 - 通过隧道连接手机和 BrowserStack，并进行全面监测
• 扩展思考窗口 - 结构化数据比你的描述占用更少的令牌

演示

盲目使用终端自动化三轮，仍无法修复一半位于屏幕外的按钮。实时查看页面，一次即可修复 — 完整演示（1:40）。

直接在运行中的应用上绘制线框图，然后发送给你的 AI Agent

愿景：扩展 Agent 的能力

传统 AI 编码助手无法看到浏览器中发生的事情。它们可以编写代码，却无法：

• 看到更改后的视觉效果
• 知道何时发生 JavaScript 错误
• 理解你遇到的布局问题
• 在你不输入文字的情况下接收反馈

agnt 将改变这一切。 它在浏览器与 AI Agent 之间建立双向通道：

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│   Your Browser  │ ←──► │      agnt       │ ←──► │   AI Agent      │
│                 │      │                 │      │                 │
│  - See changes  │      │  - Proxy traffic│      │  - Receives     │
│  - Send notes   │      │  - Capture errors│     │    context      │
│  - Draw sketches│      │  - Inject tools │      │  - Acts on      │
│  - Click to log │      │  - Route messages│     │    feedback     │
└─────────────────┘      └─────────────────┘      └─────────────────┘

快速入门

安装

npm（推荐）：

npm install -g @standardbeagle/agnt

pip/uv：

pip install agnt
# or
uv pip install agnt

从源代码安装：

git clone https://github.com/standardbeagle/agnt.git
cd agnt
make build && make install-local

作为 MCP 服务（Claude Code、Cursor 等）

添加到你的 MCP 配置中：

{
  "mcpServers": {
    "agnt": {
      "command": "agnt",
      "args": ["mcp"]
    }
  }
}

或者安装为 Claude Code 插件：

/plugin marketplace add standardbeagle/agnt
/plugin install agnt@agnt

一键安装：agnt skills — 一条命令即可安装 agnt Agent 技能并注册 MCP 服务。它会使用 Vercel 的开源技能 CLI 获取技能，然后配置 MCP：

agnt skills                 # install for Claude Code + register the MCP server
agnt skills --agent cursor  # install the skills for a different agent

它在底层会运行 npx -y skills add standardbeagle-tools/agnt --all -a claude-code，然后运行 claude mcp add agnt -s user -- agnt mcp（对其他 Agent，它会打印需要添加的 MCP 配置）。要求 PATH 中存在 Node.js（npx）。

作为 PTY 包装器（增强终端）

为 AI 工具套上包装器以启用叠加层功能：

agnt run claude --dangerously-skip-permissions
agnt run cursor
agnt run aider

这会添加终端叠加层菜单（Ctrl+P），并启用浏览器到终端的消息桥接。

首次运行设置（自动配置新项目）

首次在没有 .agnt.kdl 的项目中运行 agnt run claude 时，agnt 会在编码会话开始前执行一次性的设置流程：

cd my-new-project        # no .agnt.kdl yet
agnt run claude

大多数项目都不会进入设置阶段：agnt 会先尝试确定性的自动配置，并在项目结构明确时自行写入 .agnt.kdl。开箱即支持以下项目：

项目结构	标记	开发脚本和代理
Node Web 应用	package.json 中包含 dev/start 脚本	运行该脚本，通过 URL 检测配置代理
Go（Wails）	wails.json	wails dev
.NET Web 项目	根目录或 src/* / */ 下包含使用 Web SDK 的 *.csproj	dotnet watch run（每个项目分别配置，端口取自 launchSettings.json）
docker-compose	compose.yaml / docker-compose.yml	docker compose up，为每个发布主机端口的服务配置一个代理
Procfile	Procfile.dev / Procfile	每个条目对应一个脚本，在 web 上配置代理
Django	manage.py	python manage.py runserver（8000）
Rails	bin/rails	bin/dev 或 bin/rails server（3000）
Laravel	artisan	composer run dev 或 php artisan serve（8000）
Phoenix	包含 :phoenix 的 mix.exs	mix phx.server（4000）
Hugo / Jekyll / mkdocs	hugo.toml + content/、_config.yml + Gemfile、mkdocs.yml	hugo server（1313）、bundle exec jekyll serve（4000）、mkdocs serve（8000）
静态网站	根目录中的 index.html	标准库文件服务器（8000）

检测结果会累积：包含 compose 文件的 .NET 解决方案会同时配置 dotnet test/build 和 compose 拓扑。Go、Node、Python、Ruby、PHP、Elixir 和 .NET 的测试、lint 和构建命令会注册为按需运行的脚本。已知端口会写入 fallback-port，以便在首次请求前启动代理。生成的文件可以自由编辑；更改会实时生效。

只有自动配置无法判断时，才会运行设置阶段：

1. 设置阶段 — Claude 以设置模式启动并配置项目：检测技术栈、注册开发服务器 脚本和反向代理，并写入 .agnt.kdl。如果尚未安装 agnt:setup-project 技能，Claude 会告知具体的安装步骤（/plugin marketplace add standardbeagle/agnt，然后执行 /plugin install agnt）。
2. 重新启动 — 设置退出后，agnt 会以启用自动启动的方式重新启动 Claude，进入普通编码 会话，并重放原始参数。开发服务器和代理会自动启动。

# Pass a task through — it's replayed verbatim into the relaunched session:
agnt run claude -- "add a /healthz endpoint"

如果你拒绝设置（没有写入 .agnt.kdl），agnt 会记录带时间戳的标记，并在重新提醒间隔结束前不再提示（默认 7 天，可通过 .agnt.kdl 中的 setup { renudge-ttl-days 7 } 配置）。成功完成设置后会永久记录。

设置也支持其他 Agent — 每种 Agent 都会获得适合其自身技能/命令机制的安装说明（参见 docs/agent-support-matrix.md）。

agnt init — 不启动会话，仅配置项目

想单独设置项目？agnt init 只运行设置阶段 （不会重新启动会话），并在写入 .agnt.kdl 后退出：

agnt init            # configure with claude
agnt init gemini     # configure with a different agent

成功运行 agnt init 后也会记录永久标记，因此之后运行 agnt run 会直接进入编码会话。

通道模式（Beta — 仅适用于 Claude Code）

Beta / 实验性功能：通道模式需要使用分叉的 MCP SDK，并在 Claude Code 中启用开发标志。行为和架构可能会发生变化。

Claude Code v2.1.80+ 可以接收实时浏览器错误、诊断信息和用户交互，并将其作为推送事件传入上下文——无需 PTY 包装器。在 .agnt.kdl 中添加 channel { enabled true }，并使用 claude --dangerously-load-development-channels server:agnt 启动。有关完整架构、事件格式，以及用于向浏览器浮层发送消息的 channel_reply 工具，请参阅 CLAUDE.md 中的通道模式章节。

核心功能

1. 浏览器超能力

启动代理后，你的 Agent 就能洞察浏览器：

proxy {action: "start", id: "app", target_url: "http://localhost:3000"}

现在，你的 Agent 可以：

// Take screenshots
proxy {action: "exec", id: "app", code: "__devtool.screenshot('current-state')"}

// Inspect any element
proxy {action: "exec", id: "app", code: "__devtool.inspect('#submit-button')"}

// Audit accessibility
proxy {action: "exec", id: "app", code: "__devtool.auditAccessibility()"}

// Check what the user clicked
proxy {action: "exec", id: "app", code: "__devtool.interactions.getLastClickContext()"}

2. 悬浮指示器

每个经过代理的页面都会显示一个小小的悬浮虫子图标。点击它即可：

• 直接向你的 AI Agent 发送消息
• 截取特定区域的屏幕截图
• 选择元素并记录其详细信息
• 打开草图模式进行线框设计

不必再切换窗口来描述所见内容——只需点击并发送。

3. 草图模式

按下草图按钮，直接在 UI 上绘制：

• 矩形、圆形、箭头和徒手绘图
• 线框元素：按钮、输入框、便笺
• 一键保存并发送给你的 Agent

无需输入任何文字，就能轻松表达“我想在这里放个按钮”或“这个布局不对”。

4. 实时错误捕获

JavaScript 错误会自动捕获，并提供给你的 Agent：

proxylog {proxy_id: "app", types: ["error"]}
→ {message: "TypeError: Cannot read property 'map' of undefined",
   stack: "at ProductList (products.js:42)",
   timestamp: "..."}

错误发生时，你的 Agent 就能看到，而不必等到你想起要提及时。

5. 扩展思考窗口

与自然语言描述相比，结构化数据消耗的令牌更少：

• 错误摘要——proxylog {types: ["error"]}，而不是“我在第 42 行遇到一个 TypeError，错误信息是……”
• 点击上下文——interactions.getLastClickContext()，而不是“我点击了页眉里的蓝色按钮……”
• DOM 状态——inspect('#element')，而不是“有一个 div，里面嵌套着一些 span……”
• 整合后的堆栈跟踪——将预处理后的 React 错误墙转换为可执行的摘要
• 状态一目了然——结构化 JSON，便于你的 Agent 高效解析

agnt 不会把 100 行嵌套的 React 错误直接塞进上下文，而是将冗长输出整合为简洁、可执行的数据。

6. 以任何身份登录

在 .agnt.kdl 中声明测试用户，agnt 就会在代理上提供开发用 OIDC 颁发方。你可以通过指示器中的身份切换控件、在终端输入 :as admin，或使用 devauth 工具让你的 Agent 在普通用户和管理员之间切换。整个过程不需要真实的 IdP 账户。

支持 loopback、tailnet（bind "tailscale"，身份信息来自 tailscale whois；如果 tailnet 提供节点证书，则通过 HTTPS 提供服务），也支持在具名 Cloudflare tunnel 后运行，并在源站验证 Access。请参阅开发登录与受保护共享。

MCP 工具

工具	描述
detect	自动检测项目类型和可用脚本
run	执行脚本或命令（后台/前台）
proc	管理进程：状态、输出、停止、列表
proxy	反向代理：启动、停止、执行、状态
proxylog	查询日志：http、error、screenshot、sketch、panel_message
currentpage	查看活动页面会话及分组资源
get_incidents	从始终处于活动状态的事件收件箱中获取权威数据
responsive_audit	对不同视口尺寸进行响应式审计（布局/溢出/无障碍）
api_audit	API 效率审计：瀑布图、N+1、重复请求、频繁请求
loading_audit	加载体验审计：加载指示器级联 + 并发碎片化
snapshot	视觉回归：基准/对比截图
tunnel	隧道管理：cloudflare/ngrok（公开）或 tailscale（仅限 tailnet）
devauth	开发用 OIDC 身份：列出、切换浏览器身份、生成令牌
verify_change	修复后重新检查会话记录的问题
daemon	管理后台守护进程服务
watch	通过 agnt monitor 流式传输守护进程事件
channel_reply	向开发者的浏览器叠加层发送消息（仅限频道模式）

Browser API（50 多个函数）

代理会注入 window.__devtool，提供强大的诊断功能：

元素检查

__devtool.inspect('#element')     // Full element analysis
__devtool.getPosition('#element') // Bounding box and position
__devtool.isVisible('#element')   // Visibility check

视觉调试

__devtool.highlight('.items')           // Highlight elements
__devtool.mutations.highlightRecent()   // Show recent DOM changes
__devtool.screenshot('name')            // Capture screenshot

无障碍

__devtool.auditAccessibility()    // Full a11y audit with score
__devtool.getContrast('#text')    // Color contrast check
__devtool.getTabOrder()           // Tab navigation order

交互

__devtool.interactions.getLastClick()        // Last click details
__devtool.interactions.getLastClickContext() // Full click context
__devtool.selectElement()                    // Interactive picker

草图模式

__devtool.sketch.open()    // Enter sketch mode
__devtool.sketch.save()    // Save and send to agent
__devtool.sketch.toJSON()  // Export sketch data

响应式模式

__devtool.responsive.open()       // Open the interactive width workbench
__devtool.responsive.setWidth(414) // Drive the frame to a width (320–1920)
__devtool.responsive.getState()    // Read current width + detected layout shifts

评分审计

__devtool.auditAll()  // 8 weighted audits: dom, css, perf, security, seo,
                      // a11y, API efficiency, loading/spinner → overall grade

配置

在项目根目录创建 .agnt.kdl，以自动启动脚本、代理并配置浏览器通知：

// Scripts to run via daemon process manager
scripts {
    dev {
        run "npm run dev"           // Shell command (recommended)
        autostart true
        url-matchers "(Local|Network):\\s*{url}"
    }

    api {
        command "go"                // Or use command + args
        args "run" "./cmd/server"
        autostart true
        env {
            GIN_MODE "debug"
        }
        cwd "./backend"
    }
}

// Reverse proxies with traffic logging
proxies {
    frontend {
        script "dev"               // Link to script for URL auto-detection
    }

    backend {
        target "http://localhost:8080"
        autostart true
        max-log-size 2000
    }
}

// Browser notifications when AI responds
hooks {
    on-response {
        toast true                 // Show toast notification
        indicator true             // Flash bug indicator
        sound false                // Play notification sound
    }
}

// Toast appearance
toast {
    duration 4000
    position "bottom-right"        // top-right, top-left, bottom-right, bottom-left
    max-visible 3
}

在 Claude Code 中运行 /setup-project，即可交互式生成此配置。

特定框架的 URL 匹配器：

框架	url-matchers
Next.js / Vite / React	"(Local|Network):\\s*{url}"
Wails	"DevServer URL:\\s*{url}"
Astro	"Local\\s+{url}"
Jekyll	"Server address:\\s*{url}"
Hugo	"Web Server.*available at {url}"

架构

agnt 使用守护进程架构来持久化状态：

┌─────────────────────┐       ┌─────────────────────────────────────┐
│  AI Agent           │       │              agnt                   │
│  (Claude Code, etc.)│◄─────►│                                     │
│                     │ MCP   │  ┌────────────────┐                 │
└─────────────────────┘       │  │  MCP Server    │                 │
                              │  └───────┬────────┘                 │
                              │          │ socket                   │
                              │          ▼                          │
┌─────────────────────┐       │  ┌────────────────────────────────┐ │
│  Browser            │◄──────┼──│        Daemon                  │ │
│                     │ proxy │  │  ProcessManager │ ProxyManager │ │
│  __devtool API      │       │  └────────────────────────────────┘ │
│  Floating Indicator │       └─────────────────────────────────────┘
│  Sketch Mode        │
└─────────────────────┘

关键设计决策：

• 使用 sync.Map 和原子操作实现无锁并发
• 使用环形缓冲区限制内存占用
• 客户端断开连接后，进程和代理仍会继续运行
• 前端 JavaScript 零依赖

文档

完整文档 →

# Run docs locally
cd docs-site
npm install && npm start

使用场景

• 氛围编程 - 让 Agent 看到所有内容，让你保持专注
• 视觉调试 - 与其描述，不如直接展示，勾画出问题所在
• 移动端测试 - 使用 Cloudflare/ngrok 隧道连接开发服务，以便在真实设备上测试，并集成 BrowserStack
• 无障碍测试 - 在开发过程中自动进行 a11y 审计
• 错误追踪 - 在用户发现之前捕获前端错误
• UI 审查 - 直接在运行中的应用上标注设计
• 远程协作 - 与 Agent 分享视觉上下文

要求

• Node.js 18+ 或 Go 1.24+
• 兼容 MCP 的 AI 助手

从 devtool-mcp 迁移

agnt 是 devtool-mcp 的新名称。现有用户：

# npm
npm uninstall -g @standardbeagle/devtool-mcp
npm install -g @standardbeagle/agnt

# pip
pip uninstall devtool-mcp
pip install agnt

更新 MCP 配置，使用 agnt 命令和 ["mcp"] 参数。

许可证

MIT

贡献

欢迎贡献！有关架构详情，请参阅文档。