跳到正文
曾亮懿 ZengLiangYi Blog

KeelDesk

基于 Tauri v2 与 Rust 构建的 Windows 11 桌面级 MCP 运行底座与本机开发工作台:内嵌 Streamable HTTP MCP 服务端、单实例托盘常驻与高危操作桌面人工审批,让 Claude Code 与 Cursor 安全调用本机工具。

目录 展开 收起

问题:本地 MCP 工具散落命令行,进程生命周期与高危操作如何纳管?

当日常开发重度依赖 Claude Code CLI、Cursor 等 AI 编程客户端时,本地 Model Context Protocol(MCP)工具的管理往往退化成一堆散落的命令行脚本与临时子进程:关闭终端后服务即中断、端口冲突难以排查,更缺乏针对破坏性系统操作(如强制终止进程、清理占用端口)的可视化确认屏障。

KeelDesk(龙骨桌面) 是为解决这一工程痛点而设计的 Windows 11 桌面级 MCP 运行底座与本机开发环境工作台。它既是一个开箱即用的本机环境巡检与活跃端口治理工具,也是一套严格遵循单向分层约束的 Tauri v2 + Rust 桌面应用参考骨架——将“桌面宿主生命周期、Streamable HTTP MCP 服务端、高危工具人工审批”沉淀为可复用的底层龙骨(keel_core + keel-sdk)。

双重定位:实用工作台 + 桌面级 MCP 工程骨架 KeelDesk 既可以直接作为日常 Windows 开发环境与端口管理桌面工具使用,也可以作为构建桌面级 MCP Server 的脚手架:只需替换业务模块(workbench),即可复刻整套托盘常驻、回环安全防线与桌面人工审批基建。

核心能力

1. 内嵌 Streamable HTTP MCP 服务端

基于 Rust rmcp 与 axum 在应用进程内原生承载 Streamable HTTP 协议(默认监听 http://127.0.0.1:19527/mcp 并提供 /healthz 健康探针),支持通过 KEELDESK_MCP_PORT 自定义端口,一行命令即可接入 Claude Code CLI 或写入 Cursor 的 mcp.json。

2. 单实例守护与系统托盘常驻

集成 tauri-plugin-single-instance,重复启动时自动唤醒并聚焦已有主窗口;点击关闭按钮默认最小化隐藏至系统托盘,保持后台 MCP 服务持续在线,仅在托盘菜单选择 Quit 时优雅释放端口。

3. 高危工具人工审批闭环

工具权限严格划分为 Safe(只读直通)与 ConfirmRequired(桌面人工审批)。当外部 AI 客户端请求终止占用端口的进程时,异步挂起 MCP 调用并在桌面弹出确认卡片,超时未批自动拒绝。

4. 本机环境巡检与活跃端口治理

并发探测 Git、Node.js、pnpm、Rust/Cargo、Python 等本机开发工具链版本与可执行路径状态;实时枚举本机监听中的 TCP 开发端口与关联 PID,支持工作台一键释放或由 AI 发起受控清理。

架构:严格单向分层的“龙骨”边界

为了让底座能力与具体业务彻底解耦,KeelDesk 在前后端同时执行单向依赖法则:业务层(src-tauri/src/workbench 与 src/App.tsx)单向调用底座层(src-tauri/src/keel_core 与 src/keel-sdk),底座层对具体业务模型保持零反向引用。

前后端跨语言通信通过 tauri-specta 自动从 Rust 结构体与 Command 签名生成强类型 TypeScript 绑定(src/bindings.ts),从编译期消除手写 IPC 参数与载荷类型漂移。

设计选择 带来的价值 安全与工程边界
底座与业务单向隔离 替换 workbench 即可复用整套桌面 MCP 宿主底座 keel_core 与 keel-sdk 严禁反向引用业务模块
Loopback + Header 白名单 防止局域网暴露与浏览器 DNS Rebinding 探测 仅监听 127.0.0.1,严格校验 Host 与 Origin
Safe / ConfirmRequired 分级 只读探针零摩擦响应,破坏性操作强制人工把关 审批挂起超时后自动拒绝,不会静默放行高危指令
内置 keel_ping 回环自检 无需外部 AI 客户端即可在桌面端验证协议与链路 使用 Windows 原生 SChannel TLS 栈发起真实 HTTP 握手

安全防线与高危操作人工审批流

将本地系统能力暴露给 HTTP 接口与大模型客户端时,安全边界是首要设计约束。KeelDesk 从网络层到执行层构建了三道防线:

  1. 回环地址锁定与防 DNS Rebinding 校验:MCP HTTP 服务端硬性绑定 127.0.0.1 回环网卡,拒绝局域网或公网直连;中间件对每个请求的 Host 与 Origin 请求头执行严格白名单校验。
  2. 端到端回环自检(keel_ping):内置基于 reqwest(Windows 原生 SChannel TLS)的真实 HTTP 客户端,可在桌面端一键向自身 /mcp 端点发起端到端握手演练,同时支持在 UI 内直接触发高危审批干跑演练(Dry Run)。
  3. 基于 oneshot 通道的异步挂起与桌面审批:当 AI 客户端调用 kill_port_process(标记为 ConfirmRequired)时,keel_core 创建 tokio::sync::oneshot 通道挂起当前请求,并通过 Tauri 事件总线唤醒桌面审批队列。只有用户在桌面点击“批准”后,系统才执行进程终止并将结果原路返回给 AI。

Windows 11 原生桌面打磨

  • 沉浸式深色标题栏与 Snap Layouts:通过 Win32 DWM API 显式开启 DWMWA_USE_IMMERSIVE_DARK_MODE,同时保留系统原生窗口样式(WS_THICKFRAME | WS_CAPTION | WS_MAXIMIZEBOX),支持鼠标悬停最大化按钮触发 Windows 11 原生分屏布局(Snap Layouts)。
  • 两段式零白屏启动:窗口创建时默认隐藏(visible: false),配合内联深色启动骨架屏与后台预扫描任务,首帧渲染就绪后再平滑呈现主窗口。
  • 100dvh 视口锁定与局部滚动:全屏工作台采用紧凑的双栏仪表盘布局,整页零滚动条,仅在端口列表与实时 MCP 遥测日志区域按需局部滚动。

快速开始、客户端接入命令及二开指南可查看 KeelDesk GitHub 仓库。

有问题或想法?

无论是讨论技术实现,还是交流项目思路,都可以给我留言。