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工具

🖥️ Electron工具

💻 使用示例

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优化的双引擎自动化的力量！🚀