OmniMCP

OmniMCP 通过模型上下文协议 (MCP)和microsoft/OmniParser为 AI 模型提供丰富的 UI 上下文和交互能力，专注于通过可视化分析、结构化规划和精准交互执行，实现对用户界面的深度理解。

核心功能

• **视觉感知：**使用 OmniParser 理解 UI 元素。
• **LLM 规划：**根据目标、历史和视觉状态规划下一步行动。
• **代理执行器：**协调感知-计划-行动循环（ omnimcp/agent_executor.py ）。
• **动作执行：**通过pynput ( omnimcp/input.py ) 控制鼠标/键盘。
• **CLI 接口：**运行任务的简单入口点（ cli.py ）。
• **自动部署：**可选将 OmniParser 服务器部署到 AWS EC2 并自动关闭。
• **调试：**每一步生成带有时间戳的可视日志。

概述

cli.py使用AgentExecutor运行感知-计划-执行循环。它捕获屏幕（ VisualState ），使用 LLM（ core.plan_action_for_ui ）进行规划，并执行操作（ InputController ）。

演示

• 实际动作（计算器）： python cli.py打开计算器，计算 5*9。
• 合成 UI（登录）： python demo_synthetic.py使用生成的图像（无实际 I/O）。 （注：待重构以使用 AgentExecutor）。

先决条件

• Python >=3.10，<3.13
• uv安装（ pip install uv ）
• Linux 运行时要求： pynput需要一个活动的图形会话 (X11/Wayland)。可能需要系统库（ libx11-dev等）——请参阅pynput文档。

（macOS 显示缩放依赖关系在安装期间自动处理）。

对于 AWS 部署功能

需要在.env中提供 AWS 凭证（参见.env.example ）。**警告：**创建 AWS 资源（EC2、Lambda 等）会产生费用。请使用python -m omnimcp.omniparser.server stop进行清理。

安装

快速入门

确保环境已激活并且.env已配置。

调试输出保存在runs/<timestamp>/中。

**关于 MCP 服务器的说明：**存在一个实验性的 MCP 服务器（ omnimcp/mcp_server.py中的OmniMCP类），但与主要的cli.py / AgentExecutor工作流程是分开的。

建筑学

1. CLI （ cli.py ）——入口点，设置，启动执行器。
2. 代理执行器（ omnimcp/agent_executor.py ）——协调循环，管理状态/工件。
3. 视觉状态管理器（ omnimcp/visual_state.py ） - 感知（屏幕截图，调用解析器）。
4. OmniParser 客户端和部署（ omnimcp/omniparser/ ） - 管理 OmniParser 服务器通信/部署。
5. LLM 规划器（ omnimcp/core.py ）——生成行动计划。
6. 输入控制器（ omnimcp/input.py ） - 执行操作（鼠标/键盘）。
7. （可选）MCP 服务器（ omnimcp/mcp_server.py ） - 实验性 MCP 接口。

发展

环境设置和检查

调试支持

运行python cli.py会将带有时间戳的运行保存在runs/中，包括：

• step_N_state_raw.png
• step_N_state_parsed.png （带元素框）
• step_N_action_highlight.png （带有动作突出显示）
• final_state.png

详细日志位于logs/run_YYYY-MM-DD_HH-mm-ss.log中（建议在.env中使用LOG_LEVEL=DEBUG ）。

（注意：时间、数量、IP、实例 ID 和具体计划等详细信息会有所不同）

路线图和局限性

主要限制和未来工作领域：

• **性能：**减少 OmniParser 延迟（探索本地模型、缓存等）并优化状态管理（避免完全重新解析）。
• **稳健性：**提高 LLM 规划可靠性（提示、ReAct 等技术），添加动作验证/错误恢复，增强元素定位。
• **目标 API/架构：**向更高级别的声明式 API 发展（例如， @omni.publish样式），并可能将循环逻辑与实验性 MCP 服务器（ OmniMCP类）集成。
• **一致性：**重构demo_synthetic.py以使用AgentExecutor 。
• **特点：**扩展操作空间（拖放、悬停）。
• **测试：**添加 E2E 测试，扩大跨平台验证，定义评估指标。
• **研究：**探索微调、流程图（RAG）、框架集成。

项目状态

通过cli.py / AgentExecutor核心循环可以完成基本任务。性能和稳健性需要显著改进。MCP 集成尚处于实验阶段。

贡献

1. Fork 存储库
2. 创建功能分支
3. 实施变更并添加测试
4. 确保检查通过（ uv run ruff format . , uv run ruff check . --fix , uv run pytest tests/ ）
5. 提交拉取请求

执照

MIT 许可证

接触

• 问题： GitHub 问题
• 问题：讨论
• 安全： security@openadapt.ai