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

工具	描述	關鍵參數
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		核心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優化的雙引擎自動化的力量！🚀