使用说明

项目简介

mcp-operator 是一个实现了 Model Context Protocol (MCP) 的服务器，它扩展了大型语言模型（LLM）的能力，使其能够与 Chrome 浏览器进行交互。通过提供资源管理、Prompt 模板和工具注册等功能，该服务器允许 LLM 客户端以标准化的方式访问浏览器功能，实现网页浏览、信息检索和自动化操作。

主要功能点

资源管理 (Resources):
- 提供简单的笔记存储系统，可以通过 'note://' URI 访问和管理笔记资源。
- 每个笔记资源包含名称、描述和文本内容。
Prompt 模板 (Prompts):
- 提供 'summarize-notes' Prompt，用于生成所有存储笔记的摘要，并支持通过可选参数 'style' 控制摘要的详细程度（'brief' 或 'detailed'）。
工具 (Tools):
- 笔记管理工具: 'add-note' 工具允许客户端向服务器添加新的笔记。
- 浏览器自动化工具:
  - 'create-browser': 创建一个新的 Chrome 浏览器实例，支持通过 'project_name' 实现浏览器状态的持久化。
  - 'navigate-browser': 在指定的浏览器实例中导航到指定的 URL。
  - 'operate-browser': 基于自然语言指令操作浏览器，例如点击、输入、滚动等，利用 OpenAI 的 Computer Use API 解析指令并执行浏览器操作。支持多步骤操作和卡顿检测与恢复。
  - 'close-browser': 关闭指定的浏览器实例。
- 任务管理工具:
  - 'get-job-status': 查询浏览器操作任务的状态，包括状态、创建时间以及结果（完成时包含截图）。
  - 'list-jobs': 列出最近的浏览器操作任务，支持限制返回的任务数量。
异步工作流: 浏览器自动化工具采用异步任务模式，避免客户端超时，通过 'job_id' 跟踪任务进度和获取结果。
持久化浏览器状态: 通过 'project_name' 创建浏览器时，支持浏览器状态（cookies, storage等）的持久化，允许跨会话保持登录状态和工作流程。

安装步骤

环境准备:
- 确保已安装 Python 3.11 或更高版本。
- 安装 Playwright 浏览器自动化库。
- 拥有 OpenAI API 密钥，并已开通 Computer Use API 的访问权限。

安装依赖:

pip install mcp-operator
playwright install chromium

配置环境变量:

创建 '.env' 文件或设置环境变量，配置 OpenAI API 密钥：

OPENAI_API_KEY=your-api-key-here
# 可选: 如果有组织ID
# OPENAI_ORG=your-org-id

服务器配置

MCP 客户端需要配置 MCP 服务器的启动命令和参数才能连接。以下是针对不同部署方式的服务器配置信息，请根据实际情况选择：

Claude Desktop 客户端配置 (Development/Unpublished Servers Configuration 示例):

{
  "mcpServers": {
    "mcp-operator": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-operator",  //  请替换为 mcp-operator 仓库的实际路径
        "run",
        "mcp-operator"
      ]
    }
  }
}

'server name': 'mcp-operator' (服务器名称，客户端配置中引用)
'command': 'uv' (启动命令，这里假设使用 'uv' 运行 Python 应用)
'args': 启动参数列表
- '--directory': '/path/to/mcp-operator' (指向 'mcp-operator' 仓库根目录的路径，请务必替换为实际路径)
- 'run': 子命令，表示运行 Python 模块
- 'mcp-operator': 要运行的 Python 模块名称

注意:

路径替换: '/path/to/mcp-operator' 必须替换为 'mcp-operator' 仓库在您本地文件系统中的绝对路径。
uv: 示例配置使用 'uv' 作为 Python 包和虚拟环境管理器来运行服务器。您可以根据您的 Python 环境和偏好调整命令和参数。例如，如果直接使用 'python' 命令，可以将 'command' 设置为 'python'，并将 'args' 调整为 '["-m", "mcp_operator.server"]'。
Published Servers Configuration: 仓库也提供了 Published Servers Configuration 的示例，适用于已发布和打包的服务器，通常命令和参数会更简洁，例如：

{
  "mcpServers": {
    "mcp-operator": {
      "command": "uvx",
      "args": [
        "mcp-operator"
      ]
    }
  }
}

请根据您的部署环境和 MCP 客户端的要求，选择合适的配置方式。

基本使用方法

启动 MCP 服务器: 根据上述服务器配置，启动 mcp-operator 服务器。
配置 MCP 客户端: 在 MCP 客户端（例如 Claude Desktop）中，配置连接到 mcp-operator 服务器，填入正确的服务器名称和启动命令参数。
使用 LLM 客户端: 在 LLM 客户端中，可以通过调用注册的工具（如 'operate-browser'、'add-note' 等）来利用服务器提供的功能。例如，可以指示 LLM 客户端调用 'operate-browser' 工具并提供自然语言指令，让浏览器执行相应的操作。
异步任务管理: 对于浏览器自动化工具，工具调用会返回 'job_id'。可以使用 'get-job-status' 工具和 'job_id' 查询任务状态和结果。

关键词