MCP 服务器

GoScry

GoScry 是一个用 Go 编写的服务器应用程序，它充当控制系统（例如 LLM 或脚本）和 Web 浏览器之间的桥梁。

copyleftdev

开发者工具

访问服务器

README

GoScry

GoScry 是一个用 Go 编写的服务器应用程序，它充当控制系统（如 LLM 或脚本）和 Web 浏览器之间的桥梁。它使用 Chrome DevTools 协议 (CDP) 与基于通过其 API 提交的任务的网站进行交互。 GoScry 可以执行导航、点击、输入、处理身份验证（带有 2FA 的钩子）以及提取 DOM 内容等操作。结果和状态更新可以通过使用模型上下文协议 (MCP) 格式的 Webhook 报告回来。

特性

远程浏览器控制： 使用 CDP（通过 chromedp）来控制无头或有头的 Chrome/Chromium 实例。
基于任务的 API： 通过简单的 JSON API 提交浏览器操作序列（导航、点击、输入、等待、获取 DOM、屏幕截图等）。
身份验证处理： 支持任务中的基本用户名/密码登录序列。
2FA 支持（手动钩子）： 检测潜在的 2FA 提示，并通过 API/回调发回信号，允许外部系统或用户提供代码以继续任务。
DOM 提取： 检索完整的 HTML、文本内容或 DOM 的简化版本。
DOM AST： 生成 DOM 的结构化抽象语法树表示，并具有可选的作用域控制。
MCP 输出： 根据模型上下文协议（规范 2025-03-26）格式化异步结果/状态更新（例如，通过回调），以实现清晰、结构化的上下文报告。
可配置： 通过 YAML 文件或环境变量管理服务器端口、浏览器设置、日志记录和安全性。

架构图

sequenceDiagram
    participant Client as LLM 系统 / API 客户端
    participant GS as GoScry 服务器 (API)
    participant TM as 任务管理器
    participant BM as 浏览器管理器
    participant DOM as DOM 处理器
    participant CDP as Chrome (通过 CDP)
    participant Site as 目标网站

    Client->>+GS: POST /api/v1/tasks (任务 JSON)
    GS->>+TM: SubmitTask(task)
    TM-->>GS: TaskID
    GS-->>-Client: 202 Accepted (TaskID)
    Note right of TM: 任务执行异步开始
    TM->>BM: ExecuteActions(actions)
    BM->>+CDP: 运行 CDP 命令 (导航, 点击, 等.)
    CDP->>+Site: HTTP 请求
    Site-->>-CDP: HTTP 响应 (HTML, 等.)
    CDP-->>-BM: 操作结果 / DOM 状态
    BM-->>TM: 操作完成 / 错误

    alt DOM AST 检索
        Client->>+GS: POST /api/v1/dom/ast (URL, ParentSelector)
        GS->>+DOM: GetDomAST(URL, ParentSelector)
        DOM->>+CDP: ChromeDP 操作 (导航, GetHTML)
        CDP->>+Site: HTTP 请求
        Site-->>-CDP: HTTP 响应 (HTML)
        CDP-->>-DOM: HTML 内容
        DOM-->>-GS: DOM AST 结构
        GS-->>-Client: 200 OK (AST JSON)
    end

    alt 需要 2FA (例如, 登录操作后)
        TM->>BM: ExecuteAction(detect2FAPrompt)
        BM->>CDP: 检查页面状态以查找 2FA 指示器
        CDP->>BM: 存在结果
        BM->>TM: 检测到/未检测到提示
        opt 检测到提示
            TM->>TM: 更新任务状态 (WaitingFor2FA)
            TM-->>Client: 通知回调 (MCP 2FA 请求)
            Note over Client, TM: 客户端从外部检索代码
            Client->>+GS: POST /api/v1/tasks/{id}/2fa (代码)
            GS->>+TM: Provide2FACode(id, code)
            TM->>TM: 信号/恢复任务执行
            Note right of TM: 下一个操作键入 2FA 代码
            TM->>BM: ExecuteActions(键入 2FA 代码, 提交)
            BM->>+CDP: 键入代码, 提交
            CDP->>+Site: 验证 2FA
            Site-->>-CDP: 登录成功/失败
            CDP-->>-BM: 结果
            BM-->>TM: 操作完成
        end
    end
    TM->>TM: 处理最终结果 / 格式化 MCP
    TM-->>Client: 通知回调 (MCP 结果/状态)
    TM->>TM: 更新任务状态 (已完成/失败)
    Note over TM: 任务执行完成.

包结构

cmd/goscry： 主应用程序入口点
internal/taskstypes： 跨包共享的核心数据类型
internal/tasks： 任务管理和执行
internal/browser： 浏览器控制和 CDP 交互
internal/server： HTTP API 处理程序
internal/config： 配置处理
internal/dom： DOM 处理实用程序

前提条件

Go： 1.21 或更高版本。
Chrome / Chromium： 在运行 GoScry 的系统上安装的兼容版本。确保浏览器可执行文件位于系统 PATH 中，或在配置中提供路径。

安装

克隆存储库：

git clone [https://github.com/copyleftdev/goscry.git](https://github.com/copyleftdev/goscry.git)
cd goscry

构建可执行文件：
```
go build -o goscry ./cmd/goscry/
```
这将在项目根目录中创建 goscry 二进制文件。
或者，从 releases page 下载预构建的二进制文件。

Docker 部署

GoScry 可以使用 Docker 和 Docker Compose 轻松部署，并提供多种部署选项。

使用 Docker 快速入门

克隆存储库：

git clone [https://github.com/copyleftdev/goscry.git](https://github.com/copyleftdev/goscry.git)
cd goscry

启动容器：
```
docker compose up -d
```
通过 http://localhost:8090 访问 API

部署选项

GoScry 提供了几个预配置的部署配置文件：

基本部署 - 仅 GoScry 服务：
```
docker compose up -d
```
生产部署 - 包括带有 TLS 终止的 Traefik 反向代理：
```
docker compose --profile production up -d
```
监控部署 - 添加 Prometheus 和 Grafana 以实现可观察性：
```
docker compose --profile monitoring up -d
```

Docker 配置

环境变量：使用环境变量配置服务：
- GOSCRY_API_KEY：用于身份验证的 API 密钥
- LOG_LEVEL：日志记录级别（debug、info、warn、error）
- AUTO_GENERATE_API_KEY：自动生成安全的 API 密钥
卷：Docker 设置包括以下持久卷：
- 配置数据
- Prometheus 指标（使用监控配置文件时）
- Grafana 仪表板（使用监控配置文件时）

有关详细的 Docker 部署说明，请参阅 DOCKER.md。

持续集成和部署

GoScry 使用 GitHub Actions 进行 CI/CD：

每次推送到 main 和拉取请求时进行自动化测试
自动构建 Linux、macOS（Intel 和 ARM）和 Windows 的二进制文件
推送版本标签时自动发布（例如，v1.0.0）

有关发布过程的详细信息，请参阅 RELEASING.md。

配置

GoScry 通过 config.yaml 文件或环境变量进行配置。

复制示例配置：
```
cp config.example.yaml config.yaml
```
编辑 config.yaml 以适合您的环境：
- server.port：API 服务器侦听的端口。
- browser.executablePath：Chrome/Chromium 可执行文件的绝对路径（留空以尝试自动检测）。
- browser.headless：true 以无头模式运行，false 以有头模式运行。
- browser.userDataDir：持久用户配置文件目录的路径（可选，如果为空则创建临时配置文件）。
- browser.maxSessions：最大并发浏览器实例数。
- log.level：日志记录级别（debug、info、warn、error）。
- security.allowedOrigins：允许 CORS 请求的来源列表。在生产中使用特定域而不是 *。
- security.apiKey：API 访问所需的密钥（通过 GOSCRY_SECURITY_APIKEY 环境变量设置以获得更好的安全性）。

环境变量会覆盖文件设置。它们以 GOSCRY_ 为前缀，并使用下划线代替点（例如，GOSCRY_SERVER_PORT=9090，GOSCRY_SECURITY_APIKEY=your-secret-key）。

运行服务器

./goscry -config config.yaml

或者，如果主要使用环境变量：

export GOSCRY_SECURITY_APIKEY="your-secret-key"
# export GOSCRY_BROWSER_EXECUTABLEPATH="/path/to/chrome" # Optional
./goscry

服务器将启动并将输出记录到控制台，具体取决于配置的日志级别。

API 用法

API 在配置的端口（默认为 8080）上的 /api/v1 路径前缀下侦听。如果设置了 security.apiKey，则需要通过 X-API-Key 或 Authorization: Bearer <key> 标头进行身份验证。

端点

POST /api/v1/tasks: 提交新的浏览器任务。
- 请求正文： SubmitTaskRequest JSON（参见 internal/server/handlers.go）。包括 actions、可选的 credentials、two_factor_auth 信息和 callback_url。
- 响应（成功）： 202 Accepted，带有包含 task_id 的 SubmitTaskResponse JSON。
- 响应（错误）： 400 Bad Request、401 Unauthorized、403 Forbidden、500 Internal Server Error。
GET /api/v1/tasks/{taskID}: 获取任务的当前状态和结果。
- URL 参数： taskID (UUID 字符串)。
- 响应（成功）： 200 OK，带有 Task JSON（参见 internal/tasks/task.go）。
- 响应（错误）： 400 Bad Request、401 Unauthorized、403 Forbidden、404 Not Found、500 Internal Server Error。
POST /api/v1/tasks/{taskID}/2fa: 为等待 2FA 代码的任务提供 2FA 代码。
- URL 参数： taskID (UUID 字符串)。
- 请求正文： Provide2FACodeRequest JSON（例如，{"code": "123456"}）。
- 响应（成功）： 200 OK，带有简单的成功消息。
- 响应（错误）： 400 Bad Request、401 Unauthorized、403 Forbidden、404 Not Found、409 Conflict（如果任务未等待）、408 Request Timeout（如果任务等待超时）、500 Internal Server Error。
POST /api/v1/dom/ast: 从带有可选父选择器的 URL 获取 DOM 抽象语法树。
- 请求正文： GetDomASTRequest JSON（例如，{"url": "https://example.com", "parent_selector": "div#main"} - parent_selector 是可选的）。
- 响应（成功）： 200 OK，带有表示为嵌套 DomNode 对象的结构化 DOM 树。
- 响应（错误）： 400 Bad Request、401 Unauthorized、403 Forbidden、500 Internal Server Error。

操作类型

提交请求中的 actions 数组定义了步骤：

类型	描述	`selector` 是否使用	`value` 是否使用	`format` 是否使用
`Maps`	将浏览器导航到 URL。	否	URL 字符串	否
`wait_visible`	等待与选择器匹配的元素变为可见。	是	可选持续时间（例如，“5s”，默认为“30s”）	否
`wait_hidden`	等待与选择器匹配的元素变为隐藏。	是	可选持续时间（例如，“5s”，默认为“30s”）	否
`wait_delay`	暂停执行指定的持续时间。	否	持续时间字符串（例如，“2s”，“500ms”）	否
`click`	等待元素可见并单击它。	是	否	否
`type`	将文本键入元素。使用 `{{task.tfa_code}}` 进行 2FA 代码注入。	是	文本字符串，或 `{{task.tfa_code}}`	否
`select`	通过其 value 属性在 `<select>` 元素中选择一个选项。	是	选项 value 字符串	否
`scroll`	滚动页面（`top`，`bottom`）或将元素滚动到视图中。	如果 value 不是 `top`/`bottom`	`top`、`bottom` 或空（使用选择器）	否
`screenshot`	捕获全页屏幕截图。结果附加到任务结果。	否	可选 JPEG 质量（0-100，默认为 90）	`base64` (字符串) 或 `png` (字节)
`get_dom`	检索 DOM 内容。结果附加到任务结果。	可选（默认为 `body`）	否	`full_html`、`simplified_html`、`text_content`
`run_script`	在页面上下文中执行任意 JavaScript。结果附加到任务结果。	否	JavaScript 代码字符串	否

使用 DOM AST API

概述

DOM AST API 提供网页的文档对象模型 (DOM) 的结构化表示，作为抽象语法树。此功能启用：

以编程方式分析页面结构
提取页面的特定部分，并保持其层次关系不变
执行具有作用域控制的定向内容提取

端点

POST /api/v1/dom/ast

请求参数

参数	类型	必需	描述
`url`	string	是	要分析的网页的 URL
`parent_selector`	string	否	CSS 选择器，用于将 AST 的作用域限定为特定元素（例如，`#main-content`，`div.container`）

响应结构

DOM AST 中的每个节点都具有以下结构：

{
  "nodeType": "element",        // "element", "text", "comment", 或 "document"
  "tagName": "div",             // HTML 标签名称（对于元素节点）
  "id": "main",                 // ID 属性（如果存在）
  "classes": ["container"],     // CSS 类数组（如果存在）
  "attributes": {               // 所有属性的映射
    "id": "main",
    "class": "container"
  },
  "textContent": "",            // 文本内容（主要用于文本节点）
  "children": []                // 子节点数组
}

用法示例

请求：

curl -X POST http://localhost:8080/api/v1/dom/ast \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "url": "[https://example.com](https://example.com)",
    "parent_selector": "#main-content"
  }'

响应：

{
  "nodeType": "element",
  "tagName": "div",
  "attributes": {"id": "main-content"},
  "children": [
    {
      "nodeType": "element",
      "tagName": "h1",
      "attributes": {"class": "title"},
      "children": [],
      "textContent": "Welcome to Example.com"
    },
    {
      "nodeType": "element",
      "tagName": "p",
      "attributes": {},
      "children": [],
      "textContent": "This domain is for use in illustrative examples in documents."
    }
  ]
}

实现说明

DOM AST 功能使用 ChromeDP 的选择器支持来实现强大的 CSS 选择器匹配
等待 5 秒钟，以便 JavaScript 繁重的页面在处理之前完全加载
适用于使用 React、Vue 或 Angular 等框架的简单站点和复杂的现代 Web 应用程序
处理各种 CSS 选择器，包括标签、类、ID 和嵌套选择器

贡献

欢迎贡献！请随时提交拉取请求。

许可证

该项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。

GoScry

README

GoScry

特性

架构图

包结构

前提条件

安装

Docker 部署

使用 Docker 快速入门

部署选项

Docker 配置

持续集成和部署

配置

运行服务器

API 用法

端点

操作类型

使用 DOM AST API

概述

端点

请求参数

响应结构

用法示例

实现说明

贡献

许可证

推荐服务器