SmartFetch V1.8 — MCP 발견 가능성

SmartFetch는 공개 웹 URL을 받아 에이전트가 바로 사용할 수 있는 정리된 텍스트, Markdown, 링크, 메타데이터, 그리고 사용된 가져오기 방식을 반환합니다. 먼저 저비용 HTTP 가져오기를 시도하고, 필요할 때 실제 Chromium 브라우저로 폴백합니다.

V1.8에서 변경된 사항

• 유료 MCP fetch_webpage 도구는 이제 실행 또는 결제 동작을 변경하지 않고 에이전트 발견을 위해 공식 x402 Bazaar 메타데이터를 선언합니다.

• 루트 server.json은 기존 /mcp Streamable HTTP 엔드포인트를 Official MCP Registry용 원격 전용 서버로 광고합니다.

• 이 저장소 업데이트로 Registry 게시, 배포, Railway 변수 변경 또는 결제가 수행되지는 않습니다.

V1.7의 HTTP 결제, Bazaar, 네이티브 MCP 동작은 모두 변경되지 않습니다:

• Base Sepolia는 기본 x402 네트워크로 유지되며 CDP 자격 증명 없이 https://x402.org/facilitator를 계속 사용합니다.

• Base mainnet은 명시적으로 선택하면 Coinbase의 인증된 CDP facilitator를 사용할 수 있습니다.

• 메인넷 시작에는 두 CDP API 자격 증명이 모두 필요하며, 유효하지 않은 자격 증명이나 facilitator 지원 누락 시 실패-폐쇄(fails closed) 방식으로 종료됩니다.

• /meta는 활성화된 테스트넷과 메인넷 결제 모드를 구분합니다.

• 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 결제 보호가 활성화되면 POST /fetch에 대한 PAYMENT-REQUIRED 헤더에는 url, max_chars, force_browser 입력 계약과 대표적인 성공 응답이 포함된 Bazaar 선언이 포함됩니다. /, /health, /meta는 계속 무료이며 Bazaar 메타데이터를 광고하지 않습니다.

MCP

원격 MCP 클라이언트는 Streamable HTTP를 사용하여 /mcp에 연결합니다. 서버는 정확히 하나의 도구를 노출합니다:

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

이 도구는 에이전트를 위해 공개 웹페이지를 읽고, 가져오고, 스크래핑하거나 추출하여 기존 SmartFetch 텍스트, Markdown, 링크 및 가져오기 메타데이터를 반환합니다. POST /fetch와 동일한 SSRF 검증, 실행기, 요청 시간 제한, 동시성 상한, 출력 상한, HTTP 가져오기 및 브라우저 폴백을 사용합니다. 공개 API로 HTTP 요청을 다시 보내지 않습니다.

x402가 활성화되면 결제되지 않은 tools/call은 네이티브 MCP x402 결제 챌린지를 반환합니다. 유효한 결제는 가져오기 전에 검증되고 도구 실행이 성공한 후 한 번 정산됩니다. 네트워크, 공개 수취인, 가격은 X402_NETWORK, X402_PAY_TO, X402_PRICE에서 가져옵니다. 판매자 개인 키나 지갑 비밀은 허용되거나 요구되지 않습니다.

결제되지 않은 MCP 결제 챌린지에는 전송 방식 streamable-http, 기존 입력 계약 및 대표적인 SmartFetch 출력이 포함된 fetch_webpage용 Bazaar 선언이 포함됩니다. 해당 결제 리소스는 mcp://tool/fetch_webpage로 유지됩니다. POST /fetch에 대한 기존 HTTP Bazaar 리소스는 별도이며 변경되지 않습니다.

루트 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은 명시적으로 선택해야 하며 Coinbase의 인증된 CDP facilitator를 사용합니다:

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

메인넷에는 두 CDP 자격 증명이 모두 필요합니다. 누락되었거나 유효하지 않거나 사용할 수 없는 자격 증명, 지원되지 않는 Base-mainnet 정확(exact) 결제 또는 facilitator/미들웨어 초기화 실패는 시작을 중단합니다. SmartFetch는 메인넷이 선택되면 무료 액세스나 테스트넷 facilitator로 폴백하지 않습니다. 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을 배포할 수 있습니다. 아웃바운드 HTTPS와 Chromium 프로세스 하나에 충분한 RAM을 제공하는 모든 Docker 호스트에서도 작동해야 합니다.

권장 초기 환경 변수:

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

배포 통과 기준은 5개의 강제 브라우저 요청을 포함하여 최소 18/20으로 유지됩니다.

결제 출시 상태

V1.8은 기존 Base Sepolia 및 Base mainnet 결제 구성을 유지합니다. 이 저장소 변경 자체는 MCP Registry에 게시하거나 서비스를 배포하거나 Railway 변수를 수정하지 않습니다. 활성 결제 네트워크는 X402_NETWORK로 제어됩니다: Base Sepolia의 경우 eip155:84532, Base mainnet의 경우 eip155:8453.