Ui Controller MCP

ui控制器mcp

一个轻量级的模型上下文协议（MCP）服务器 FastMCP 它通过服务器发送事件（SSE）公开桌面UI控制工具。它为远程访问提供了结构化的工具定义、JSON模式契约和可选的ngrok隧道。

特性

• MCP兼容的SSE流媒体 /sse 使用工具元数据和心跳。
• 工具执行通过 /invoke 具有一致的JSON成功/错误信封。
• 桌面自动化抽象为可互换的控制器（PyAutoGUI在可用时支持，否则不安全）。
• 请求/响应日志记录和针对破坏性命令的安全防护。
• 支持ngrok，可用于本地和远程使用。

入门

先决条件

• Python 3.12+
• 可选： ngrok 远程隧道的auth令牌（创建 .env 文件使用 .env.example).

安装

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

在本地运行

./start.sh

访问 http://localhost:8000/health 确认服务器已启动。

使用ngrok（远程）运行

cp .env.example .env
# add your NGROK_AUTH_TOKEN to .env
./start-remote.sh

启动时，一旦隧道建立，服务器就会打印公共ngrok URL。

API概述

• GET /sse：发出以下信号的SSE流 ready 带有工具模式的事件，后面是定期事件 ping 事件。
• POST /messages：由FastMCP处理的MCP消息传输，用于工具调用。
• GET /health：轻量级健康检查。

SSE握手示例

连接到 GET /sse 并期待类似于以下情况的初始事件：

event: ready
data: {"protocol": "mcp/1.0", "server": {"name": "ui-controller-mcp", "version": "0.1.0"}, "tools": [...], "timestamp": "..."}

紧随其后 ping 每10秒发生一次事件。

项目结构

ui_controller_mcp/
├── desktop/        # UI automation controllers
├── routes/         # FastAPI route handlers (/sse, /invoke)
├── server/         # FastAPI app factory and ngrok integration
├── tools/          # Tool schemas and execution dispatcher
└── utils/          # Logging and safety helpers

测试

pytest

安全与安保

• 安全防护装置拒绝明显具有破坏性的发射命令和文本输入。
• 日志中间件记录入站请求和响应以实现可观察性。
• 没有操作控制器可以确保在没有桌面UI的环境中安全执行。