shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

circuit-mcp

Snowfort Circuit MCP是一个全面的模型上下文协议服务器套件，为AI编码代理提供网页和Electron桌面应用自动化能力，具有AI优化的快照、智能截图压缩和多会话管理等功能。

article

README

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

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

项目状态

License npm npm

🚀 快速开始

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 | npm | 核心MCP基础设施 | | @snowfort/circuit-web | npm | Web自动化CLI（29种工具） | | @snowfort/circuit-electron | npm | 桌面自动化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优化的双引擎自动化的力量！🚀

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client