cicy-desktop 1.0.8

package/.github/workflows/build.yml

@@ -0,0 +1,85 @@
+name: Build and Release
+
+on:
+  push:
+    branches:
+      - alpha
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run build:win
+        
+      - name: Rename installer
+        shell: bash
+        run: |
+          if [ "${{ github.ref_type }}" == "branch" ]; then
+            mv "dist/Electron MCP Setup 1.0.0.exe" "dist/Electron.MCP.Setup.alpha.exe"
+            # 删除其他文件，只保留 exe
+            find dist -type f ! -name "*.exe" -delete
+          fi
+        
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows-build
+          path: dist/*.exe
+
+  release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+      
+      - name: Delete existing alpha release
+        if: github.ref_type == 'branch'
+        run: |
+          gh release delete alpha -y || true
+          git push origin :refs/tags/alpha || true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          
+      - name: Create Alpha Release
+        if: github.ref_type == 'branch'
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: alpha
+          files: artifacts/**/*.exe
+          prerelease: true
+          name: "Alpha Release (Latest)"
+          body: |
+            ## Alpha Release
+            
+            最新的 alpha 分支自动构建
+            
+            **文件:** Electron.MCP.Setup.alpha.exe
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          
+      - name: Create Tag Release
+        if: github.ref_type == 'tag'
+        uses: softprops/action-gh-release@v1
+        with:
+          files: artifacts/**/*.exe
+          prerelease: true
+          name: "Release ${{ github.ref_name }}"
+          body: |
+            ## Release ${{ github.ref_name }}
+            
+            标签版本构建
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.kiro/steering/dev-workflow.md

@@ -0,0 +1,166 @@
+---
+inclusion: always
+---
+
+# Git 开发工作流程 - Git Development Workflow
+
+## ⚠️ 开发前必读
+
+**在开始任何开发任务前，必须完整阅读本文档并严格遵循所有规范。**
+
+违反规范将导致：
+- ❌ 代码被拒绝合并
+- ❌ 浪费时间重做
+- ❌ 影响项目质量
+
+## 🚨 核心原则（必须遵守）
+
+1. **开发前必读本文档** - 不要凭记忆或猜测
+2. **严格遵循每个阶段** - 不要跳过任何步骤
+3. **遇到问题先分析** - 不要盲目重试
+4. **测试驱动开发** - 一功能一测试
+5. **全部测试通过才提交** - npm test 必须 100% 通过
+
+## 新功能/Bug修复标准流程
+
+当收到开发新功能或修复bug的请求时，严格遵循以下流程：
+
+### 阶段1：需求分析
+1. **用户提出需求**
+2. **AI 制定可行方案**
+   - 分析技术实现路径
+   - 评估工作量和风险
+   - 提出具体实现方案
+3. **询问用户是否有补充**
+4. **等待用户确认"开始"**
+
+### 阶段2：环境准备（用户说"开始"后执行）
+```bash
+# 分支命名规范：
+# - 新功能：feat-MMDD-功能简述
+# - Bug修复：fix-MMDD-问题简述
+
+# 1. 直接在工作目录克隆并创建分支
+mkdir -p ~/projects/electron-mcp/branches/
+git clone -b origin/main git@github.com:cicy-dev/electron-mcp.git ~/projects/electron-mcp/branches/<branch-name>
+sudo ln -s /<branch-name> ~/projects/electron-mcp/branches/<branch-name>
+cd /<branch-name>
+git fetch origin
+git checkout -b <branch-name> origin/main
+
+# 2. 安装依赖
+npm install
+```
+
+### 阶段3：需求文档化
+在工作目录创建 `task/task-<branch-name>.md` 文档，包含：
+
+```markdown
+# 任务：[功能/Bug简述]
+
+## 需求描述
+[用户原始需求]
+
+## 实现方案
+[技术方案详细说明]
+
+## TODO 清单
+- [ ] 任务1
+- [ ] 任务2
+- [ ] 任务3
+
+## 验收标准
+- [ ] 功能正常工作
+- [ ] 所有测试通过
+- [ ] 代码符合规范
+- [ ] 文档已更新
+```
+
+### 阶段4：开发实现
+```bash
+# 在工作目录进行开发
+cd /<branch-name>
+
+# ⚠️ 必须遵循：一功能一测试
+# ❌ 禁止：写完所有代码再测试
+# ✅ 正确：每完成一个功能立即测试
+
+# 实时更新 TASK.md 中的完成状态
+```
+
+**核心原则：增量开发，持续验证**
+
+### 阶段5：本地测试（❗强制要求）
+```bash
+# ⚠️ 必须运行完整测试套件
+npm test
+
+# ❌ 如果测试失败，绝对不能提交
+# ✅ 必须所有测试通过才能进入下一阶段
+# ✅ 验证所有验收标准
+```
+
+**⚠️ 警告：如果跳过此步骤直接提交，视为严重违规！**
+
+**遇到测试失败时：**
+1. ❌ 不要盲目重试
+2. ✅ 仔细阅读错误信息
+3. ✅ 分析失败原因（依赖缺失？代码错误？环境问题？）
+4. ✅ 总结问题根源
+5. ✅ 制定修复方案
+6. ✅ 修复后再次测试
+
+### 阶段6：提交和推送
+```bash
+# 提交更改
+git add .
+git commit -m "feat/fix: 简要描述更改内容"
+
+# 推送到远程
+git push origin <branch-name>
+```
+
+### 阶段7：创建 Pull Request
+```bash
+# 使用 GitHub CLI 创建 PR
+gh pr create --base main --head <branch-name> --title "标题" --body "详细描述"
+
+# 或手动在 GitHub 网页创建 PR
+```
+
+## 分支命名示例
+
+### 新功能
+- `feat-0206-add-cdp-scroll`
+- `feat-0206-multi-account-support`
+- `feat-0206-network-monitor`
+
+### Bug修复
+- `fix-0206-window-close-crash`
+- `fix-0206-screenshot-memory-leak`
+- `fix-0206-test-timeout`
+
+## 工作目录结构
+```
+~/
+├── projects/
+│   └── electron-mcp/main             # 主仓库
+└── projects/electron-mcp/branches/
+    ├── feat-0206-feature1/
+    ├── fix-0206-bug1/
+    └── feat-0206-feature2/
+```
+
+## 核心原则
+- ✅ 始终基于 `origin/main` 创建新分支
+- ✅ 使用独立工作目录避免污染主仓库
+- ✅ **本地测试必须全部通过才能提交（npm test）**
+- ✅ **一功能一测试，不要全写完再测试**
+- ✅ 分支名称包含日期和清晰的功能/问题描述
+- ✅ 提交信息遵循 conventional commits 规范
+- ❌ **禁止跳过测试直接提交代码**
+- ❌ **禁止一次性写完所有代码**
+
+---
+**制定时间：2026-02-06**
+**适用项目：electron-mcp**

package/AGENTS.md

@@ -0,0 +1,247 @@
+# AGENTS.md
+
+This file provides guidelines for AI agents working on this codebase.
+
+## Build, Lint, and Test Commands
+
+### Core Commands
+
+```bash
+# Start the MCP server (runs Electron app with MCP endpoint)
+npm start
+
+# Start with specific port
+npm start -- --port=8102
+
+# Start with URL and single window mode
+npm start -- --url=http://example.com --one-window
+
+# Run all tests (Jest with forceExit to handle Electron processes)
+npm test
+
+# Run a single test file
+npm test -- api.ping.test.js
+
+# Run tests matching a pattern
+npm test -- --testNamePattern="ping"
+
+# Format code with Prettier
+npm run format
+
+# Check formatting
+npm run format:check
+
+# Build distributables
+npm run build
+```
+
+### Test Configuration
+
+- Tests are in `tests/` directory with pattern `*.test.js`
+- Jest runs with `--runInBand` (serial execution) due to Electron's single-process nature
+- Tests use supertest for HTTP API testing
+- Tests spawn actual Electron processes on dynamic ports
+- Auth token loaded from `~/data/electron/token.txt`
+- Test utilities in `tests/test-utils.js`
+
+## Code Style Guidelines
+
+### Language
+
+- **CommonJS** only - use `require()` not ES modules
+- Plain JavaScript - no TypeScript
+- ES6+ features: async/await, arrow functions, template literals
+
+### File Organization
+
+```
+src/
+  main.js              # Main entry: Electron + Express + MCP server
+  config.js            # Configuration constants
+  tools/               # MCP tool implementations
+    ping.js
+    window-tools.js
+    cdp-tools.js
+    exec-js.js
+  utils/               # Utility modules
+    window-utils.js
+    window-monitor.js
+    cdp-utils.js
+    snapshot-utils.js
+    auth.js
+tests/                 # Test files
+  test-utils.js        # Shared test utilities
+  *.test.js            # Individual test files
+```
+
+### Imports Order
+
+```javascript
+// 1. Built-in Node modules
+const fs = require("fs");
+const path = require("path");
+
+// 2. External dependencies
+const { BrowserWindow } = require("electron");
+const { z } = require("zod");
+const express = require("express");
+
+// 3. Internal modules
+const { config } = require("../config");
+const { createWindow } = require("../utils/window-utils");
+```
+
+### Naming Conventions
+
+- **Classes**: PascalCase (`AuthManager`, `BrowserWindow`)
+- **Functions/variables**: camelCase (`getWindows`, `registerTool`)
+- **Constants**: SCREAMING_SNAKE_CASE (`PORT`, `LOGS_DIR`)
+- **Tool names**: snake_case (`open_window`, `get_windows`)
+- **File names**: kebab-case for tests (`api.ping.test.js`)
+
+### Error Handling
+
+All tool handlers must return structured MCP responses:
+
+```javascript
+try {
+  // ... operation
+  return {
+    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+  };
+} catch (error) {
+  return {
+    content: [{ type: "text", text: `Error: ${error.message}` }],
+    isError: true,
+  };
+}
+```
+
+### Tool Registration Pattern
+
+```javascript
+const { z } = require("zod");
+
+function registerTools(registerTool) {
+  registerTool(
+    "tool_name",
+    "Description of what the tool does",
+    z.object({
+      win_id: z.number().optional().default(1).describe("Window ID"),
+      param: z.string().describe("Required parameter"),
+    }),
+    async ({ win_id, param }) => {
+      try {
+        // Implementation
+        return { content: [{ type: "text", text: "result" }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true };
+      }
+    },
+    { tag: "Category" } // OpenAPI grouping tag
+  );
+}
+
+module.exports = registerTools;
+```
+
+### Response Formats
+
+```javascript
+// Text response
+return { content: [{ type: "text", text: "message" }] };
+
+// JSON response
+return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+
+// Image response (NativeImage from Electron)
+return {
+  content: [
+    { type: "text", text: `Image: ${width}x${height}` },
+    { type: "image", data: base64String, mimeType: "image/png" },
+  ],
+};
+
+// Error response
+return { content: [{ type: "text", text: "error message" }], isError: true };
+```
+
+### Common Patterns
+
+#### Window Lookup
+
+```javascript
+const win = BrowserWindow.fromId(win_id);
+if (!win) throw new Error(`Window ${win_id} not found`);
+```
+
+#### JSON Serialization with BigInt
+
+```javascript
+JSON.stringify(result, (key, value) => (typeof value === "bigint" ? value.toString() : value), 2);
+```
+
+#### NativeImage Handling
+
+```javascript
+if (result?.constructor.name === "NativeImage") {
+  const size = result.getSize();
+  const base64 = result.toPNG().toString("base64");
+  return {
+    content: [
+      { type: "text", text: `Image: ${size.width}x${size.height}` },
+      { type: "image", data: base64, mimeType: "image/png" },
+    ],
+  };
+}
+```
+
+### Testing Patterns
+
+```javascript
+const { setPort, setupTest, teardownTest, sendRequest } = require("./test-utils");
+
+describe("Feature Test Suite", () => {
+  beforeAll(async () => {
+    setPort(8102); // Set test port
+    await setupTest(); // Start Electron + establish SSE
+  }, 30000);
+
+  afterAll(async () => {
+    await teardownTest(); // Cleanup
+  });
+
+  test("should do something", async () => {
+    const response = await sendRequest("tools/call", {
+      name: "tool_name",
+      arguments: { param: "value" },
+    });
+    expect(response.result).toBeDefined();
+  });
+});
+```
+
+### Logging
+
+Use electron-log with consistent format:
+
+```javascript
+const log = require("electron-log");
+log.info("[MCP] Server starting");
+log.error("[MCP] Error:", error);
+```
+
+### Security
+
+- Never log secrets or API keys
+- Validate all inputs with Zod schemas
+- Return structured errors without internal details
+- Auth token loaded from `~/data/electron/token.txt`
+
+### Electron Best Practices
+
+- Use `electronApp.whenReady()` for initialization
+- Handle `window-all-closed` event properly
+- Enable remote debugging with `--remote-debugging-port`
+- Use `nodeIntegration: false` and `contextIsolation: true`
+- Multi-account support via `partition: persist:sandbox-{accountIdx}`

package/CLAUDE.md

@@ -0,0 +1,162 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is an Electron-based MCP (Model Context Protocol) server that provides browser automation and web scraping capabilities. It exposes window management, Chrome DevTools Protocol (CDP) operations, and page interaction tools through a standardized MCP interface.
+
+## Development Commands
+
+### Starting the Server
+```bash
+# Start MCP server (default port 8101)
+npm start
+
+# Start with custom port
+npm start -- --port=8102
+
+# Start in test mode with environment variables
+export URL=https://www.google.com
+export TEST=true
+export DISPLAY=:1
+npx electron main.js
+```
+
+### Testing
+```bash
+# Run complete test suite
+npm test
+
+# Run specific test categories
+npm run test:api          # Basic API tests
+npm run test:cdp          # All CDP tools tests
+npm run test:cdp-mouse    # CDP mouse operations
+npm run test:cdp-keyboard # CDP keyboard operations
+npm run test:cdp-page     # CDP page operations
+
+# Run single test with pattern
+npm test -- --testNamePattern="cdp_click"
+```
+
+### Development Setup
+```bash
+# Install dependencies
+npm install
+
+# Kill existing processes on port
+pkill electron
+```
+
+## Architecture
+
+### Core Components
+
+**main.js** - Main application file containing:
+- `ElectronMcpServer` class - Core MCP server implementation
+- Tool registration system using `registerTool()` method
+- HTTP server with SSE (Server-Sent Events) transport
+- Authentication token management
+- Network monitoring and resource capture system
+
+**start-mcp.js** - Server launcher with:
+- Port management and conflict resolution
+- Background process spawning
+- Logging system (~/logs/electron-mcp.log)
+- Process lifecycle management
+
+**snapshot-utils.js** - Screenshot utilities:
+- Page capture with automatic macOS scaling
+- Clipboard integration
+- MCP-compatible image format conversion
+
+### MCP Tool Categories
+
+1. **Window Management**: `get_windows`, `open_window`, `close_window`, `load_url`, `get_title`
+2. **Code Execution**: `invoke_window`, `invoke_window_webContents`, `invoke_window_webContents_debugger_cdp`
+3. **CDP Mouse**: `cdp_click`, `cdp_double_click`
+4. **CDP Keyboard**: `cdp_press_key`, `cdp_type_text`, `cdp_press_key_enter`, etc.
+5. **CDP Page**: `cdp_scroll`, `cdp_find_element`, `cdp_execute_script`, `cdp_get_page_title`
+6. **Screenshots**: `webpage_screenshot_to_clipboard`
+7. **System**: `ping`
+
+### Authentication System
+
+- Auto-generates authentication tokens stored in `~/data/electron/token.txt`
+- All HTTP requests require `Authorization: Bearer <token>` header
+- Token validation in `validateAuth()` method
+
+### Network Monitoring
+
+The server automatically captures network resources when pages load:
+- Monitors Network.* CDP events
+- Saves resources by type: html, json, js, css, images
+- Organizes by domain in `~/data/captured_data/`
+- Prettifies JSON and code content
+
+## Key Implementation Details
+
+### Tool Registration Pattern
+```javascript
+this.registerTool(
+  "tool_name",
+  "Description in Chinese",
+  { param: z.string().describe("Parameter description") },
+  async ({ param }) => {
+    // Implementation
+    return { content: [{ type: "text", text: "Result" }] };
+  }
+);
+```
+
+### Code Execution Context
+- `invoke_window`: Access to `win` (BrowserWindow) and `webContents` objects
+- `invoke_window_webContents`: Access to `webContents` and `win` objects
+- `invoke_window_webContents_debugger_cdp`: Access to `debuggerObj`, `webContents`, `win`
+
+### Error Handling
+- All tools return `{ isError: true }` for failures
+- Comprehensive error messages with stack traces
+- Parameter validation using Zod schemas
+
+### Test Architecture
+- Uses Jest with supertest for HTTP API testing
+- SSE connection management for real-time communication
+- Comprehensive CDP tool coverage (33 test cases)
+- Automatic Electron process lifecycle management
+- Authentication token integration
+
+## Common Patterns
+
+### Adding New Tools
+1. Use `registerTool()` in the `setupTools()` method
+2. Follow the established parameter validation pattern with Zod
+3. Add corresponding test cases in `tests/api.test.js`
+4. Update documentation
+
+### CDP Operations
+- Always check if debugger is attached: `debuggerObj.isAttached()`
+- Attach with version: `debuggerObj.attach('1.3')`
+- Use `sendCommand()` for CDP protocol calls
+- Handle async operations with proper await
+
+### Window Management
+- Window IDs are used consistently across all window operations
+- Default window ID is 1 when not specified
+- Always validate window existence before operations
+
+## Environment Variables
+
+- `PORT`: Server port (default: 8101)
+- `TEST`: Enable test mode with auto-window creation
+- `URL`: Default URL for test window
+- `DISPLAY`: X11 display for headless environments
+- `NODE_ENV`: Environment mode (test/development/production)
+
+## File Structure Notes
+
+- Main server logic in `main.js` (1141 lines)
+- Comprehensive test suite in `tests/api.test.js` (712 lines)
+- Utility functions separated in `snapshot-utils.js`
+- Process management in `start-mcp.js`
+- All dependencies managed through `package.json`