Snowfort Circuit MCP - 用于Web应用和Electron应用的计算机使用

Snowfort Circuit MCP 是一个全面的模型上下文协议（MCP）服务器套件，使AI编码代理能够以无与伦比的精度和灵活性自动化Web浏览器和Electron桌面应用程序。

🚀 AI代理快速入门

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": "默认输入"
})
// 所有后续对话将被自动处理

桌面应用自动化

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']"})
// 响应包含：“成功点击元素”+带有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项目：

# 第一步：首先在终端中启动您的开发服务器
npm run start

# 第二步：一旦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 - 用于所有后续命令

如何工作：

• 🚀 使用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