에이전트(Agents)를 사용하여 개발하는 동안 저는 계속해서 동일한 문제에 직면했습니다:

페이지는 공개되어 있습니다. 브라우저는 이를 읽을 수 있습니다. 하지만 제 에이전트는 차단되거나, 리다이렉트(Redirect)되거나, 속도 제한(Rate-limited)에 걸리거나, 유용한 콘텐츠가 없는 껍데기뿐인 HTML을 전달받습니다.

이 분야에는 이미 재미있는 프로젝트인 insane-search가 있었습니다. 매우 영리하고 공격적이며 유용하지만, 원래의 워크플로우(Workflow)는 Claude Code를 중심으로 설계되어 있었습니다.

저는 일반적인 MCP 서버와 같이 어떤 MCP 호환 클라이언트(Client)라도 호출할 수 있는 수준의 공개 웹 회복탄력성(Public-web resilience)을 원했습니다.

그 결과 탄생한 것이 unlimited-search입니다.

flyingsquirrel0419 / unlimited-search

회복탄력성이 있는 공개 경로를 통해 공개 웹 페이지를 읽기 위한 MCP 서버 및 CLI.

unlimited-search

English | 한국어 | 中文 | 日本語 | Español

공개 페이지에서 사용 가능한 신호(Signal)로.

unlimited-search는 일반적인 직접 페치(Direct fetch)만으로는 충분하지 않을 때 공개 웹 콘텐츠를 읽기 위한 Python CLI 및 MCP 서버입니다. 이 도구는 플랫폼 공개 경로, 브라우저와 유사한 HTTP 정체성(Identities), 콘텐츠 폴백(Content fallbacks), 공개 아카이브 폴백, 그리고 미디어 메타데이터 추출 기능을 하나의 로컬 도구 뒤에 결합합니다.

이 도구는 공개 URL로부터 사용 가능한 텍스트가 필요한 에이전트(Agents) 및 자동화(Automation)를 위해 구축되었습니다. 로그인, 페이월(Paywalls), CAPTCHA, 프라이빗 네트워크(Private networks), 계정 제한, IP 차단 또는 액세스 제어(Access controls)를 우회하기 위한 용도가 아닙니다.

빠른 시작 (Quickstart)

전제 조건: Python 3.12 이상.

python -m pip install unlimited-search
unlimited-search read https://en.wikipedia.org/wiki/OpenAI --max-content-chars 800

이 명령은 페이지 content, verdict, 요청 metadata, 그리고 시도 기록인 trace를 포함한 JSON을 반환합니다.

MCP 클라이언트의 경우, 패키지를 설치하고 stdio 서버를 등록하세요:

{
  "mcpServers": {
    "unlimited-search": {
      "command": "unlimited-search"
      "args"

…

GitHub에서 보기

요약 (TL;DR)

unlimited-search는 다양한 공개 경로와 폴백(Fallbacks)을 통해 공개 웹 페이지를 읽기 위한 Python CLI 및 MCP 서버입니다.

주요 기능:

• 하나의 공개 URL 읽기
• 한 번의 MCP 호출로 여러 개의 공개 URL 읽기
• 페이지 접근이 어려운 이유 진단
• yt-dlp를 사용하여 공개 미디어 메타데이터 추출
• 공개 플랫폼 경로, 브라우저 방식의 HTTP 페칭(Fetching), 공개 아카이브, 피드(Feeds) 및 메타데이터 추출을 통한 폴백 수행

이 도구는 로그인, 페이월(Paywalls), CAPTCHA, 프라이빗 네트워크(Private networks), 계정 제한 또는 실제 액세스 제어(Access controls)를 우회하려고 시도하지 않습니다.

설치 (Install)

python -m pip install unlimited-search

그 다음 MCP 클라이언트에 추가하세요:

{
  "mcpServers": {
    "unlimited-search": {
...

MCP 클라이언트를 재시작하면 다음 도구들을 사용할 수 있습니다:

• read_public_url
• read_public_urls
• diagnose_access
• extract_media

빠른 테스트 (Quick test)

터미널에서 직접 사용할 수도 있습니다:

unlimited-search read https://example.com --max-content-chars 1000
unlimited-search diagnose https://example.com

출력값은 복구된 콘텐츠, 최종 URL, 판정(Verdict), 메타데이터, 그리고 시도된 작업의 추적(Trace) 정보가 담긴 JSON입니다.

제작 동기 (Why I built it)

대부분의 에이전트(Agents)는 텍스트가 컨텍스트(Context)에 들어오기만 하면 해당 텍스트를 바탕으로 추론하는 능력이 뛰어납니다.

문제는 텍스트를 가져오는 과정이 번거롭다는 점입니다.

현대의 공개 웹사이트들은 일관적이지 않습니다:

• 유용한 공개 API (Public APIs)를 제공하는 곳이 있는가 하면
• 거의 모든 것을 클라이언트 측 (Client-side)에서 렌더링하는 곳도 있습니다
• RSS 또는 Atom 피드 (Feeds)를 노출하는 곳도 있습니다
• Open Graph 또는 JSON-LD 메타데이터 (Metadata)는 있지만 HTML 내용이 빈약한 곳도 있습니다
• 브라우저와 유사한 TLS 식별 정보 (TLS identity)가 있어야만 작동하는 곳도 있습니다
• 공개 아카이브 스냅샷 (Archive snapshot)을 통해 읽는 것이 더 쉬운 곳도 있습니다
• 일부 미디어 페이지는 가공되지 않은 HTML (Raw HTML)이 아닌 메타데이터로 처리하는 것이 더 나은 경우도 있습니다

따라서 모든 URL이 동일하다고 가정하는 대신, unlimited-search는 계층화된 전략 (Layered strategy)을 시도합니다.

작동 방식

특정 URL에 대해, 리더(Reader)는 가장 침해성이 낮은 공개 경로를 우선적으로 시도합니다:

1. Reddit, X/Twitter, YouTube 메타데이터, Bluesky, Mastodon, Hacker News, Stack Overflow, Wikipedia, GitHub, npm, PyPI, Naver Blog, Google Scholar, Amazon 등을 포함한 사이트들을 위한 플랫폼별 공개 경로 (Platform-specific public routes).
2. 다양한 식별 정보 (Identities), URL 변형 (URL variants), 리퍼러 전략 (Referer strategies), 그리고 HTTP 전송 폴백 (HTTP transport fallback)을 사용한 브라우저와 유사한 HTTP 페칭 (HTTP fetching).
3. Jina Reader JSON, RSS/Atom 발견 (Discovery), 일반적인 피드 경로, OGP, JSON-LD, Schema.org, 그리고 Next.js 메타데이터와 같은 콘텐츠 폴백 (Content fallbacks).
4. Wayback 및 archive.today/archive.ph의 최선 노력(Best-effort) 스냅샷을 통한 공개 아카이브 폴백 (Public archive fallbacks).
5. 공개 미디어 URL에 대한 yt-dlp를 통한 미디어 메타데이터 추출 (Media metadata extraction).

모든 결과에는 다음과 같은 판정 (Verdict)이 포함됩니다:

• strong_ok: 신뢰도가 높은 공개 경로가 성공적으로 작동함
• weak_ok: 콘텐츠가 복구되었으나, 부분적이거나 폴백 기반일 수 있음
• suspect_ok: 유용한 것이 발견되었으나, 호출자가 이를 검사해야 함
• 차단됨 (Blocked), 안전하지 않음 (Unsafe), 로그인 전용 (Login-only), CAPTCHA, 프라이빗 네트워크 (Private-network), 또는 사용 불가능한 결과에 대한 실패 판정

MCP 호출 예시

MCP 클라이언트에게 다음과 같이 요청할 수 있습니다:

Use unlimited-search to read this public URL and summarize the page:

내부적으로 모델은 다음과 같이 호출할 수 있습니다:

{
  "url": "https://example.com",
  "max_content_chars": 4000
...

그러면 단순히 조용히 실패하는 것이 아니라, 콘텐츠와 함께 추적 정보 (Trace)를 돌려받게 됩니다.

일반적인 페치 (Fetch)와 무엇이 다른가요?

일반적인 페치는 다음과 같이 묻습니다:

이 URL을 GET 할 수 있나요?

unlimited-search는 다음과 같이 묻습니다:

이 URL에서 유용한 텍스트를 얻을 수 있는 정당한 공개 경로(public route)가 있나요?

에이전트 워크플로 (Agent workflows)에서는 이 차이가 중요합니다.

직접적인 HTML 페치 (Fetch)가 좋지 않다면, 도구는 공개 API (Public API)를 시도할 수 있습니다. 페이지에 메타데이터 (Metadata)는 풍부하지만 콘텐츠가 적다면, 메타데이터를 추출할 수 있습니다. 라이브 페이지가 불안정하다면, 공개 아카이브 (Public archive) 경로를 시도할 수 있습니다. 페이지가 미디어 (Media)라면, 거대한 HTML 껍데기를 쏟아내는 대신 구조화된 미디어 메타데이터를 반환할 수 있습니다.

목표는 마법 같은 기능을 제공하는 것이 아닙니다. 목표는 실용적인 것이 됩니다.

안전 경계 (Safety boundary)

이 점이 중요합니다: unlimited-search는 **공개 콘텐츠 리더 (Public-content reader)**입니다.

대상(Target)이 다음과 같은 사항을 요구할 경우 중단하도록 설계되었습니다:

• 인증 (Authentication)
• 결제 (Payment)
• CAPTCHA
• 프라이빗 네트워크 액세스 (Private network access)
• 계정별 권한 부여 (Account-specific authorization)
• 강력한 어뷰징 방지 우회 (Hard anti-abuse bypassing)

또한 기본적으로 프라이빗 (Private), 루프백 (Loopback), 링크 로컬 (Link-local), 멀티캐스트 (Multicast), 예약된 (Reserved) 및 메타데이터 서비스 (Metadata-service) 대상을 거부합니다.

이러한 경계 덕분에 이 도구는 우회 도구 (Bypass tool)로 변질되지 않으면서도 에이전트에게 유용하게 쓰일 수 있습니다.

insane-search에서 얻은 영감

저는 insane-search의 정신을 좋아합니다: 에이전트 워크플로 (Agent workflows)를 위해 공개 웹 읽기를 덜 취약하게 만드는 것 말이죠.

차이점은 패키징 (Packaging)과 인터페이스 (Interface)에 있습니다.

워크플로를 하나의 에이전트 환경에 묶어두는 대신, unlimited-search는 그 기능을 일반적인 MCP 서버로 노출합니다:

• pip로 설치
• stdio를 통해 실행
• 모든 MCP 호환 클라이언트 (MCP-compatible client)에서 호출 가능
• 트레이스 (Traces) 및 판결 (Verdicts) 검사
• MCP가 필요하지 않을 때는 CLI로 사용

이를 통해 다양한 로컬 에이전트 설정에 더 쉽게 연결할 수 있습니다.

사용해 보기

python -m pip install unlimited-search
unlimited-search read https://dev.to --max-content-chars 1500

GitHub:

https://github.com/flyingsquirrel0419/unlimited-search

PyPI:

https://pypi.org/project/unlimited-search/

만약 이 도구가 또 다른 취약한 페이지 페칭 (page-fetching) 도구를 만드는 수고를 덜어준다면, GitHub 스타를 눌러 프로젝트가 더 많이 알려지도록 도와주세요.

그리고 만약 특이한 공개 사이트를 대상으로 테스트해 보신다면, 무엇이 작동했고 무엇이 실패했는지, 그리고 다음에 어떤 폴백 (fallback) 기능이 추가되어야 하는지에 대해 꼭 듣고 싶습니다.