OmniMCP

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

核心功能

• 视觉感知： 使用 OmniParser 理解 UI 元素。
• LLM 规划： 基于目标、历史记录和视觉状态规划下一步行动。
• Agent Executor： 编排感知-计划-行动循环 (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://... # 可选：跳过自动部署

安装

git clone [https://github.com/OpenAdaptAI/OmniMCP.git](https://github.com/OpenAdaptAI/OmniMCP.git)
cd OmniMCP
./install.sh # 创建 .venv，安装依赖项，包括测试所需的额外依赖
cp .env.example .env
# 使用您的密钥编辑 .env
# 激活：source .venv/bin/activate (Linux/macOS) 或相关的 Windows 命令

快速开始

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

# 运行默认目标（计算器任务）
python cli.py

# 运行自定义目标
python cli.py --goal "您的目标"

# 查看选项
python cli.py --help

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

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

架构

1. CLI (cli.py) - 入口点，设置，启动 Executor。
2. Agent Executor (omnimcp/agent_executor.py) - 编排循环，管理状态/工件。
3. Visual State Manager (omnimcp/visual_state.py) - 感知（屏幕截图，调用解析器）。
4. OmniParser Client & Deploy (omnimcp/omniparser/) - 管理 OmniParser 服务器通信/部署。
5. LLM Planner (omnimcp/core.py) - 生成行动计划。
6. Input Controller (omnimcp/input.py) - 执行行动（鼠标/键盘）。
7. （可选）MCP 服务器 (omnimcp/mcp_server.py) - 实验性的 MCP 接口。

开发

环境设置和检查

# 设置（如果尚未完成）：./install.sh
# 激活环境：source .venv/bin/activate (或类似命令)
# 格式化/Lint：uv run ruff format . && uv run ruff check . --fix
# 运行测试：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）。

<details> <summary>示例日志片段（自动部署 + Agent 步骤）</summary>

# --- 初始化 & 自动部署 ---
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 执行循环示例步骤 ---
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 和具体计划等详细信息会有所不同） </details>

路线图和局限性

主要局限性和未来工作领域：

• 性能： 降低 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. 提交 pull request

许可证

MIT 许可证

联系方式

• 问题：GitHub Issues
• 疑问：Discussions
• 安全：security@openadapt.ai