LinOS MCP Bridge

English · 中文

让你的本地机器成为 AI 可以安全使用的“双手”：一个自托管的 MCP（Model Context Protocol）服务器，把文件读写、命令执行、Git、后台长任务暴露给 ChatGPT 以及任意 MCP 客户端（Cursor / Claude / Codex / VS Code…），并带桌面控制中心、审计链和断点交接。

⚠️ 安全前提：这个程序会让 AI 以你当前 Windows 用户的身份操作这台机器。默认只开只读工具；写文件、执行命令、PowerShell、屏幕等能力必须你显式开启。不要在不受信任的环境里开“全权模式”。

它解决什么问题

Related MCP server: Kontrol

架构

Electron 主进程（窗口 / 托盘 / IPC）
 ├─ Supervisor 子进程        命名管道 + Capability-MAC
 │   └─ Runtime 子进程      HTTP 127.0.0.1:48766/mcp（JSON-RPC 2.0）
 └─ cloudflared 子进程（可选）公网命名隧道

• 渲染层无 Node 权限，只能通过 preload 暴露的白名单 IPC；

• 每个 IPC 通道要求调用方提交预期 capability 字符串；

• Runtime 的所有路径必须落在工作区内（越界即拒绝）；

• 命令执行有白名单（git / npm / python / pytest / node），禁止 shell 元字符与 -c/--exec；

• 审计日志逐条 prevHash + hash 链式，可校验是否被改。

快速开始

需要 Windows 10/11、Node.js ≥ 20。

git clone <this-repo>
cd linos-mcp-bridge
npm ci
npm run build:runtime
npm run build
npm start

一键安装（推荐）：

powershell -ExecutionPolicy Bypass -File .\scripts\setup.ps1

它会检查 Node 版本、安装依赖、构建 runtime 与界面，并打印后续步骤。

首次启动会进入「快速设置」：选工作区目录 → 选端口（默认 48766）→ 生成配对码。

公网访问：三选一

完整步骤与排错见 docs/INSTALL.md。

接入 ChatGPT

1. 控制中心「连接授权」→ 生成配对码；

2. ChatGPT → 设置 → 连接器 → 新建，URL 填 https://<你的域名>/mcp；

3. OAuth 页面输入配对码 → 允许。

接入其他客户端

• Cursor / Claude Desktop / Codex / VS Code：设置页「其他 AI 接入」生成长期令牌，复制现成配置片段；

• 网页版 AI（DeepSeek / Gemini / 千问）：装 extension/ 里的浏览器扩展，页面右下角出现面板。

安全模型（务必读）

建议：先只用只读；确认工作流后，再按需开启写入；命令与 PowerShell 最后开。

目录结构

src/main          Electron 主进程（IPC、Supervisor 适配、托盘、健康探测）
src/preload       暴露给渲染层的白名单 API
src/renderer      React 界面（总览、连接、工作区、诊断、项目看板、MCP 进度）
runtime/src       MCP 服务器（HTTP/OAuth、工具实现、审计、任务引擎）
extension/        Chrome/Edge 浏览器扩展
scripts/          安装与隧道脚本（setup.ps1 / tunnel-quick.ps1 / tunnel-named.ps1）
docs/             安装说明、故障经验库

测试

npm test                 # 主包（约 420 项）
cd runtime; npm test     # runtime（约 109 项）

状态

早期可用版本（0.1.0）。接口与配置可能变化；生产使用前请自评估安全边界。

许可

MIT，见 LICENSE。第三方依赖许可见 THIRD_PARTY_NOTICES.md。

参与共建

这个项目从第一天就是按"能被别人接手"来写的，欢迎任何人参与：

共建原则：安全默认优先（新能力默认关闭）、可验证优先（说修好了就给复现步骤）、可撤销优先（破坏性动作要有备份与回滚）。

一键上手（不想看文档的话）

1. 双击 install.cmd（装依赖 + 构建 + 启动）

2. 之后双击 start.cmd

3. 要在公网给 ChatGPT 用：scripts\tunnel-quick.ps1（当天试用）或 scripts\tunnel-named.ps1 -Domain 你的域名（长期固定）