OmniMCP

OmniMCP 通过 Model Context Protocol (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 运行时要求： 需要一个活跃的图形会话（X11/Wayland）用于 pynput。可能需要系统库（libx11-dev 等）- 请参阅 pynput 文档。

(macOS 显示缩放依赖项在安装过程中自动处理)。

对于 AWS 部署功能

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

AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_KEY
# OMNIPARSER_URL=http://... # Optional: Skip auto-deploy

安装

git clone [https://github.com/OpenAdaptAI/OmniMCP.git](https://github.com/OpenAdaptAI/OmniMCP.git)
cd OmniMCP
./install.sh # Creates .venv, installs deps incl. test extras
cp .env.example .env
# Edit .env with your keys
# Activate: source .venv/bin/activate (Linux/macOS) or relevant Windows command

快速开始

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

# Run default goal (Calculator task)
python cli.py

# Run custom goal
python cli.py --goal "Your goal here"

# See options
python cli.py --help

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

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

架构

1. CLI (cli.py) - 入口点，设置，启动执行器。
2. Agent Executor (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 接口。

开发

环境设置与检查

# Setup (if not done): ./install.sh
# Activate env: source .venv/bin/activate (or similar)
# Format/Lint: uv run ruff format . && uv run ruff check . --fix
# Run tests: uv run pytest tests/

调试支持

运行 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）。

# --- Initialization & Auto-Deploy ---
2025-MM-DD HH:MM:SS | INFO     | omnimcp.omniparser.client:... - No server_url provided, attempting discovery/deployment...
2025-MM-DD HH:MM:SS | INFO     | omnimcp.omniparser.server:... - Creating new EC2 instance...
2025-MM-DD HH:MM:SS | SUCCESS  | omnimcp.omniparser.server:... - Instance i-... is running. Public IP: ...
2025-MM-DD HH:MM:SS | INFO     | omnimcp.omniparser.server:... - Setting up auto-shutdown infrastructure...
2025-MM-DD HH:MM:SS | SUCCESS  | omnimcp.omniparser.server:... - Auto-shutdown infrastructure setup completed...
... (SSH connection, Docker setup) ...
2025-MM-DD HH:MM:SS | SUCCESS  | omnimcp.omniparser.client:... - Auto-deployment successful. Server URL: http://...
... (Agent Executor Init) ...

# --- Agent Execution Loop Example Step ---
2025-MM-DD HH:MM:SS | INFO     | omnimcp.agent_executor:run:... - --- Step N/10 ---
2025-MM-DD HH:MM:SS | DEBUG    | omnimcp.agent_executor:run:... - Perceiving current screen state...
2025-MM-DD HH:MM:SS | INFO     | omnimcp.visual_state:update:... - VisualState update complete. Found X elements. Took Y.YYs.
2025-MM-DD HH:MM:SS | INFO     | omnimcp.agent_executor:run:... - Perceived state with X elements.
... (Save artifacts) ...
2025-MM-DD HH:MM:SS | DEBUG    | omnimcp.agent_executor:run:... - Planning next action...
... (LLM Call) ...
2025-MM-DD HH:MM:SS | INFO     | omnimcp.agent_executor:run:... - LLM Plan: Action=..., TargetID=..., GoalComplete=False
2025-MM-DD HH:MM:SS | DEBUG    | omnimcp.agent_executor:run:... - Added to history: Step N: Planned action ...
2025-MM-DD HH:MM:SS | INFO     | omnimcp.agent_executor:run:... - Executing action: ...
2025-MM-DD HH:MM:SS | SUCCESS  | omnimcp.agent_executor:run:... - Action executed successfully.
2025-MM-DD HH:MM:SS | DEBUG    | omnimcp.agent_executor:run:... - Step N duration: Z.ZZs
... (Loop continues or finishes) ...

（注意：如时间、计数、IP 地址、实例 ID 和具体计划等细节会有所不同）

道路图与限制

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

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

项目状态

通过 cli.py/AgentExecutor 实现的核心循环对于基本任务是可用的。性能和健壮性需要显著改进。MCP 集成是实验性的。

贡献

1. 分叉仓库
2. 创建特性分支
3. 实现更改并添加测试
4. 确保检查通过 (uv run ruff format ., uv run ruff check . --fix, uv run pytest tests/)
5. 提交拉取请求

许可证

MIT 许可证

联系方式

• 问题: GitHub Issues
• 询问: 讨论
• 安全: security@openadapt.ai