# 本地开发助手（Local MCP Server）

Windows 本地开发 MCP Server，让 AI 在明确的工作区边界内调用文件、命令、浏览器和桌面工具。

## 核心能力

- **工作区隔离**：先绑定项目目录，再通过独立 `workspace_handle` 操作，避免不同项目互相影响。
- **文件与代码操作**：读取、搜索、创建、修改和删除项目文件，并对正式写入提供 Git / 备份保护。
- **命令与进程**：运行受控开发命令、测试和后台进程，并限制工作目录和执行边界。
- **浏览器工具**：支持页面结构读取、网络检查和隔离浏览器验证。
- **桌面控制**：支持窗口、鼠标、键盘和截图等本地桌面操作。
- **临时文件隔离**：诊断脚本和一次性文件放在项目目录之外，避免污染正式代码。
- **Secure MCP Tunnel**：让 ChatGPT 通过受控通道连接本机 MCP；本地 MCP 仍只监听本机地址，不直接开放公网端口。

## 运行环境

- Windows 10 / 11 64 位
- Python 3.12 x64
- Windows PowerShell 5.1 或更高版本
- 首次安装需要联网下载 Python 依赖和 Playwright Chromium

## 安装与启动

在仓库目录打开 PowerShell：

```powershell
.\install.ps1
.\doctor.ps1
.\start.ps1
```

默认地址：

```text
MCP:    http://127.0.0.1:18766/mcp
Health: http://127.0.0.1:18766/health
```

停止服务：

```powershell
.\stop.ps1
```

如果本机端口冲突，可以指定其他端口：

```powershell
.\start.ps1 -Port 18776
.\doctor.ps1 -Port 18776
.\stop.ps1 -Port 18776
```

如果 PowerShell 阻止本地脚本执行：

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
```

## 连接 ChatGPT

本地 MCP 可以独立运行；只有 ChatGPT 需要访问本机 MCP 时才需要 Tunnel。

先在 OpenAI Platform 创建 Tunnel，并准备对应的 Runtime API key，然后执行：

```powershell
.\setup-tunnel.ps1 -TunnelId tunnel_...
```

脚本会下载官方 `openai/tunnel-client`、校验 SHA256，并通过隐藏输入保存 Runtime API key。

启动 Tunnel：

```powershell
.\start-tunnel.ps1
.\status-tunnel.ps1
.\doctor.ps1 -Tunnel
```

停止 Tunnel：

```powershell
.\stop-tunnel.ps1
```

Tunnel 配置、客户端和加密后的 Runtime API key 默认保存在 `%LOCALAPPDATA%\LocalAssistantMCP`，不会写入仓库。

## 安全边界

- MCP 只监听 `127.0.0.1`，不会直接绑定公网地址。
- 项目操作受工作区边界约束，跨工作区操作会被拒绝。
- 沙箱执行和受控主机命令分别处理不同权限需求，主机命令仍受路径和参数限制。
- Runtime API key 使用 Windows CurrentUser DPAPI 加密保存。
- 带账号密码的代理地址不会写入配置文件。
- 桌面控制可以操作真实窗口，只应连接你信任的 MCP 客户端。

## 测试

安装开发依赖并运行完整测试：

```powershell
.\install.ps1 -Dev
.\run_tests.ps1
```

## License

MIT License。见 [LICENSE](LICENSE)。