Circuit MCP

🚀 Snowfort Circuit MCP - 用于Web应用和Electron应用的计算机工具

Snowfort Circuit MCP是一套全面的模型上下文协议（MCP）服务器套件，它使AI编码代理能够以前所未有的精度和灵活性自动操作Web浏览器和Electron桌面应用程序。

项目状态

🚀 快速开始

MCP配置

将以下内容添加到你的AI代理的MCP配置文件中：

仅用于Web自动化

{
  "mcpServers": {
    "circuit-web": {
      "command": "npx",
      "args": ["@snowfort/circuit-web@latest"]
    }
  }
}

仅用于桌面自动化

{
  "mcpServers": {
    "circuit-electron": {
      "command": "npx",
      "args": ["@snowfort/circuit-electron@latest"]
    }
  }
}

完整的双引擎设置（推荐）

{
  "mcpServers": {
    "circuit-web": {
      "command": "npx",
      "args": ["@snowfort/circuit-web@latest"]
    },
    "circuit-electron": {
      "command": "npx",
      "args": ["@snowfort/circuit-electron@latest"]
    }
  }
}

首次命令

配置完成后，你的AI代理可以立即开始自动化操作：

// 使用优化的AI设置启动浏览器
browser_launch({
  "compressScreenshots": true,
  "screenshotQuality": 50
})
browser_navigate({"sessionId": "...", "url": "https://github.com"})
// 响应中包含自动快照！

// 启动并控制任何Electron应用程序
app_launch({"app": "/Applications/Visual Studio Code.app"})
click({"sessionId": "...", "selector": "button[title='New File']"})

✨ 主要特性

🌐 Web自动化（29种工具）

• 跨浏览器支持：支持Chromium、Firefox、WebKit浏览器。
• 🎯 AI优化快照：每次操作后自动生成带有元素引用的快照。
• 📸 智能截图压缩：支持JPEG压缩，可加快AI工作流程（可配置）。
• 完整交互集：支持点击、输入、悬停、拖动、滚动等操作，并带有自动上下文。
• 🖱️ 多标签管理：可创建、切换、列出和关闭浏览器标签。
• 📊 网络和控制台监控：实时跟踪请求和捕获控制台信息。
• 高级输入：支持文件上传、下拉选择、键盘快捷键等操作。
• 内容提取：可提取HTML内容、文本内容、可访问性树等，并带有元素引用。
• 视觉捕获：支持压缩截图、生成PDF。
• 导航：支持历史记录控制、页面重新加载、URL导航等操作。
• 对话框处理：自动管理警告、确认和提示对话框。
• 浏览器控制：支持视口调整、窗口管理。
• 🧪 测试生成：根据记录的操作自动生成Playwright测试代码。
• JavaScript执行：可在页面上下文中运行自定义脚本。
• 智能等待：可等待元素出现、网络空闲、页面加载状态等。

🖥️ 桌面自动化（32种工具）

• 🎯 AI优化桌面控制：可启动和控制Electron应用程序，并自动生成快照。
• 📸 智能截图压缩：支持JPEG压缩，可加快AI工作流程（可配置）。
• 🔧 开发模式支持：支持在开发过程中启动应用程序，并自动检测。
• 通用Electron支持：支持任何Electron应用程序（打包或开发中）。
• 多窗口管理：可同时控制多个应用程序窗口。
• IPC通信：可直接与应用程序进行进程间通信。
• 原生文件系统：可直接读写文件。
• 增强定位：支持基于角色的点击、第n个元素选择、基于文本的定位等。
• 无障碍优先：内置可访问性树导航，并带有元素引用。
• 状态管理：支持高级页面状态等待和监控。
• 🐛 控制台和网络监控：可捕获应用程序日志和网络请求，用于调试。
• 所有Web工具：所有Web自动化工具均可在桌面环境中使用。

🔧 架构优势

• 🤖 以AI为中心的设计：自动生成快照、元素引用和压缩图像，优化AI工作流程。
• 运行时应用选择：可在调用工具时指定Electron应用程序，而不是在启动时。
• 会话管理：支持多个并发自动化会话，且相互隔离。
• 类型安全：完全支持TypeScript，并提供全面的类型定义。
• 错误处理：提供强大的错误报告和恢复机制。
• 性能优化：高效使用资源，执行速度快。

📚 详细文档

🌐 Web工具

工具	描述	关键参数
browser_launch	使用AI优化设置启动浏览器	browser, headed, viewport, compressScreenshots, screenshotQuality
browser_navigate	导航到指定URL（包含自动快照）	sessionId, url
browser_resize	调整浏览器视口大小	sessionId, width, height
browser_handle_dialog	设置对话框自动响应	sessionId, action, promptText
browser_tab_new	创建新的浏览器标签	sessionId
browser_tab_list	列出所有打开的标签	sessionId
browser_tab_select	切换到指定标签	sessionId, tabId
browser_tab_close	关闭指定标签	sessionId, tabId
browser_network_requests	获取网络请求历史记录	sessionId
browser_console_messages	获取控制台消息历史记录	sessionId
browser_generate_playwright_test	根据操作生成测试代码	sessionId
click	点击元素（包含自动快照）	sessionId, selector, windowId
type	输入文本（包含自动快照）	sessionId, selector, text, windowId
hover	悬停在元素上（包含自动快照）	sessionId, selector, windowId
drag	将元素拖动到目标位置	sessionId, sourceSelector, targetSelector
key	按下键盘按键（包含自动快照）	sessionId, key, windowId
select	选择下拉选项	sessionId, selector, value
upload	上传文件到输入框	sessionId, selector, filePath
back	后退到历史记录中的上一页	sessionId
forward	前进到历史记录中的下一页	sessionId
refresh	重新加载当前页面	sessionId
screenshot	拍摄压缩截图	sessionId, path
snapshot	获取带有元素引用的可访问性树	sessionId
pdf	生成页面的PDF文件	sessionId, path
content	获取HTML内容	sessionId
text_content	获取可见文本	sessionId
evaluate	执行JavaScript代码	sessionId, script
wait_for_selector	等待元素出现	sessionId, selector, timeout
close	关闭浏览器会话	sessionId

🖥️ Electron工具

工具	描述	关键参数
app_launch	使用AI优化设置启动Electron应用程序	app, mode, projectPath, startScript, disableDevtools, compressScreenshots, screenshotQuality
get_windows	列出带有类型标识的窗口	sessionId
ipc_invoke	调用IPC方法	sessionId, channel, args
fs_write_file	将文件写入磁盘	sessionId, filePath, content
fs_read_file	从磁盘读取文件	sessionId, filePath
keyboard_press	按下带有修饰键的按键	sessionId, key, modifiers
click_by_text	根据文本点击元素	sessionId, text, exact
click_by_role	根据可访问性角色点击元素	sessionId, role, name
click_nth	点击第n个匹配的元素	sessionId, selector, index
keyboard_type	延迟输入文本	sessionId, text, delay
add_locator_handler	处理模态框/弹出窗口	sessionId, selector, action
wait_for_load_state	等待页面状态	sessionId, state
smart_click	智能点击，自动检测（引用/文本/CSS）	sessionId, target, strategy, windowId
browser_console_messages	获取Electron应用程序的控制台日志	sessionId
browser_network_requests	获取Electron应用程序的网络请求	sessionId
+ 共享Web工具	核心Web工具：click, type, screenshot, evaluate等

💻 使用示例

Web自动化工作流

AI优化的浏览器启动

// 使用优化的AI设置启动浏览器
const session = await browser_launch({
  "compressScreenshots": true,
  "screenshotQuality": 50,
  "headed": false
})

// 导航时自动包含带有元素引用的页面快照
await browser_navigate({
  "sessionId": session.id, 
  "url": "https://github.com"
})
// 响应中包含带有元素引用的自动快照，如ref="e1", ref="e2"

多标签工作流

// 创建和管理多个标签
const session = await browser_launch({})
await browser_navigate({"sessionId": session.id, "url": "https://github.com"})

const newTabId = await browser_tab_new({"sessionId": session.id})
await browser_tab_select({"sessionId": session.id, "tabId": newTabId})
await browser_navigate({"sessionId": session.id, "url": "https://stackoverflow.com"})

const tabs = await browser_tab_list({"sessionId": session.id})
// 显示所有标签的标题、URL和活动状态

使用引用定位元素

// 导航并获取元素引用
await browser_navigate({"sessionId": session.id, "url": "https://example.com"})
// 自动快照响应包含：
// {"role": "button", "name": "Sign In", "ref": "e5"}

// 使用标准选择器点击元素（包含自动快照）
await click({"sessionId": session.id, "selector": "button:has-text('Sign In')"})
// 响应中包含更新后的页面快照，显示交互结果

网络和控制台监控

// 监控页面活动
await browser_navigate({"sessionId": session.id, "url": "https://api-heavy-site.com"})
const requests = await browser_network_requests({"sessionId": session.id})
const consoleMessages = await browser_console_messages({"sessionId": session.id})

// 根据操作生成测试代码
const testCode = await browser_generate_playwright_test({"sessionId": session.id})

对话框处理

// 设置自动对话框处理
await browser_handle_dialog({
  "sessionId": session.id,
  "action": "accept",
  "promptText": "Default input"
})
// 后续所有对话框将自动处理

桌面应用程序自动化

AI优化的桌面启动

// 使用优化的AI设置启动打包应用程序
const session = await app_launch({
  "app": "/Applications/Visual Studio Code.app",
  "compressScreenshots": true,
  "screenshotQuality": 50
})
// 所有交互自动包含带有元素引用的窗口快照！
await click({"sessionId": session.id, "selector": "[title='New File']"})
// 响应中包含："Element clicked successfully" + 带有ref="e1", ref="e2"的快照

开发模式支持

// 新特性：在开发过程中启动Electron应用程序
const session = await app_launch({
  "app": "/Users/dev/my-electron-project",
  "mode": "development",
  "compressScreenshots": false  // 调试时使用全质量截图
})

// 自动检测打包和开发模式
const session2 = await app_launch({
  "app": "/path/to/app-or-project",
  "mode": "auto"  // 自动检测启动模式
})

Electron Forge支持（v0.5.7新增）

推荐方法（最可靠）：

// 1. 首先，在单独的终端中运行：
// npm run start

// 2. 等待webpack编译完成后，使用MCP启动应用程序：
const session = await app_launch({
  "app": "/path/to/forge-project",
  "mode": "development"
  // 不要使用startScript - 让手动的npm start处理它
})
// 这种方法确保了正确的时间安排和可靠的启动

实验性自动启动功能：

// MCP可以尝试自动启动开发服务器（实验性）
const session = await app_launch({
  "app": "/path/to/forge-project",
  "mode": "development",
  "startScript": "start"  // 尝试自动运行 'npm run start'
})
// 特性：30秒超时，每5秒更新进度，增强Forge模式检测
// 注意：如果遇到问题，请使用上述手动方法

Electron自动化快速入门指南

本指南适用于AI代理（CLAUDE.md）或手动参考

对于Electron Forge项目

# 步骤1：在终端中，首先启动开发服务器
npm run start

# 步骤2：webpack编译完成后，使用MCP启动应用程序
await app_launch({
  "app": "/path/to/your/project",
  "mode": "development"
})

对于常规Electron项目

// 直接启动 - 无需准备！
await app_launch({
  "app": "/path/to/project",
  "mode": "development",
  "disableDevtools": true  // 可选：防止DevTools自动打开
})

对于打包应用程序

// 启动.app、.exe或AppImage文件
await app_launch({
  "app": "/Applications/YourApp.app"
})

关键特性

• 📸 每个操作返回一个AI就绪的快照，带有元素引用（e1, e2等）。
• 🎯 多种点击方法：支持通过选择器、文本、角色或第n个元素进行点击。
• 🔧 全面自动化：支持截图、执行JS、键盘和鼠标控制。
• 🧹 自动清理：会话和开发服务器会自动关闭。
• 🪟 智能窗口管理：自动过滤DevTools窗口，可检测主窗口。

专业提示

• 使用 compressScreenshots: true（默认）以加快AI处理速度。
• MCP会启动一个新实例，无法连接到正在运行的应用程序。
• 对于Electron Forge项目：始终先启动开发服务器，然后使用MCP启动应用程序。
• DevTools窗口会自动过滤掉 - 你将始终获得主应用程序窗口。
• 使用 disableDevtools: true 防止DevTools自动打开。
• 使用 get_windows 查看所有带有类型标识的窗口（主窗口/DevTools/其他）。

就是这样！ 所有其他工具的使用方法与Web版本相同。祝你自动化愉快！🎉

📖 AI代理的旧版说明（Claude, CLAUDE.md等）

⚠️ 重要提示

MCP会启动自己的Electron实例 - 你无法连接到已经运行的应用程序。

对于Electron开发项目：

1. 停止任何现有的 npm run start 进程
2. 让MCP启动你的应用程序：

const session = await app_launch({
  "app": "/path/to/your/electron/project",
  "mode": "development"
})
// 自动返回sessionId - 后续所有命令使用此ID

工作原理：

• 🚀 使用Playwright启动新的Electron应用程序实例
• 🎯 通过Chrome DevTools协议进行全面自动化控制
• 📸 无法连接到现有的运行进程

AI工作流的关键优势：

• 🤖 每次操作后自动生成快照，带有元素引用（ref="e1", ref="e2"）
• 📸 默认使用压缩截图，加快处理速度
• 🎯 可直接使用快照中的引用定位元素
• 🔄 无需手动调用快照 - 自动提供上下文

代码编辑器自动化

// 传统打包应用程序自动化
const session = await app_launch({"app": "/Applications/Visual Studio Code.app"})
await click({"sessionId": session.id, "selector": "[title='New File']"})
await keyboard_type({"sessionId": session.id, "text": "console.log('Hello World');", "delay": 50})
await keyboard_press({"sessionId": session.id, "key": "s", "modifiers": ["ControlOrMeta"]})

多窗口管理

// 处理多个窗口
const session = await app_launch({"app": "/Applications/Slack.app"})
const windows = await get_windows({"sessionId": session.id})
await click({"sessionId": session.id, "selector": ".channel-name", "windowId": "main"})
await type({"sessionId": session.id, "selector": "[data-qa='message-input']", "text": "Hello team!", "windowId": "main"})

控制台和网络监控

// 启动Electron应用程序并监控活动
const session = await app_launch({"app": "/Applications/MyElectronApp.app"})

// 执行一些生成日志/网络活动的操作
await click({"sessionId": session.id, "selector": "#load-data-button"})
await wait_for_load_state({"sessionId": session.id, "state": "networkidle"})

// 获取控制台日志进行调试
const consoleLogs = await browser_console_messages({"sessionId": session.id})
console.log("App console output:", consoleLogs)

// 获取网络请求以查看API调用
const networkRequests = await browser_network_requests({"sessionId": session.id})
console.log("Network activity:", networkRequests)

高级配置

全质量Web开发模式

// 启动浏览器时使用未压缩的截图进行调试
const session = await browser_launch({
  "compressScreenshots": false,  // 全PNG质量
  "headed": true,                // 可见浏览器
  "viewport": {"width": 1920, "height": 1080}
})

Electron开发模式

// 在开发过程中以全质量启动Electron应用程序
const session = await app_launch({
  "app": "/Users/dev/my-electron-project",
  "mode": "development",
  "compressScreenshots": false  // 调试时使用全质量截图
})

优化性能的生产模式

// Web：为了速度使用最大压缩启动
const webSession = await browser_launch({
  "compressScreenshots": true,
  "screenshotQuality": 30,      // 最大压缩
  "headed": false               // 无头模式以提高性能
})

// Electron：以压缩模式启动打包应用程序
const electronSession = await app_launch({
  "app": "/Applications/MyApp.app",
  "compressScreenshots": true,
  "screenshotQuality": 30       // 最大压缩
})

🔧 故障排除

常见的Electron开发问题

“未连接”错误

问题：尝试在没有有效会话的情况下使用MCP命令。 解决方案：

// ❌ 错误 - 没有会话存在
get_windows({"sessionId": "test"})

// ✅ 正确 - 先启动，然后使用返回的sessionId
const session = await app_launch({"app": "/path/to/project", "mode": "development"})
get_windows({"sessionId": session.id})

无法连接到正在运行的应用程序

问题：尝试连接到现有的 npm run start 进程。 解决方案：停止现有进程，让MCP启动应用程序。

# 停止现有进程
kill $(ps aux | grep 'Electron .' | awk '{print $2}')

# 让MCP启动应用程序
app_launch({"app": "/your/project", "mode": "development"})

找不到Electron

问题：MCP无法找到Electron可执行文件。 解决方案：

1. 本地安装Electron：npm install electron --save-dev
2. 指定自定义路径：{"electronPath": "/custom/path/to/electron"}
3. 全局安装：npm install -g electron

🛠️ 配置选项

CLI选项

Web服务器 (@snowfort/circuit-web)

npx @snowfort/circuit-web@latest [options]

Options:
  --browser <type>    浏览器引擎：chromium, firefox, webkit (默认: chromium)
  --headed           以有头模式运行 (默认: 无头模式)
  --name <name>      MCP握手的服务器名称 (默认: circuit-web)

Electron服务器 (@snowfort/circuit-electron)

npx @snowfort/circuit-electron@latest [options]

Options:
  --name <name>      MCP握手的服务器名称 (默认: circuit-electron)

高级MCP配置

开发设置

{
  "mcpServers": {
    "circuit-web": {
      "command": "npx",
      "args": ["@snowfort/circuit-web@latest", "--headed", "--browser", "chromium"]
    },
    "circuit-electron": {
      "command": "npx",
      "args": ["@snowfort/circuit-electron@latest"]
    }
  }
}

生产设置

{
  "mcpServers": {
    "circuit-web": {
      "command": "npx",
      "args": ["@snowfort/circuit-web@latest"]
    },
    "circuit-electron": {
      "command": "npx",
      "args": ["@snowfort/circuit-electron@latest"]
    }
  }
}

🏗️ 架构

已发布的包：
├── @snowfort/circuit-core@latest      # 核心MCP基础设施
├── @snowfort/circuit-web@latest       # Web自动化服务器（29种工具）
└── @snowfort/circuit-electron@latest  # 桌面自动化服务器（32种工具）

本地开发：
packages/
├── core/          # 共享MCP基础设施和驱动接口
├── web/           # 带有AI优化的Web自动化CLI
└── electron/      # 桌面自动化CLI

📦 已发布的包

包	版本	描述
@snowfort/circuit-core		核心MCP基础设施
@snowfort/circuit-web		Web自动化CLI（29种工具）
@snowfort/circuit-electron		桌面自动化CLI（25+种工具）

🔧 开发

本地开发设置

# 克隆仓库
git clone https://github.com/snowfort-ai/circuit-mcp.git
cd circuit-mcp

# 安装依赖
pnpm install

# 构建所有包
pnpm -r build

# 开启监听模式开发
pnpm -r dev

运行本地开发服务器

# Web自动化服务器
./packages/web/dist/esm/cli.js --headed

# 桌面自动化服务器  
./packages/electron/dist/esm/cli.js

测试

# 运行所有测试
pnpm -r test

# 清理所有构建
pnpm -r clean

🤝 贡献

我们欢迎贡献！请参阅我们的贡献指南以获取详细信息。

1. 分叉仓库
2. 创建你的功能分支 (git checkout -b feature/amazing-feature)
3. 提交你的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

📄 许可证

本项目采用Apache License 2.0许可 - 有关详细信息，请参阅LICENSE文件。

全面自动化测试的独立实现 - © 2025 Snowfort LLC

🙏 致谢

• Playwright 提供自动化框架
• MCP SDK 提供协议实现
• 模型上下文协议社区推动AI工具集成的创新

---

准备好自动化一切了吗？ 从上面的MCP配置开始，释放AI优化的双引擎自动化的力量！🚀