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優化的雙引擎自動化的力量！🚀