pulse-fetch

Pulse Fetch MCP 服务

还不了解 MCP？最简单的了解方式是阅读我们在 PulseMCP 上发布的每周通讯。

---

这是一个 MCP（Model Context Protocol）服务，可将开放互联网中的特定资源拉取到上下文中，专为构建 Agent 的框架以及缺少内置抓取功能的 MCP 客户端而设计。

Pulse Fetch 专为从网页中提取干净、结构化的内容而打造，可最大限度地减少令牌用量，并通过先进的反机器人绕过功能可靠地访问受保护内容。

本项目由 PulseMCP 构建并维护。

目录

• 亮点
• 功能
• 使用技巧
• 示例
• 设置
  • 先决条件
  • 环境变量
  • Claude Desktop
    • 本地设置
    • 远程设置
• 开发
• 抓取策略配置
• 提取功能

亮点

干净的内容提取：使用 Mozilla 的 Readability 算法去除 HTML 杂项，最大限度地减少 MCP 工具调用期间的令牌用量。

智能缓存：自动将抓取的内容缓存为 MCP 资源。后续请求同一 URL 时会立即返回缓存内容，无需网络调用，从而大幅提升性能。

绕过反机器人机制：集成 Firecrawl 和 BrightData API，可靠地绕过反抓取技术。

智能策略选择：自动学习并应用针对特定 URL 模式的最佳抓取方法，随时间推移不断提升性能。

针对大模型优化：提供 MCP 提示词和描述清晰的工具设计，以提高与大模型交互的可靠性。

灵活的格式：支持多种输出格式，包括干净的 Markdown、HTML、屏幕截图和结构化数据提取。

智能提取：使用由大模型驱动的自然语言查询提取特定信息。

功能

此服务基于 macOS 和 Claude Desktop 构建并经过测试，也应该适用于其他 MCP 客户端。

工具名称	描述
scrape	抓取单个网页，支持高级内容提取选项和多种输出格式。

使用技巧

• scrape 工具可处理所有网页内容提取需求，并会在必要时自动绕过反机器人保护
• 结果处理模式：使用 resultHandling 参数控制抓取内容的处理方式：
  • saveAndReturn（默认）：将内容保存为 MCP 资源并返回内容，最适合重复使用
  • returnOnly：返回内容但不保存，适用于只需使用一次的情况
  • saveOnly：将内容保存为 MCP 资源，仅返回资源链接，适用于大型内容
• 自动缓存：默认缓存之前抓取过的 URL。再次请求时，工具会立即返回缓存内容
• 如果知道页面已发生变化，可使用 forceRescrape: true 绕过缓存并获取最新内容
• 使用 maxChars 和 startIndex 参数处理超出令牌限制的大型内容
• 为加载缓慢的网站配置超时参数（默认值为 60s）
• 使用 extract 参数和自然语言查询，从网页中提取特定信息（需要配置大模型）

示例

基本网页内容提取

User: "Get the main content from this article: https://example.com/article"
Assistant: I'll extract the content from that article for you.

[Uses scrape tool with onlyMainContent: true]

I've extracted the main article content. The article is titled "Example Article Title" and contains approximately 2,500 words discussing...

提取结构化数据

User: "Extract the product information from this e-commerce page: https://shop.example.com/product/123"
Assistant: I'll extract the structured product data from that page.

[Uses scrape tool with format: 'extract' and appropriate schema]

I've extracted the product information:
- Product Name: Example Product
- Price: $99.99
- Rating: 4.5/5 stars
- Description: High-quality example product...

处理受保护内容

User: "This page is blocking me with CAPTCHA. Can you get the content from https://protected.example.com/data"
Assistant: I'll extract the content from that protected page for you.

[Uses scrape tool with automatic anti-bot bypass]

I successfully bypassed the protection and extracted the content from the page using BrightData's Web Unlocker capabilities.

智能缓存

User: "Get the content from https://example.com/article again"
Assistant: I'll retrieve that content for you.

[Uses scrape tool - automatically returns cached content]

I've retrieved the content from cache (originally scraped 2 hours ago). The article contains...

User: "Actually, I think that article was updated. Can you get the latest version?"
Assistant: I'll fetch a fresh copy of the article for you.

[Uses scrape tool with forceRescrape: true]

I've fetched the latest version of the article. I can see it was indeed updated with new information about...

结果处理选项

User: "I need to archive this entire article: https://example.com/long-article"
Assistant: I'll save that article as a resource for you.

[Uses scrape tool with resultHandling: 'saveOnly']

I've successfully archived the article. It's now saved as an MCP Resource that you can access later.

User: "Can you extract just the summary from https://example.com/report without saving it?"
Assistant: I'll extract just the summary without saving the full content.

[Uses scrape tool with resultHandling: 'returnOnly' and extract parameter]

Here's the summary I extracted from the report: [summary content]

为什么选择 Pulse Fetch？

如果我们的设计原则与您的理念相契合，您应考虑使用我们的服务。

官方 fetch 参考实现是最接近的替代方案。不过：

• fetch 没有绕过反爬技术的机制，因此请求可能会随机失败。我们集成了第三方服务，以确保可靠访问。
• fetch 由志愿者维护，因此 Bug 或边缘情况不太可能得到及时处理。
• Pulse Fetch 会将响应缓存为资源，方便检查和重复使用工具调用结果。
• Pulse Fetch 的工具设计描述性更强，能更可靠地触发并完成预期任务。

大多数其他替代方案至少在以下一个方面有所不足：

• 它们并非专为将特定互联网资源提取到上下文中而构建
• 它们可能是多页面爬虫、搜索引擎，或与完整的 REST API 绑定，容易让大模型感到困惑
• 它们未能充分利用 MCP 的资源和提示词等概念

设置

前提条件

• Node.js（建议使用 package.json 中指定的版本）
• Claude 桌面应用（用于本地设置）
• 可选：Firecrawl API 密钥，用于增强抓取能力
• 可选：BrightData Bearer 令牌，用于网页解锁功能

环境变量

核心配置

环境变量	描述	必需	默认值	示例
FIRECRAWL_API_KEY	Firecrawl 服务的 API 密钥，用于绕过反机器人措施	否	N/A	fc-abc123...
BRIGHTDATA_API_KEY	BrightData Web Unlocker 服务的 Bearer 令牌	否	N/A	Bearer bd_abc123...
STRATEGY_CONFIG_PATH	包含抓取策略配置的 Markdown 文件路径	否	OS 临时目录	/path/to/scraping-strategies.md
OPTIMIZE_FOR	抓取优化策略：cost 或 speed	否	cost	speed
MCP_RESOURCE_STORAGE	已保存资源的存储后端：memory 或 filesystem	否	memory	filesystem
MCP_RESOURCE_FILESYSTEM_ROOT	文件系统存储目录（仅在使用 filesystem 类型时生效）	否	/tmp/pulse-fetch/resources	/home/user/mcp-resources
SKIP_HEALTH_CHECKS	启动时跳过 API 身份验证健康检查	否	false	true

Extract 功能的 LLM 配置

对于不支持 MCP 原生采样功能的客户端，extract 功能提供了替代方案。配置后，它可以使用大模型从抓取的内容中智能提取信息。如果既未配置大模型，也无法使用 MCP 采样功能，则工具中不会显示 extract 参数。

环境变量	描述	必填	默认值	示例
LLM_PROVIDER	大模型提供商：anthropic、openai、openai-compatible	否	N/A	anthropic
LLM_API_KEY	所选大模型提供商的 API 密钥	否	N/A	sk-abc123...
LLM_API_BASE_URL	OpenAI 兼容提供商的基础 URL	否	N/A	https://api.together.xyz/v1
LLM_MODEL	用于提取的特定模型	否	见下方默认值	gpt-4-turbo

默认模型：

• Anthropic：claude-sonnet-4-20250514（Claude Sonnet 4——最新且能力最强）
• OpenAI：gpt-4.1-mini（GPT-4.1 Mini——最新且能力最强）
• OpenAI 兼容：由提供商指定（必须指定）

Claude Desktop

本地设置

你需要在计算机上安装 Node.js，才能运行本地版本。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%\Claude\claude_desktop_config.json

将以下配置添加到 Claude Desktop 配置文件中：

最简配置（仅使用原生 fetch）：

{
  "mcpServers": {
    "pulse-fetch": {
      "command": "npx",
      "args": ["-y", "@pulsemcp/pulse-fetch"]
    }
  }
}

完整配置（包含所有可选环境变量）：

{
  "mcpServers": {
    "pulse-fetch": {
      "command": "npx",
      "args": ["-y", "@pulsemcp/pulse-fetch"],
      "env": {
        "FIRECRAWL_API_KEY": "your-firecrawl-api-key",
        "BRIGHTDATA_API_KEY": "your-brightdata-bearer-token",
        "STRATEGY_CONFIG_PATH": "/path/to/your/scraping-strategies.md",
        "OPTIMIZE_FOR": "cost",
        "MCP_RESOURCE_STORAGE": "filesystem",
        "MCP_RESOURCE_FILESYSTEM_ROOT": "/path/to/resource/storage"
      }
    }
  }
}

设置本地版本：

1. 克隆或下载仓库
2. 转到本地目录：cd pulse-fetch/local
3. 安装依赖：npm install
4. 构建项目：npm run build
5. 使用正确的路径更新 Claude Desktop 配置
6. 重启 Claude Desktop

远程设置

如需托管解决方案，请参阅 Pulse Fetch（远程）。

开发

项目结构

pulse-fetch/
├── local/                 # Local server implementation
│   ├── src/
│   │   └── index.ts      # Main entry point
│   ├── build/            # Compiled output
│   └── package.json
├── shared/               # Shared business logic
│   ├── src/
│   │   ├── tools.ts      # Tool implementations
│   │   ├── resources.ts  # Resource implementations
│   │   └── types.ts      # Shared types
│   └── package.json
└── remote/               # Remote server (planned)
    └── README.md

在开发模式下运行

# Build shared module first
cd shared
npm install
npm run build

# Run local server in development
cd ../local
npm install
npm run dev

测试

本项目包含全面的测试功能：

# Install all dependencies
npm run install-all

# Run tests (if implemented)
npm test

# Run linting
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

代码检查与格式化

项目使用 ESLint 和 Prettier 来保证代码质量和一致性：

# Check for linting issues
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format all code
npm run format

# Check if code is properly formatted
npm run format:check

工具参考

scrape

使用高级选项抓取单个网页并提取内容。

内容清理

默认情况下（cleanScrape: true），工具会自动清理抓取的内容：

• HTML 内容：转换为语义化 Markdown，移除导航栏、广告、侧边栏和其他冗余内容，同时保留主要内容结构。通常可将内容大小减少 50%–90%。
• JSON/XML 内容：原样传递（已有结构）
• 纯文本：原样传递

仅在以下情况下禁用清理（cleanScrape: false）：

• 需要精确的原始 HTML 结构以进行解析
• 正在调试抓取问题
• 正在处理预先结构化的内容

参数：

• url（string，必填）：要抓取的网址（例如，“https://example.com”或仅“example.com”——如果未指定协议，则会自动添加 https://）
• timeout（number）：等待页面加载的最长时间
• maxChars（number）：返回的最大字符数（默认值：100,000）
• startIndex（number）：输出的起始字符索引（用于分页）
• saveResult（boolean）：将结果保存为 MCP 资源（默认值：true）
• forceRescrape（boolean）：即使已有缓存也强制重新抓取（默认值：false）
• cleanScrape（boolean）：将 HTML 内容转换为语义化 Markdown 进行清理（默认值：true）
• extract（string）：用于智能提取内容的自然语言查询（需要配置大模型）

路线图与未来构想

计划中的功能

• 支持 MCP Sampling 进行提取——在可用时使用 MCP 客户端的原生大模型能力
• 使用 Sampling（外部 API 作为后备）判断抓取是否成功（并据此将其保存为学习结果）
  • 目前，我们根据 HTTP 状态码判断抓取是否成功，这可能并不可靠（例如返回 200，但显示反机器人屏幕）
• 支持截图
  • 允许在 scrape 工具中使用 screenshot 和 screenshot-full-page 格式

未来增强构想

增强抓取参数：

• includeHtmlTags：要包含在输出中的 HTML 标签
• excludeHtmlTags：要从输出中排除的 HTML 标签
• customUserAgent：自定义 User-Agent 字符串
• ignoreRobotsTxt：是否忽略 robots.txt 限制
• proxyUrl：可选的代理网址
• headers：请求的自定义标头
• followLinks：跟踪页面上的相关链接

交互功能：

• 在抓取前执行点击或滚动等自定义操作

图像处理：

• imageStartIndex：图像收集的起始位置
• raw：返回原始内容，而非处理后的 Markdown
• imageMaxCount：每次请求处理的最大图像数
• imageMaxHeight/Width：图像尺寸限制
• imageQuality：JPEG 质量（1-100）
• enableFetchImages：启用图像获取和处理

许可证

MIT

身份验证健康检查

Pulse Fetch 会在服务启动时验证 API 凭据，以便在身份验证配置有误时尽早失败。这可以避免工具执行期间出现无提示失败。

健康检查行为：

• 服务启动时自动运行（除非已禁用）
• 发起最少量的测试请求以验证 API 密钥，不消耗额度
• 身份验证失败时退出并显示清晰的错误消息
• 可通过设置 SKIP_HEALTH_CHECKS=true 禁用

凭据无效时的示例输出：

Running authentication health checks...

Authentication health check failures:
  Firecrawl: Invalid API key - authentication failed
  BrightData: Invalid bearer token - authentication failed

To skip health checks, set SKIP_HEALTH_CHECKS=true

抓取策略配置

pulse-fetch MCP 服务包含一个智能策略系统，可自动为不同网站选择最佳抓取方法。

优化模式

OPTIMIZE_FOR 环境变量控制抓取策略的顺序和选择：

• COST（默认）：优先尝试原生抓取，然后是 Firecrawl，最后是 BrightData，以实现最低成本

  • 顺序：native → firecrawl → brightdata
  • 适用场景：大多数关注成本的用例
  • 行为：始终先尝试免费的原生方式，再使用付费服务

• SPEED：跳过原生抓取，直接从功能更强大的抓取工具开始，以更快获得结果

  • 顺序：firecrawl → brightdata（完全跳过原生抓取）
  • 适用场景：对时间敏感的应用，或已知会阻止原生抓取的网站
  • 行为：直接使用高级抓取工具，它们更有可能成功抓取复杂网站

配置示例：

export OPTIMIZE_FOR=SPEED  # For faster, more reliable scraping
export OPTIMIZE_FOR=COST   # For cost-effective scraping (default)

工作原理

1. 已配置的策略：服务会检查本地配置文件，查找特定 URL 对应的策略
2. 通用回退：如果不存在已配置的策略，或该策略执行失败，则回退到通用方案（native → firecrawl → brightdata）
3. 自动学习：策略执行成功后，系统会自动将其保存到配置文件，并生成智能 URL 模式以供后续使用

策略类型

• native：使用 Node.js fetch API 进行快速原生抓取（适用于简单页面）
• firecrawl：使用 Firecrawl API 增强内容提取（适用于复杂布局）
• brightdata：使用 BrightData Web Unlocker 绕过反机器人机制（适用于受保护的内容）

配置文件

配置以 Markdown 表格形式存储。默认情况下，系统会自动在操作系统临时目录中创建该文件（例如，在 Unix 系统上为 /tmp/pulse-fetch/scraping-strategies.md）。你可以通过设置 STRATEGY_CONFIG_PATH 环境变量来自定义文件位置。

该表格包含三列：

• prefix：用于匹配的域名或 URL 前缀（例如，reddit.com 或 reddit.com/r/）
• default_strategy：要使用的策略（native、firecrawl 或 brightdata）
• notes：可选的描述或理由

配置示例

| prefix        | default_strategy | notes                                               |
| ------------- | ---------------- | --------------------------------------------------- |
| reddit.com/r/ | brightdata       | Reddit requires anti-bot bypass for subreddit pages |
| reddit.com    | firecrawl        | General Reddit pages work well with Firecrawl       |
| github.com    | native           | GitHub pages are simple and work with native fetch  |

前缀匹配规则

• 域名匹配：github.com 可匹配 github.com、www.github.com 和 subdomain.github.com
• 路径匹配：reddit.com/r/ 可匹配 reddit.com/r/programming，但不匹配 reddit.com/user/test
• 最长匹配优先：如果多个前缀匹配，则使用最长的前缀

自动发现策略

抓取新的 URL 时：

1. 系统会尝试通用回退顺序（native → firecrawl → brightdata）
2. 首个成功的策略会连同智能提取的 URL 模式自动保存到配置文件
3. 后续匹配该模式的请求将使用已发现的策略

URL 模式提取

系统通过移除最后一个路径段来提取 URL 模式：

• yelp.com/biz/dolly-san-francisco → yelp.com/biz/
• reddit.com/r/programming/comments/123 → reddit.com/r/programming/comments/
• example.com/blog/2024/article → example.com/blog/2024/
• stackoverflow.com/questions/123456 → stackoverflow.com/questions/

对于只有一个路径段的 URL 或根 URL，只保存主机名。提取模式时会忽略查询参数和片段。

配置客户端抽象

系统使用抽象层来存储配置：

• FilesystemClient：将配置存储在本地 Markdown 文件中（默认）
  • 如果已设置，则使用 STRATEGY_CONFIG_PATH
  • 否则使用操作系统临时目录（例如，/tmp/pulse-fetch/scraping-strategies.md）
  • 自动创建包含常见模式的初始配置
• 未来客户端：可支持 GCS、S3、数据库存储等

创建 MCP 服务时，你可以通过提供不同的 StrategyConfigFactory 来更换存储后端。

资源存储

Pulse Fetch 将抓取的内容存储为 MCP 资源，以便缓存和日后检索。该存储系统支持多个层级，以保留处于不同处理阶段的内容。

存储结构

资源分为三个独立阶段保存：

1. 原始：从网站抓取的原始内容
2. 清理后：应用内容清理器（HTML → Markdown 等）后的内容
3. 提取后：经过大模型处理、仅包含所需信息的内容

文件系统存储

使用文件系统存储（MCP_RESOURCE_STORAGE=filesystem）时，文件会整理到子目录中：

/tmp/pulse-fetch/resources/
├── raw/
│   └── example.com_article_20250701_123456.md
├── cleaned/
│   └── example.com_article_20250701_123456.md
└── extracted/
    └── example.com_article_20250701_123456.md

每个阶段使用相同的文件名，以便轻松关联。提取后的文件会在其元数据中包含提取提示词，以便完整追溯。

内存存储

内存存储采用类似的结构，URI 如下：

• memory://raw/example.com_article_20250701_123456
• memory://cleaned/example.com_article_20250701_123456
• memory://extracted/example.com_article_20250701_123456

优势

• 调试：轻松检查每个处理阶段的内容
• 效率：针对不同的提取查询重复使用清理后的内容
• 可追溯性：跟踪内容在各个阶段的转换过程
• 灵活性：根据需要选择要返回的版本

提取功能

提取功能使用大模型从抓取的网页内容中智能提取信息。对于不支持 MCP 原生采样功能的客户端，它可作为替代方案。

概述

提取功能提供两种信息提取方式：

1. MCP 采样（尚未实现）：使用 MCP 客户端原生的大模型能力
2. 直接调用大模型 API：可配置的备用方案，使用你自己的 API 密钥

如果两种方式都不可用，该工具仍可在不具备提取能力的情况下运行，并且只返回抓取的原始内容。

工作原理

当你使用自然语言查询提供 extract 参数时，该工具将：

1. 首先正常抓取网页内容
2. 通过大模型处理内容，以提取所需信息
3. 返回提取后的数据，而不是原始 HTML

架构

大模型提供商支持

该实现支持三种提供商类型：

1. Anthropic（原生）：使用 Anthropic SDK 直接集成

   • 最适合：具备高级推理能力的 Claude 模型
   • API：使用 Anthropic 原生格式

2. OpenAI：与 OpenAI API 直接集成

   • 最适合：GPT-4 和 GPT-3.5 模型
   • API：标准 OpenAI 格式

3. OpenAI 兼容：支持任何提供 OpenAI 兼容端点的提供商

   • 包括：Together.ai、Groq、Perplexity、DeepSeek、Fireworks AI 等
   • API：使用自定义基础 URL 的 OpenAI 格式

配置

使用上文 提取功能的大模型配置 部分所述的环境变量配置提取功能。

使用示例

基本提取

User: "Get the author and publication date from this article: https://example.com/article"
Assistant: I'll extract that information from the article.

[Uses scrape tool with extract: "author name and publication date"]

The article was written by John Doe and published on March 15, 2024.

复杂数据提取

User: "Extract all product specifications from this page: https://shop.example.com/laptop"
Assistant: I'll extract the detailed specifications from that product page.

[Uses scrape tool with extract: "all technical specifications including processor, RAM, storage, display details, ports, and dimensions"]

Here are the laptop specifications:
- Processor: Intel Core i7-13700H
- RAM: 16GB DDR5
- Storage: 512GB NVMe SSD
...

实现策略

1. 客户端抽象层：为所有大模型提供商提供通用接口
2. 提供商专用客户端：
   • AnthropicClient：原生 Anthropic API 集成
   • OpenAIClient：OpenAI API 集成
   • OpenAICompatibleClient：适用于任何 OpenAI 兼容端点的灵活客户端
3. 提取流水线：
   • 对大型文档进行内容预处理和分块
   • 根据提取查询智能构建提示词
   • 解析并格式化响应
4. 回退机制：
   • 将 MCP 采样作为首选方法（如可用）
   • 将直接 API 调用作为备用方案
   • 错误处理和重试逻辑

为什么采用这种方案？

• 灵活性：用户可以选择自己偏好的大模型提供商
• 成本优化：支持多种提供商，可在成本和性能之间权衡
• 面向未来：OpenAI 兼容接口可确保新提供商自动接入
• MCP 优先：设计上优先使用 MCP 的采样能力（尚未实现）