# mcp4gui

**Repository Path**: andershsueh/mcp4gui

## Basic Information

- **Project Name**: mcp4gui
- **Description**: 在GUI界面里使用的local map 工具. 
- **Primary Language**: JavaScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-13
- **Last Updated**: 2025-12-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 桌面交互工具（MCP 工具集）

此仓库用于为 AI Agent / ai-cli 提供本地 MCP 工具，支持桌面截图（低清/原始/聚焦）、鼠标键盘模拟、浏览器启动、历史对比、AI 笔记、人机协作（转交人类）、可选 DOM/无障碍树获取与登录态复用。完整技术规范见 `docs/ai-desktop-tool-spec.md`。

## 目录结构建议
- `main/` 主进程（IPC、权限/频控/白名单、日志、历史存储、notes 写入）
- `native/` Node-API C++ 插件（截图、鼠标、键盘，按平台拆分）
- `renderer/` 授权与状态 UI
- `services/` 业务逻辑（history/notes/schema 校验/频控）
- `schemas/` JSON Schema
- `docs/` 规范与测试用例（已含 `ai-desktop-tool-spec.md`, `test_case.md`）
- `test/` 测试脚本占位

## 快速开始
1) 安装依赖：`npm install`
2) 运行主进程：`npm run dev`（默认启用授权 UI，HTTP `/invoke` 端口 3001，可通过 `HTTP_PORT` 覆盖）
3) 测试：`npm test`（Vitest，FAKE_MODE 下可在无原生依赖环境运行）
4) 类型检查：`npm run typecheck`
5) 打包：`npm run build`（electron-builder，三平台模板；未签名，需自行配置证书）

## 环境与变量
- Node 18+ / Electron 28（见 `package.json`）
- FAKE 模式：`MCP_FAKE_CAPTURE=1`、`MCP_FAKE_INPUT=1`、`MCP_FAKE_DOM=1` 可在无原生插件环境运行与测试。
- 历史/笔记/会话存储路径：
  - `MCP_HISTORY_DIR`、`MCP_NOTES_FILE`、`MCP_SESSION_FILE`、`MCP_HANDOFF_FILE`
- HTTP 网关：`ENABLE_HTTP_GATEWAY`（默认开启）、`HTTP_PORT`。

## 测试
- 用例清单：见 `docs/test_case.md`。
- 单测：`test/handlers.spec.js` 覆盖参数校验、白名单/授权/频控、notes/session/handoff/dom_snapshot/browser、history TTL/配额、FAKE 截图/输入、错误码与性能指标。
- 集成（最小 E2E）：`test/sample.spec.js` 通过 HTTP `/invoke` 验证 observe/notes/session/handoff/history 流程。
- 性能：在 FAKE 截图路径中记录并校验 P50/P95，频控超限返回 `RATE_LIMIT`。

## 打包与签名
- 配置文件：`electron-builder.yml`（asar 开启，mac dmg / win nsis / linux AppImage）。
- 签名占位：mac `identity: null`，win 未配置证书。需自行提供签名证书后在配置中填写（或通过环境变量/CI 注入），无证书可保持当前值跳过签名。
- 输出目录：`dist_electron/`。不会自动上传或发布。

## 部署与 CI
- 当前不接入 CI，请手动运行 `npm run typecheck && npm test && npm run build` 后再部署。

## 参考
- 详细技术规范：`docs/ai-desktop-tool-spec.md`
- 测试用例说明：`docs/test_case.md`
- 分阶段开发指南：`docs/phase1_dev_guide.md` ~ `docs/phase5_dev_guide.md`