AI导哈

浏览器自动化服务

一个基于Model Context Protocol (MCP)的服务器，包装了steel-dev API，用于通过浏览器自动化访问网站，支持无状态和有状态的交互模式。

  • by jhstatewide
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 jhstatewide/mcp-server-steel-scraper

使用说明

MCP服务器刮钢机

一个简单的模型上下文协议（MCP）服务器，它包装了steel-dev API，用于访问具有浏览器自动化功能的网站。

快速开始

  1. 安装软件包：

    npm install -g @jharding_npm/mcp-server-steel-scraper

  2. 添加到MCP客户端配置中：

    {
  "mcpServers": {
    "steel-scraper": {
      "command": "npx",
     "args": ["@jharding_npm/mcp-server-steel-scraper", "--mode=both"],
     "env": {
       "STEEL_API_URL": "http://localhost:3000"
     }
   }
 }

}


3. **Start using the stateless `visit_with_browser` tool, or the stateful interactive tools.**

## Features

- **Dual Modes**: Run stateless scraping, stateful interaction, or both via `--mode=stateless|stateful|both` (default: `both`)
- **Stateless Tool**: `visit_with_browser` - Visit websites using steel-dev API
- **Stateful Tools**: Create sessions and interact with pages (navigate, click, type, scroll, snapshot)
- **Flexible Return Types**: HTML, markdown, readability, or cleaned HTML
- **Local/Remote Support**: Works with local or remote steel-dev instances
- **Browser Automation**: Screenshot capture, PDF generation, proxy support
- **Smart Length Management**: Single `maxLength` parameter with intelligent defaults and automatic content/metadata split
- **Clean Output by Default**: Minimal metadata output perfect for 7B models and summarization
- **Verbose Mode**: Optional full metadata when detailed information is needed
- **TypeScript**: Fully typed implementation

## Installation

### Option 1: NPM Package (Recommended)

Install the package globally to use it with npx:

```bash
npm install -g @jharding_npm/mcp-server-steel-scraper

或者直接与npx一起使用，而无需安装：

npx @jharding_npm/mcp-server-steel-scraper

方案2：地方发展

  1. 克隆此存储库：
git clone <repository-url>
cd mcp-server-steel-scraper
  1. 安装依赖项：
npm install
  1. 构建项目：
npm run build

配置

服务器使用环境变量进行配置：

  • STEEL_API_URL：钢铁与API的端点（默认值： http://localhost:3000)
  • STEEL_TIMEOUT：请求超时（毫秒）（默认值： 30000)
  • STEEL_RETRIES：重试尝试次数（默认值： 3)
  • STEEL_LOCAL：设置为 true 当使用本地Steel实例进行有状态会话时
  • STEEL_BASE_URL：Steel Sessions API的基本URL（默认值： https://api.steel.dev，或 http://localhost:3000 当 STEEL_LOCAL=true)
  • STEEL_API_KEY：云模式有状态会话需要
  • STEEL_SESSION_TIMEOUT_MS：会话超时（毫秒）（默认值： 900000)
  • STEEL_GLOBAL_WAIT_SECONDS：每个有状态操作后的可选延迟（默认值： 0)
  • STEEL_IDLE_TIMEOUT_MS：在此毫秒后自动释放空闲会话（默认值： 600000，设置为 0 禁用）

复制 env.example 到 .env 并根据需要进行修改：

cp env.example .env

用法

运行服务器

# Development mode
npm run dev

# Auto-rebuild on changes (recommended for npm link workflows)
npm run build:watch

# Production mode
npm start

# Only stateless scraping tools
npm start -- --mode=stateless

# Only stateful interactive tools
npm start -- --mode=stateful

# Both tool sets (default)
npm start -- --mode=both

MCP客户端配置

将此服务器添加到MCP客户端配置中。以下是受欢迎的LLM客户的示例：

适用于Claude Desktop/Cline/其他MCP客户端（NPM包）

{
  "mcpServers": {
    "steel-scraper": {
      "command": "npx",
      "args": ["@jharding_npm/mcp-server-steel-scraper", "--mode=stateless"],
      "env": {
        "STEEL_API_URL": "http://localhost:3000"
      }
    }
  }
}

要公开有状态的交互工具，请添加 --mode=stateful 或 --mode=both 到 args 阵列。

用于Continue.dev（NPM包）

{
  "mcpServers": {
    "steel-scraper": {
      "command": "npx",
      "args": ["@jharding_npm/mcp-server-steel-scraper", "--mode=stateless"],
      "env": {
        "STEEL_API_URL": "http://localhost:3000"
      }
    }
  }
}

适用于Cursor IDE（NPM包）

{
  "mcpServers": {
    "steel-scraper": {
      "command": "npx",
      "args": ["@jharding_npm/mcp-server-steel-scraper", "--mode=stateless"],
      "env": {
        "STEEL_API_URL": "http://localhost:3000"
      }
    }
  }
}

用于远程Steel开发实例（NPM包）

{
  "mcpServers": {
    "steel-scraper": {
      "command": "npx",
      "args": ["@jharding_npm/mcp-server-steel-scraper", "--mode=stateless"],
      "env": {
        "STEEL_API_URL": "https://your-steel-dev-instance.com"
      }
    }
  }
}

替代方案：使用全局安装

如果您已使用全局安装了该软件包 npm install -g @jharding_npm/mcp-server-steel-scraper，您可以使用：

{
  "mcpServers": {
    "steel-scraper": {
      "command": "mcp-server-steel-scraper",
      "env": {
        "STEEL_API_URL": "http://localhost:3000"
      }
    }
  }
}

地方发展（使用绝对路径）

{
  "mcpServers": {
    "steel-scraper": {
      "command": "node",
      "args": ["/path/to/mcp-server-steel-scraper/dist/index.js"],
      "env": {
        "STEEL_API_URL": "http://localhost:3000"
      }
    }
  }
}

工具使用

服务器提供了一个工具： visit_with_browser

参数

  • url （必填）：要访问的URL
  • format （可选）：要提取的内容格式- ["html"] 对于原始HTML源（可能非常大）， ["markdown"] 对于从HTML转换而来的干净格式化文本（推荐阅读）， ["readability"] 对于Mozilla可读性格式， ["cleaned_html"] 用于清理HTML。您可以请求多种格式（默认： ["markdown"])
  • screenshot （可选）：对页面进行截图（返回base64编码的图像）（默认值： false)
  • pdf （可选）：生成页面的PDF（返回base64编码的PDF）（默认值： false)
  • proxyUrl （可选）：用于请求的代理URL（例如。， "http://proxy:port")
  • delay （可选）：页面加载后抓取前的延迟（默认值： 0)
  • logUrl （可选）：用于调试的日志发送URL
  • maxLength （可选）：返回的最大字符数。智能默认值：markdown=8000，可读性=10000，html=15000，cleaned_html=12000。对于markdown，会自动为元数据保留空间
  • verboseMode （可选）：返回完整的元数据，而不是以内容为中心的干净输出（默认值：false）。当您需要详细的访问信息时使用

示例用法

// Basic website visit
{
  "tool": "visit_with_browser",
  "arguments": {
    "url": "https://example.com"
  }
}

// Advanced visit with multiple formats
{
  "tool": "visit_with_browser",
  "arguments": {
    "url": "https://example.com",
    "format": ["markdown", "html"],
    "screenshot": true,
    "delay": 2
  }
}

// Simple visit with smart defaults (perfect for 7B models)
{
  "tool": "visit_with_browser",
  "arguments": {
    "url": "https://example.com",
    "format": ["markdown"]
  }
}

// Custom length limit (automatically handles content vs metadata split)
{
  "tool": "visit_with_browser",
  "arguments": {
    "url": "https://en.wikipedia.org/wiki/Long_Article",
    "format": ["markdown"],
    "maxLength": 5000
  }
}

// Verbose mode when you need detailed visit information
{
  "tool": "visit_with_browser",
  "arguments": {
    "url": "https://example.com",
    "format": ["markdown"],
    "maxLength": 8000,
    "verboseMode": true
  }
}

// With proxy and PDF generation
{
  "tool": "visit_with_browser",
  "arguments": {
    "url": "https://example.com",
    "format": ["readability"],
    "pdf": true,
    "proxyUrl": "http://proxy:8080"
  }
}

有状态的交互工具

跑步时 --mode=stateful 或 --mode=both，服务器公开了有状态的工具，让LLM与实时页面交互。 状态会话通过Steel会话API创建，并通过CDP（Chrome DevTools协议）连接。

可用工具

  • session_create -创建新的Steel会话并连接
  • session_release -释放当前会话
  • navigate -导航到URL
  • search -打开谷歌搜索结果进行查询
  • click -按标签单击元素
  • type -按标签键入元素
  • scroll_down / scroll_up -滚动页面
  • go_back -返回导航
  • wait -等待几秒钟以获取动态内容
  • snapshot -带注释的屏幕截图+标签列表
  • snapshot_unmarked -无标签的屏幕截图
  • page_content -返回页面HTML或文本

示例会话

// Create a session
{
  "tool": "session_create",
  "arguments": { "timeoutMs": 900000 }
}

// Navigate
{
  "tool": "navigate",
  "arguments": { "url": "https://example.com" }
}

// Get an annotated snapshot (labels + image)
{
  "tool": "snapshot",
  "arguments": {}
}

// Click a labeled element
{
  "tool": "click",
  "arguments": { "label": 3 }
}

// Type into a labeled input
{
  "tool": "type",
  "arguments": { "label": 5, "text": "hello", "replaceText": true }
}

智能长度管理

服务器自动处理内容长度优化：

  • 统一长度控制：单人 maxLength 参数同时处理内容和元数据
  • 自动内容/元数据拆分：对于降价，元数据保留10%，内容使用90%
  • 智能默认值：未指定长度时的合理默认值（markdown=8000，text=10000，html=15000，json=5000）
  • 更好的截断：避免可能导致内容不完整的双重截断问题
  • 转换检测：自动检测HTML到markdown转换何时可能失败
  • 警报系统：当内容被截断或不完整时提供警告

运作原理

// Simple usage - uses smart defaults
{
  "url": "https://example.com",
  "format": ["markdown"]
  // Automatically uses 8000 characters, reserves 800 for metadata, 7200 for content
}

// Custom length - automatically splits appropriately
{
  "url": "https://example.com", 
  "format": ["markdown"],
  "maxLength": 5000
  // Uses 5000 total, reserves 500 for metadata, 4500 for content
}

这种方法可确保您获得完整、格式正确的内容，同时保持简单直观的参数管理。

处理大页面（如亚马逊）

对于像Amazon.com这样的大型复杂页面，请遵循以下最佳实践：

复杂页面的推荐方法

{
  "tool": "visit_with_browser",
  "arguments": {
    "url": "https://www.amazon.com",
    "format": ["readability"],  // Most reliable for complex pages
    "maxLength": 5000,          // Reasonable limit for large pages
    "delay": 3                  // Wait for main content to load
  }
}

大页面格式比较

  • 超文本标记语言：返回原始HTML源代码（亚马逊可以是900000+个字符）
  • 可读性：Mozilla可读性格式（最可靠，适用于复杂页面）
  • 标记语言：将HTML转换为干净、可读的文本（在亚马逊等复杂页面上可能会失败）
  • 已清理的HTML：使用更好的结构清理HTML

备注：Markdown转换可能会在亚马逊等复杂、JavaScript繁重的页面上失败。使用 ["readability"] 以获得最可靠的结果。

故障排除

如果你使用HTML而不是Markdown：

  • steel-dev API可能不支持该页面类型的降价转换
  • 尝试使用 format: ["readability"] 而是为了更好地提取文本
  • 使用大量JavaScript的复杂页面可能无法正确转换

如果内容被截断：

  • 页面可能太大，无法容纳指定的 maxLength
  • 尝试增加 maxLength 或使用更长的 delay
  • 考虑使用 format: ["readability"] 为了获得更可靠的截断

用于动态内容

使用 delay 等待内容加载的参数：

{
  "tool": "visit_with_browser",
  "arguments": {
    "url": "https://www.amazon.com",
    "format": ["markdown"],
    "delay": 5,                 // Wait 5 seconds for content to load
    "maxLength": 10000          // Longer content for complex pages
  }
}

默认情况下清除输出

服务器的设计考虑了7B型号，默认情况下提供干净、以内容为中心的输出：

  • 内容概述：非常适合需要总结网络内容的较弱模型
  • 内容分析：非常适合处理大量文本
  • 上下文优化：自动最大化内容与元数据的比率

运作原理

默认模式 （清洁输出）：

# Article Title
This is the actual content...

详细模式 (verboseMode: true):

SUCCESS: Successfully scraped https://example.com
Method: full-browser-automation (stealth browser, anti-detection)
Format: markdown
Status Code: 200
Processing Time: 1250ms
Content Length: 5000 characters
Content Type: text/html
Timestamp: 2024-01-15T10:30:00.000Z
Title: Article Title
Description: Article description
Language: en
Screenshot: Available (base64)
Links Found: 15

SCRAPED CONTENT:
# Article Title
This is the actual content...

清洁产出的好处

  • 最大内容空间：删除约200-300个字符的元数据开销
  • 更清洁的输出：没有冗长标题的直接内容
  • 更适合7B型号：将模型的注意力集中在实际内容上
  • 保留警告：如果发生转换问题，仍会显示重要警告

推荐使用方法

对于摘要任务，使用默认的干净输出：

{
  "tool": "visit_with_browser",
  "arguments": {
    "url": "https://article-to-summarize.com",
    "format": ["markdown"],
    "maxLength": 10000  // Automatically optimizes content vs metadata split
  }
}

钢与API要求

此MCP服务器需要一个steel-dev API实例运行，该实例具有以下端点：

  • POST /scrape -主要刮擦终点
  • GET /health -健康检查端点（可选）
  • GET /info -API信息端点（可选）
  • POST /v1/sessions -创建有状态的浏览器会话
  • POST /v1/sessions/{id}/release -释放有状态会话

预期请求格式

{
  "url": "https://example.com",
  "format": ["html", "markdown"],
  "screenshot": true,
  "pdf": false,
  "proxyUrl": "http://proxy:8080",
  "delay": 2,
  "logUrl": "https://logs.example.com"
}

预期响应格式

{
  "content": {
    "html": "<html>...</html>",
    "markdown": "# Title\nContent..."
  },
  "metadata": {
    "title": "Page Title",
    "description": "Page description",
    "statusCode": 200,
    "timestamp": "2024-01-15T10:30:00.000Z"
  },
  "links": [
    {"url": "https://example.com/link1", "text": "Link Text"}
  ],
  "screenshot": "base64...",
  "pdf": "base64..."
}

发展

项目结构

src/
├── index.ts          # Main MCP server implementation
├── steel-api.ts      # Steel-dev API wrapper
└── config.ts         # Configuration management

脚本

  • npm run build -将TypeScript构建为JavaScript
  • npm run start -运行内置服务器
  • npm run dev -使用tsx在开发模式下运行

添加新功能

  1. 在中修改工具架构 src/index.ts
  2. 更新 SteelAPI 上课中 src/steel-api.ts 如有需要
  3. 重建和测试

错误处理

服务器包括全面的错误处理：

  • 网络错误被捕获并作为错误响应返回
  • 验证无效参数
  • 正确转发API钢制变形错误
  • 长时间运行的请求的超时处理

许可证

麻省理工学院

相关 MCP