SnoopScan

SnoopScan

将任意公开网页转换为整洁的 Markdown、结构化 JSON，或你定义的架构——包括那些会拦截其他所有请求的网页。适用于 AI Agent 的 MCP 服务、REST API 和 SDK。

此仓库是 SnoopScan 的开源核心，可独立运行；snoopscan.com 上的托管 API 则提供这里没有的功能。请参阅开源版与托管 API。

在 AI 聊天中设置

将以下内容粘贴到 Claude Code、Codex、Cursor、VS Code 或任何 AI Agent 中：

Read and follow https://snoopscan.com/agent-onboarding/SKILL.md

你的 Agent 会读取指南并完成所有步骤。浏览器打开后，登录或创建免费账户（每月 1,500 个积分，无需银行卡），然后点击 Approve。就这么简单：让它读取一个网页即可。

在 Claude Code 中，你也可以安装 SnoopScan 插件，它包含 SnoopScan 的技能和 MCP 服务。在 Claude Code 的聊天中输入以下内容：

/plugin marketplace add SnoopScan/snoopscan-core
/plugin install snoopscan@snoopscan

Claude 应用和 ChatGPT 通过登录连接，无需复制密钥：添加自定义连接器（Claude）或开发者模式应用（ChatGPT），地址为 https://api.snoopscan.com/mcp-oauth。每种客户端的操作步骤见 snoopscan.com/integrations。

在代码中使用

以下示例调用托管 API，并从 SNOOPSCAN_API_KEY 读取你的密钥。请在 snoopscan.com/app/keys 创建密钥，或使用上述设置让你的 Agent 代为获取。

还没有密钥？/v1/scrape、/v1/search 和 /v1/parse 也支持不带 Authorization 请求头的调用：每个 IP 地址每天可免费调用 20 次，适用于无需浏览器即可加载的网页。每次响应都会说明剩余的免费调用次数。

curl

curl -X POST https://api.snoopscan.com/v1/scrape \
  -H "Authorization: Bearer $SNOOPSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/", "formats": ["markdown", "links"]}'

Python

pip install snoopscan

import os
from snoopscan import SnoopScan

snoop = SnoopScan(api_key=os.environ["SNOOPSCAN_API_KEY"])
print(snoop.scrape("https://example.com/").markdown)

JavaScript / TypeScript

npm install snoopscan

import { SnoopScan } from 'snoopscan';

const snoop = new SnoopScan({ apiKey: process.env.SNOOPSCAN_API_KEY! });
console.log((await snoop.scrape('https://example.com/')).markdown);

其他语言

所有 SDK 都有相同的方法、错误代码和重试规则；如果没有传入密钥，还会从环境变量读取 SNOOPSCAN_API_KEY。每个目录中的 README 都介绍了所有方法。

语言	安装	源码
PHP 8.1+	composer require snoopscan/snoopscan	sdk/php
Go 1.22+	go get github.com/SnoopScan/snoopscan-core/sdk/go	sdk/go
Ruby 3.0+	gem install snoopscan	sdk/ruby
Java 11+	com.snoopscan:snoopscan（Maven、Gradle）	sdk/java
.NET 8+	dotnet add package SnoopScan	sdk/dotnet
Rust	cargo add snoopscan	sdk/rust
Elixir	{:snoopscan, "~> 0.1"}	sdk/elixir

功能

• 输出整洁：可获取 Markdown、HTML、链接、截图，或符合你自定义架构的 JSON。
• 处理棘手网页：无需设置即可处理 JavaScript 渲染、受阻网页和代理（托管 API）。
• 整站处理：爬取网站、映射其 URL，或将数千个 URL 作为一个任务批量处理。
• 结构化数据：填充 JSON 架构或命名模板，并为每个网页提供置信度评分。
• 一次调用处理商店和博客：获取商店的完整商品目录或博客文章，无需爬取。
• 按结果付费：失败的请求不收费，每个响应都包含一个 cost 对象。
• 适用于 Agent：每个端点也都是 MCP 工具。

开源版与托管 API

此仓库包含：

• REST API
• 提取
• 拦截检测
• 爬取
• MCP 服务
• HTTP 抓取
• 存储
• 客户端 SDK：Python、JS/TS、PHP、Go、Ruby、Java、.NET、Rust 和 Elixir

snoopscan.com 上的托管 API 还提供：

• 浏览器渲染
• 代理和反机器人处理
• 线索生成

可自托管版本通过 HTTP 读取网页。需要浏览器的网页会返回 BLOCKED，而不会被视为空成功。托管 API 的免费套餐每月包含 1,500 个积分。

MCP 服务

每个端点也是一个 MCP 工具，因此 Agent 可以直接调用，无需胶水代码。托管服务地址为 https://api.snoopscan.com/mcp（可流式传输的 HTTP，Authorization: Bearer <key>），而 https://api.snoopscan.com/mcp-oauth 使用登录，而非密钥。连接到 /mcp 时即使没有密钥，Agent 也可以像使用 REST 一样，在每日免费试用额度内尝试 scrape、search 和 parse；其他所有工具都需要免费密钥。最简单的设置就是上面那一行：Agent 会遵循Agent 入门指南，其中介绍了 Claude Code、Codex、Cursor、VS Code、Windsurf、Claude 应用、ChatGPT，以及任何支持可流式传输 HTTP 的其他客户端。

工具

• 页面：scrape、fetchMore、search、parse、extract、checkChanges
• 网站：map、crawl、crawlStatus、crawlPages、listProducts、listPosts
• 域名：domain、domainReport、domainSnapshots、domainScreen
• 公司和潜在客户：company、findContacts、people、hiring、findLeads、leadsStatus

产品和文章列表、域名报告及其快照、域名筛查，以及公司、联系人、人员、招聘和潜在客户工具都需要使用托管 API。此代码仓库会以纯文本“此部署中不可用”作为响应。

每个工具都有标题以及只读 / 破坏性标签。它们都不会提交、发布或购买任何内容。

限制

这些工具旨在减少 Agent 的上下文占用：

• 每个内容工具都接受 maxChars 预算。
• 截断始终会明确显示，并返回续传令牌。
• 爬取工具不会内嵌页面正文。
• 防护机制会限制每个会话的页面数、并发爬取数、爬取规模和带宽。
• 每次拒绝请求都会说明限制，以便 Agent 调整做法，而不是盲目重试。
• MCP 不会以任何级别公开 executeJavascript。

API 端点

POST /v1/scrape      one URL -> markdown, html, links, screenshot, json
                     (+ `actions`: click, type, scroll, then read the result)
POST /v1/crawl       a whole site, page by page
POST /v1/map         every URL on a site, ordered by relevance
POST /v1/search      the web, with the results scraped
POST /v1/extract     your JSON schema — or a named template — filled from the page
GET  /v1/templates   the named templates (product, article, jobPosting, …) and their fields
POST /v1/batch/scrape  many URLs, one job
POST /v1/parse       a PDF, DOCX or XLSX as markdown
POST /v1/monitor     watch URLs on a schedule, webhook on change
POST /v1/products    a store's whole product catalog
POST /v1/posts       every post from a blog or forum
POST /v1/company     enrich one company from its own site
POST /v1/domain      a domain's registration, DNS and backlinks
POST /v1/domain/report  a buyer's report on a domain (hosted API)
POST /v1/domain/screen  which of up to 500 names can be registered (hosted API)
POST /v1/places/search  local business listings, with contacts
POST /v1/leads       businesses by trade and town, with their contacts (hosted API)

每个页面都包含 metadata.platform，用于标识构建该页面的平台；每个响应都带有一个 cost 对象。

使用架构提取数据

curl -X POST https://api.snoopscan.com/v1/extract \
  -H "Authorization: Bearer $SNOOPSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "urls": ["https://example.com/product/1"],
        "schema": {"type": "object",
                   "properties": {"name":  {"type": "string"},
                                  "price": {"type": "string"}}}
      }'

监控页面变化

系统每 60 分钟检查一次页面，并在页面发生变化时发送 webhook。

curl -X POST https://api.snoopscan.com/v1/monitor \
  -H "Authorization: Bearer $SNOOPSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/pricing"],
       "intervalMinutes": 60,
       "webhook": "https://your.app/hook"}'

开发

在本地设置并运行引擎：

uv venv --python 3.12 && uv pip install -e ".[dev]"
uv pip install -e sdk/python --python .venv/bin/python
cp .env.example .env && createdb scraping_engine && .venv/bin/alembic upgrade head
.venv/bin/python tools/create_key.py "local-dev" --rpm 600
.venv/bin/uvicorn engine.api.app:app --reload --port 8099

JS/TS SDK 位于 sdk/js，可独立构建：

cd sdk/js && npm install && npm run build && npm test

其他 SDK 的构建方式相同，每个 SDK 都位于自己的目录中，并使用自己的工具链；每个 README 的“开发”部分都列出了相应命令。它们的依赖项许可证由 sdk/check_licences.py 检查：

python3 sdk/check_licences.py rust     # after the SDK's own tests have run

运行测试、代码检查和类型检查：

.venv/bin/pytest engine/tests -q
.venv/bin/ruff check engine tools && .venv/bin/mypy --strict engine/core

依赖项许可证

每个依赖项都必须采用 MIT、Apache-2.0、BSD、ISC 或 MPL-2.0 许可证。此项检查会阻止构建：如果构建引入任何其他许可证，便会失败。该检查也会每周运行，因为传递依赖项的许可证可能发生变化。

.venv/bin/pip-licenses --format=json > licences.json \
  && .venv/bin/python tools/check_licences.py licences.json

这项规则已经在代码中带来两个结果。项目未使用 psycopg2（LGPL），Alembic 会改用 asyncpg 进行迁移。作为传递依赖项引入的 tld 有一条已记录的允许列表条目，其中注明了我们使用其三重许可证中的哪个分支。

贡献

贡献必须遵循以下三条规则：

1. 洁净室实现。不得使用任何 AGPL、GPL 或 SSPL 项目的代码。此 API 采用此类别中常见的选项名称，是因为接口兼容性是合理的；但其实现是独立完成的。
2. 许可证检查会阻止构建，而非仅提供建议。
3. 代码仓库中不得包含个人信息或可识别身份的信息。配置只能来自环境变量。所有测试样例都使用 example.com 或 .invalid。

许可证

引擎采用 AGPL-3.0 许可证。如果你将修改后的版本作为网络服务运行，第 13 条要求你向用户提供其源代码。运行中的实例会通过 GET /v1/source 自行提供源代码，因此不依赖可能被分支版本忘记更新的文档。

sdk/ 中的所有 SDK 均采用 MIT 许可证。AGPL 客户端库会将 copyleft 义务延伸到每个导入它的应用，这与客户端库的用途不符。

部分模块为专有模块，不受 AGPL 约束：浏览器渲染、代理和反机器人处理，以及潜在客户开发。它们列在 LICENSE-PROPRIETARY 中，该文件由 engine/licensing.py 生成。CI 会强制执行这一拆分：如果任何公共模块依赖其中的专有模块，tools/check_split.py 就会导致构建失败。