SmartFetch V1.8 — обнаруживаемость MCP

SmartFetch принимает публичный веб-URL и возвращает чистый текст, готовый для агентов, Markdown, ссылки, метаданные и использованный метод получения данных. Сначала он пытается выполнить недорогое HTTP-получение, а при необходимости переключается на настоящий браузер Chromium.

Что изменилось в V1.8

• Платный MCP-инструмент fetch_webpage теперь объявляет официальные метаданные x402 Bazaar для обнаружения агентами, не изменяя своё поведение при выполнении и оплате.

• Корневой server.json объявляет существующую конечную точку /mcp Streamable HTTP как сервер только для удалённого доступа для официального MCP Registry.

• Это обновление репозитория не выполняет публикацию в Registry, развёртывание, изменение переменных Railway или оплату.

Всё поведение HTTP-оплаты, Bazaar и нативного MCP из V1.7 остаётся без изменений:

• Base Sepolia остаётся сетью x402 по умолчанию и продолжает использовать https://x402.org/facilitator без учётных данных CDP.

• Base mainnet может использовать аутентифицированный CDP-фасилитатор Coinbase при явном выборе.

• Запуск в mainnet требует наличия обоих учётных данных CDP API и при недействительных учётных данных или отсутствии поддержки фасилитатора завершается отказом.

• /meta различает включённые режимы оплаты testnet и mainnet.

• cdp-sdk, FastAPI, Uvicorn и x402 точно зафиксированы по версиям, чтобы обновления инфраструктуры были явными.

Движок получения данных, поведение извлечения/браузера, защита SSRF, лимиты запросов, ограничение частоты запросов и контроль конкурентности не изменились.

Related MCP server: SteadyFetch

API

GET /health

Возвращает состояние сервиса/версию.

GET /meta

Машиночитаемое описание сервиса.

POST /fetch

{
  "url": "https://example.com/article",
  "max_chars": 20000,
  "force_browser": false
}

max_chars необязателен (минимум 1 000; по умолчанию 20 000; максимум 50 000).

Пример полей ответа:

{
  "success": true,
  "requested_url": "https://example.com/article",
  "final_url": "https://example.com/article",
  "status_code": 200,
  "render_method": "http",
  "title": "…",
  "content": "…",
  "markdown": "…",
  "links": [],
  "word_count": 1000,
  "content_hash": "…",
  "truncated": false,
  "elapsed_ms": 350,
  "request_id": "…",
  "service_version": "1.8.0"
}

Когда защита оплаты x402 включена, заголовок PAYMENT-REQUIRED для POST /fetch содержит объявление Bazaar с контрактом входных данных url, max_chars и force_browser, а также репрезентативный успешный ответ. /, /health и /meta остаются бесплатными и не объявляют метаданные Bazaar.

MCP

Удалённые MCP-клиенты подключаются к /mcp через Streamable HTTP. Сервер предоставляет ровно один инструмент:

fetch_webpage
  url: required string
  max_chars: optional integer (default 20000, minimum 1000, maximum 50000)
  force_browser: optional boolean (default false)

Инструмент читает, получает, скрейпит или извлекает публичные веб-страницы для агентов и возвращает существующий текст SmartFetch, Markdown, ссылки и метаданные получения данных. Он использует те же проверку SSRF, исполнитель, таймаут запроса, ограничение конкурентности, ограничение вывода, HTTP-получение и запасной вариант с браузером, что и POST /fetch; при этом он не выполняет HTTP-запрос обратно к публичному API.

Когда x402 включён, неоплаченный tools/call возвращает нативный платёжный вызов x402 MCP. Действительный платёж проверяется перед получением данных, а расчёт выполняется один раз после успешного выполнения инструмента. Сеть, публичный получатель и цена берутся из X402_NETWORK, X402_PAY_TO и X402_PRICE. Ни закрытый ключ продавца, ни секрет кошелька не принимаются и не требуются.

Неоплаченный платёжный вызов MCP включает объявление Bazaar для fetch_webpage с транспортом streamable-http, существующим контрактом входных данных и репрезентативным выводом SmartFetch. Его платёжный ресурс остаётся mcp://tool/fetch_webpage. Существующий HTTP-ресурс Bazaar для POST /fetch является отдельным и не изменён.

Корневой server.json описывает публичную удалённую конечную точку https://smartfetch-production-ea53.up.railway.app/mcp. Публикация в Registry — отдельное действие аутентифицированного оператора; добавление манифеста не публикует и не развёртывает сервис.

Локальный запуск

python -m pip install -r requirements.txt
python -m smartfetch.server

Затем:

curl http://127.0.0.1:8787/health
curl -X POST http://127.0.0.1:8787/fetch \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com"}'

Пользователи Windows могут запустить setup_windows.bat, затем start_windows.bat.

Если X402_ENABLED не задан или равен false, для запуска не требуются настройки оплаты, и /fetch остаётся бесплатным для локального и удалённого тестирования.

Режимы оплаты x402

Оплата остаётся отключённой, пока её явно не включат. Base Sepolia используется по умолчанию и требует только публичный адрес получателя:

X402_ENABLED=true
X402_PAY_TO=0xYOUR_PUBLIC_RECEIVING_ADDRESS
X402_PRICE=$0.005
X402_NETWORK=eip155:84532

X402_PRICE и X402_NETWORK при отсутствии используют указанные значения. Цена по умолчанию остаётся $0.005.

Base mainnet должен быть выбран явно и использует аутентифицированный CDP-фасилитатор Coinbase:

X402_ENABLED=true
X402_PAY_TO=0xYOUR_PUBLIC_RECEIVING_ADDRESS
X402_PRICE=$0.005
X402_NETWORK=eip155:8453
CDP_API_KEY_ID=YOUR_CDP_API_KEY_ID
CDP_API_KEY_SECRET=YOUR_CDP_API_KEY_SECRET

Mainnet требует оба учётных данных CDP. Отсутствующие, недействительные или непригодные учётные данные, неподдерживаемые точные платежи Base mainnet или любой сбой инициализации фасилитатора/промежуточного ПО прерывают запуск. SmartFetch никогда не переключается на бесплатный доступ или тестнет-фасилитатор, когда выбран mainnet. Любая сеть, кроме Base Sepolia и Base mainnet, отклоняется.

Защищён только POST /fetch. /health, / и /meta всегда остаются бесплатными. Включённые ответы /meta сообщают x402-enabled-testnet или x402-enabled-mainnet, не раскрывая значения конфигурации.

SmartFetch использует X402_PAY_TO как публичный адрес получателя, и ему не нужен CDP_WALLET_SECRET. Никогда не передавайте закрытый ключ MetaMask продавца или фразу восстановления: SmartFetch не требует, не читает, не принимает, не записывает в журнал и не хранит ни то, ни другое.

Локальная проверка

python tests/security_smoke.py
python tests/api_local_smoke.py

api_local_smoke.py намеренно включает доступ к частной сети только внутри тестового процесса, чтобы можно было использовать локальную фикстуру localhost.

Контейнер

docker build -t smartfetch:v1.8 .
docker run --rm -p 8787:8787 smartfetch:v1.8

Контейнер автоматически устанавливает Chromium.

Публичное развёртывание

Этот пакет готов к использованию с Docker. Railway может развернуть включённые Dockerfile и railway.json; любой Docker-хост с исходящим HTTPS и достаточным объёмом ОЗУ для одного процесса Chromium также должен работать.

Рекомендуемые начальные переменные окружения:

MAX_CONCURRENT_BROWSERS=1
MAX_CONCURRENT_FETCHES=4
DEFAULT_MAX_OUTPUT_CHARS=20000
MAX_OUTPUT_CHARS=50000
FETCH_TIMEOUT_SECONDS=12
BROWSER_TIMEOUT_SECONDS=15
TOTAL_REQUEST_TIMEOUT_SECONDS=25
RATE_LIMIT_PER_MINUTE=30
RATE_LIMIT_BURST=10
X402_ENABLED=false

Не устанавливайте ALLOW_PRIVATE_NETWORK=1 в продакшене.

Важное примечание о развёртывании и SSRF

Включена проверка URL на уровне приложения, но рендеринг в браузере может выполнять подресурсы страницы. Для платного публичного развёртывания контейнер браузера должен быть дополнительно изолирован политикой исходящего трафика хоста/сети от метаданных облака и частных сетей RFC1918. Мы снова усилим защиту перед снятием временного ограничения частоты запросов и перед запуском x402.

Тестирование публичного развёртывания

В Windows запустите test_remote_windows.bat, вставьте публичный URL и загрузите tests/remote_20_results.json.

Или:

python tests/remote_20.py https://YOUR-PUBLIC-URL

Наш порог для развёртывания остаётся минимум 18/20, включая все пять запросов с принудительным браузером.

Статус запуска оплаты

V1.8 сохраняет существующую конфигурацию оплаты Base Sepolia и Base mainnet. Это изменение репозитория само по себе не публикует сервис в MCP Registry, не развёртывает его и не изменяет переменные Railway. Активная платёжная сеть управляется с помощью X402_NETWORK: eip155:84532 для Base Sepolia или eip155:8453 для Base mainnet.