Circuit MCP

🚀 Snowfort Circuit MCP - ウェブアプリとElectronアプリ用のコンピューター

Snowfort Circuit MCPは、包括的なモデルコンテキストプロトコル（MCP）サーバースイートです。これにより、AIコーディングエージェントは、ウェブブラウザとElectronデスクトップアプリケーションの両方を、比類のない精度と柔軟性で自動化することができます。

🚀 クイックスタート

MCPの設定

AIエージェントのMCP設定ファイルに以下を追加します。

ウェブ自動化のみ

{
  "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']"})

✨ 主な機能

🌐 ウェブ自動化（29のツール）

• クロスブラウザサポート：Chromium、Firefox、WebKit
• 🎯 AI最適化スナップショット：すべてのアクション後に要素参照付きの自動スナップショット
• 📸 スマートスクリーンショット圧縮：高速なAIワークフローのためのJPEG圧縮（設定可能）
• 完全なインタラクションセット：クリック、入力、ホバー、ドラッグ、スクロールなどの自動コンテキスト付き操作
• 🖱️ マルチタブ管理：ブラウザタブの作成、切り替え、一覧表示、閉じる
• 📊 ネットワークとコンソール監視：リアルタイムのリクエスト追跡とコンソールキャプチャ
• 高度な入力：ファイルアップロード、ドロップダウン選択、キーボードショートカット
• コンテンツ抽出：HTMLコンテンツ、テキストコンテンツ、要素参照付きのアクセシビリティツリー
• ビジュアルキャプチャ：圧縮されたスクリーンショット、PDF生成
• ナビゲーション：履歴管理、ページ再読み込み、URLナビゲーション
• ダイアログ処理：自動アラート/確認/プロンプト管理
• ブラウザ制御：ビューポートのリサイズ、ウィンドウ管理
• 🧪 テスト生成：記録されたアクションからPlaywrightテストコードを自動生成
• JavaScript実行：ページコンテキストでカスタムスクリプトを実行
• スマートウェイト：要素の表示、ネットワークアイドル、ページロード状態

🖥️ デスクトップ自動化（32のツール）

• 🎯 AI最適化デスクトップ制御：自動スナップショット付きでElectronアプリを起動して制御
• 📸 スマートスクリーンショット圧縮：高速なAIワークフローのためのJPEG圧縮（設定可能）
• 🔧 開発モードサポート：自動検出で開発中のアプリを起動
• ユニバーサルElectronサポート：任意のElectronアプリケーション（パッケージ化または開発中）
• マルチウィンドウ管理：複数のアプリウィンドウを同時に制御
• IPC通信：アプリとの直接的なプロセス間通信
• ネイティブファイルシステム：直接ファイルの読み書き
• 強化されたターゲティング：ロールベースのクリック、n番目の要素選択、テキストベースのターゲティング
• アクセシビリティ第一：要素参照付きの組み込みアクセシビリティツリーナビゲーション
• 状態管理：高度なページ状態の待機と監視
• 🐛 コンソールとネットワーク監視：アプリケーションログとネットワークリクエストをキャプチャしてデバッグ
• すべてのウェブツール：すべてのウェブ自動化ツールがデスクトップコンテキストで動作

🔧 アーキテクチャの利点

• 🤖 AI第一の設計：最適なAIワークフローのための自動スナップショット、要素参照、および圧縮画像
• ランタイムアプリ選択：起動時ではなくツール呼び出し時にElectronアプリを指定
• セッション管理：完全に分離された複数の同時自動化セッション
• 型安全：包括的な型定義付きの完全なTypeScriptサポート
• エラーハンドリング：堅牢なエラー報告と回復
• パフォーマンス最適化：効率的なリソース使用と高速実行

📚 ドキュメント

🌐 ウェブツール

🖥️ Electronツール

💻 使用例

ウェブ自動化ワークフロー

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番目の要素によるクリック
• 🔧 完全な自動化：スクリーンショット、JavaScript評価、キーボード/マウス制御
• 🧹 自動クリーンアップ：セッションと開発サーバーは自動的に閉じられます
• 🪟 スマートウィンドウ管理：DevToolsウィンドウは自動的にフィルタリングされ、メインウィンドウが検出されます

プロのヒント

• compressScreenshots: true（デフォルト）を使用して、より高速なAI処理を実現します。
• MCPは新しいインスタンスを起動します - 実行中のアプリにアタッチすることはできません。
• Electron Forgeの場合は、常に開発サーバーを最初に起動し、その後MCPで起動します。
• DevToolsウィンドウは自動的にフィルタリングされます - 常にメインアプリウィンドウが取得されます。
• disableDevtools: trueを使用して、DevToolsの自動開啟を防止します。
• get_windowsを使用して、すべてのウィンドウの種類（メイン/DevTools/その他）を確認します。

以上です！ 他のすべてのツールは、ウェブバージョンと同じように機能します。楽しく自動化しましょう！ 🎉

📖 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が返されます - その後のすべてのコマンドにこれを使用します

仕組み:

• 🚀 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)

高度な設定

完全な品質でのウェブ開発モード

// デバッグ用に圧縮されていないスクリーンショットでブラウザを起動
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  // デバッグ用の完全なPNG品質
})

最適なパフォーマンスの本番モード

// ウェブ: 速度のために最大圧縮で起動
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開発の問題

"Not connected"エラー

問題: 有効なセッションがない状態で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オプション

ウェブサーバー (@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       # ウェブ自動化サーバー（29のツール）
└── @snowfort/circuit-electron@latest  # デスクトップ自動化サーバー（32のツール）

ローカル開発:
packages/
├── core/          # 共有MCPインフラストラクチャとドライバーインターフェース
├── web/           # AI最適化されたウェブ自動化CLI
└── electron/      # デスクトップ自動化CLI

📦 公開されているパッケージ

パッケージ	バージョン	説明
@snowfort/circuit-core		コアMCPインフラストラクチャ
@snowfort/circuit-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

ローカル開発サーバーの実行

# ウェブ自動化サーバー
./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ツール統合の革新を推進するModel Context Protocolコミュニティ

すべてを自動化する準備はできましたか？ 上記のMCP設定から始めて、AI最適化されたデュアルエンジン自動化の力を解放しましょう！ 🚀