OculOS MCP 服务器

关键词

桌面自动化UI 自动化本地服务JSON-RPCAI 集成

使用说明（Markdown 格式）

  • 项目简介

    • 该仓库实现了一个可运行的 MCP 服务器，用于与 MCP 客户端（如 Claude Code、Cursor、Windsurf 等）通过 JSON-RPC 2.0 的 stdin/stdout 通道进行通信。服务器暴露工具目录、对工具的调用以及对桌面 UI 的交互能力，便于 AI 客户端在本地桌面环境中执行自动化任务。

  • 主要功能点

    • MCP 核心接口支持：
      • initialize：告知客户端协议版本、能力、服务器信息。
      • tools/list：提供可用工具的目录与输入输出模式。
      • tools/call：根据名称调用具体工具，并返回文本结果或其他内容。
    • 支持将桌面 UI 自动化能力封装为 MCP 工具，并通过后端平台抽象（UiBackend）执行。
    • 行为描述遵循 JSON-RPC 2.0，响应包含 jsonrpc、id、result 或 error。
    • 运行模式与接入点
      • 可通过 --mcp 启动，使用标准输入/输出与 MCP 客户端对接。
      • 服务器信息包含名称、版本等，便于客户端在初始阶段对接与能力对齐。

  • 安装步骤

    • 环境准备：确保已安装 Rust 与 Cargo。
    • 构建并运行（Release 版本推荐）：
      • cargo build --release
      • 运行命令：./target/release/oculos --mcp
    • 运行后，MCP 客户端应通过 stdin/stdout 与之建立连接，按照 MCP 约定进行后续交互。

  • 服务器配置（MCP 客户端使用信息，非客户端代码）

    • MCP 客户端在其主机配置中需要指向该 MCP 服务器的启动命令与参数，以便在需要时能够启动并与之通信。以下配置示例用于 MCP 客户端的主机配置（仅供参考，客户端无需额外代码）：
    • 配置示例（JSON，包含服务器名称、启动命令与参数）： { "mcpServers": { "oculos": { "command": "/path/to/oculos", "args": ["--mcp"] } } } 说明：
    • server name 为 oculos，command 指向编译产物的执行路径，args 指定启动 MCP 模式所需参数。该配置用于 MCP 客户端在启动时自动启动并连接到本 MCP 服务器。客户端本身不需要使用该配置进行业务逻辑实现，仅用于连接初始化。

  • 基本使用方法

    • 启动后客户端与服务器之间通过 JSON-RPC 2.0 的换行分隔文本进行通信。典型流程：
      • 客户端发送 initialize 请求，服务器返回协议版本、能力、服务器信息。
      • 客户端请求 tools/list，获取可用工具的描述和输入输出结构。
      • 客户端通过 tools/call 调用具体工具（如 list_windows、get_ui_tree、find_elements 等），并获得文本或结构化数据作为输出，后续可在对话中驱动更多操作。
    • 常见交互要点：
      • tool/call 的响应通常包含文本或 JSON 数据，用于后续 AI 决策。
      • 客户端需妥善管理会话与能力声明，确保遵循 MCP 规范的请求格式与错误处理。
    • 诊断与调试：
      • 若客户端无法正确解析响应，请检查换行分隔的单行 JSON 是否符合 MCP-RPC 的格式要求。
      • 确认服务器在 --mcp 模式下持续运行，且 STDIN/STDOUT 未被其他进程抢占。

服务器信息

访问项目