Circuit MCP

电路MCP-用于网络应用程序和电子应用程序的计算机


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代理可以立即开始自动化：

// Launch browser with optimized AI settings
browser_launch({
  "compressScreenshots": true,
  "screenshotQuality": 50
})
browser_navigate({"sessionId": "...", "url": "https://github.com"})
// Auto-snapshot included in response!

// Launch and control any Electron app
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工作流程（可配置）
• 🔧 开发模式支持：在开发过程中启动具有自动检测功能的应用程序
• 通用电子支持：任何电子应用程序（打包或开发）
• 多窗口管理：同时控制多个应用程序窗口
• IPC通信：与应用程序直接进行进程间通信
• 本机文件系统：直接读/写文件
• 增强目标定位：基于角色的点击、第n个元素选择、基于文本的定位
• 可访问性优先：内置可访问性树导航，带有元素引用
• 状态管理：高级页面状态等待和监控
• 🐛 控制台和网络监控：捕获应用程序日志和网络请求以进行调试
• 所有Web工具：每个web自动化工具都可以在桌面环境中工作

🔧 架构优势

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

📚 完整的工具参考

🌐 Web工具

🖥️ 电子工具

💡 使用示例

Web自动化工作流

AI优化浏览器启动

// Launch with optimal AI settings
const session = await browser_launch({
  "compressScreenshots": true,
  "screenshotQuality": 50,
  "headed": false
})

// Navigation automatically includes page snapshot with element refs
await browser_navigate({
  "sessionId": session.id, 
  "url": "https://github.com"
})
// Response includes auto-snapshot with element references like ref="e1", ref="e2"

多选项卡工作流

// Create and manage multiple tabs
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})
// Shows all tabs with titles, URLs, and active status

基于引用的元素定位

// Navigate and get element references
await browser_navigate({"sessionId": session.id, "url": "https://example.com"})
// Auto-snapshot response includes:
// {"role": "button", "name": "Sign In", "ref": "e5"}

// Click using standard selector (auto-snapshot included)
await click({"sessionId": session.id, "selector": "button:has-text('Sign In')"})
// Response includes updated page snapshot showing interaction result

网络和控制台监控

// Monitor page activity
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})

// Generate test code from actions
const testCode = await browser_generate_playwright_test({"sessionId": session.id})

对话框处理

// Set up automatic dialog handling
await browser_handle_dialog({
  "sessionId": session.id,
  "action": "accept",
  "promptText": "Default input"
})
// All subsequent dialogs will be handled automatically

桌面应用程序自动化

AI优化桌面启动

// Launch with optimal AI settings for packaged apps
const session = await app_launch({
  "app": "/Applications/Visual Studio Code.app",
  "compressScreenshots": true,
  "screenshotQuality": 50
})
// All interactions automatically include window snapshots with element refs!
await click({"sessionId": session.id, "selector": "[title='New File']"})
// Response includes: "Element clicked successfully" + snapshot with ref="e1", ref="e2"

开发模式支持

// NEW: Launch Electron app during development
const session = await app_launch({
  "app": "/Users/dev/my-electron-project",
  "mode": "development",
  "compressScreenshots": false  // Full quality for debugging
})

// Auto-detect packaged vs development
const session2 = await app_launch({
  "app": "/path/to/app-or-project",
  "mode": "auto"  // Automatically detects launch mode
})

电子锻造支架（v0.5.7中的新功能）

推荐方法（最可靠）：

// 1. First, run in a separate terminal:
// npm run start

// 2. Wait for webpack to compile, then launch with MCP:
const session = await app_launch({
  "app": "/path/to/forge-project",
  "mode": "development"
  // Don't use startScript - let manual npm start handle it
})
// This approach ensures proper timing and reliable launches

实验性自动启动功能：

// The MCP can attempt to auto-start the dev server (experimental)
const session = await app_launch({
  "app": "/path/to/forge-project",
  "mode": "development",
  "startScript": "start"  // Attempts to run 'npm run start' automatically
})
// Features: 30s timeout, progress updates every 5s, enhanced Forge pattern detection
// Note: If you experience problems, use the manual approach above

🚀 电子自动化快速入门指南

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

对于电子锻造项目：

# Step 1: In terminal, start your dev server first
npm run start

# Step 2: Once webpack compiles, use the MCP to launch
await app_launch({
  "app": "/path/to/your/project",
  "mode": "development"
})

对于常规电子项目：

// Just launch directly - no prep needed!
await app_launch({
  "app": "/path/to/project",
  "mode": "development",
  "disableDevtools": true  // Optional: prevent DevTools auto-opening
})

对于打包应用程序：

// Launch .app, .exe, or AppImage files
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 查看所有具有类型标识的窗口（main/devtools/other）

就是这样！ 所有其他工具的工作方式都和网络版本一样。自动化快乐！ 🎉

📖 人工智能代理的传统指令（Claude、Claude.md等）

⚠️ 重要提示： MCP启动自己的Electron实例-您无法连接到已运行的应用程序。

对于电子开发项目：

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

const session = await app_launch({
  "app": "/path/to/your/electron/project",
  "mode": "development"
})
// Returns sessionId automatically - use this for all subsequent commands

工作原理：

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

人工智能工作流程的主要优势：

• 🤖 自动快照 在每个带有元素引用的操作之后(ref="e1", ref="e2")
• 📸 压缩截图 默认情况下，处理速度更快
• 🎯 直接元素定位 在快照中使用提供的引用
• 🔄 无需手动调用快照 -上下文是自动提供的

代码编辑器自动化

// Traditional packaged app automation
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"]})

多窗口管理

// Work with multiple windows
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"})

控制台和网络监控

// Launch Electron app and monitor activity
const session = await app_launch({"app": "/Applications/MyElectronApp.app"})

// Perform some actions that generate logs/network activity
await click({"sessionId": session.id, "selector": "#load-data-button"})
await wait_for_load_state({"sessionId": session.id, "state": "networkidle"})

// Get console logs for debugging
const consoleLogs = await browser_console_messages({"sessionId": session.id})
console.log("App console output:", consoleLogs)

// Get network requests to see API calls
const networkRequests = await browser_network_requests({"sessionId": session.id})
console.log("Network activity:", networkRequests)

高级配置

全质量的Web开发模式

// Launch browser with uncompressed screenshots for debugging
const session = await browser_launch({
  "compressScreenshots": false,  // Full PNG quality
  "headed": true,                // Visible browser
  "viewport": {"width": 1920, "height": 1080}
})

电子开发模式

// Launch Electron app during development with full quality
const session = await app_launch({
  "app": "/Users/dev/my-electron-project",
  "mode": "development",
  "compressScreenshots": false  // Full PNG quality for debugging
})

性能优化的生产模式

// Web: Launch with maximum compression for speed
const webSession = await browser_launch({
  "compressScreenshots": true,
  "screenshotQuality": 30,      // Maximum compression
  "headed": false               // Headless for performance
})

// Electron: Launch packaged app with compression
const electronSession = await app_launch({
  "app": "/Applications/MyApp.app",
  "compressScreenshots": true,
  "screenshotQuality": 30       // Maximum compression
})

🔧 故障排除

常见电子开发问题

“未连接”错误

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

解决方案：

// ❌ Wrong - no session exists
get_windows({"sessionId": "test"})

// ✅ Correct - launch first, then use returned sessionId
const session = await app_launch({"app": "/path/to/project", "mode": "development"})
get_windows({"sessionId": session.id})

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

问题： 尝试连接到现有 npm run start 过程

解决方案： 停止现有进程，让MCP启动您的应用程序

# Stop existing process
kill $(ps aux | grep 'Electron .' | awk '{print $2}')

# Let MCP launch instead
app_launch({"app": "/your/project", "mode": "development"})

未找到电子

问题： 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     Browser engine: chromium, firefox, webkit (default: chromium)
  --headed           Run in headed mode (default: headless)
  --name       Server name for MCP handshake (default: circuit-web)

电子服务器(@snowfort/circuit-electron)

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

Options:
  --name       Server name for MCP handshake (default: 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"]
    }
  }
}

🏗️ 建筑

Published Packages:
├── @snowfort/circuit-core@latest      # Core MCP infrastructure
├── @snowfort/circuit-web@latest       # Web automation server (29 tools)
└── @snowfort/circuit-electron@latest  # Desktop automation server (32 tools)

Local Development:
packages/
├── core/          # Shared MCP infrastructure & Driver interface
├── web/           # Web automation CLI with AI optimizations
└── electron/      # Desktop automation CLI

📦 已发布的软件包

🔧 发展

地方发展设置

# Clone the repository
git clone https://github.com/clharman/circuit-mcp.git
cd circuit-mcp

# Install dependencies
pnpm install

# Build all packages
pnpm -r build

# Watch mode development
pnpm -r dev

运行本地开发服务器

# Web automation server
./packages/web/dist/esm/cli.js --headed

# Desktop automation server  
./packages/electron/dist/esm/cli.js

测试

# Run all tests
pnpm -r test

# Clean all builds
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许可证2.0获得许可-请参阅 许可证 文件以获取详细信息。

独立实施全面自动化测试

🙏 致谢

• 剧作家 自动化框架
• MCP-SDK 用于协议实现
• 推动人工智能工具集成创新的模型上下文协议社区