mcp-web-tools-server

AI 에이전트에게 웹 페이지를 가져오고 콘텐츠를 추출하는 실제 작동하는 도구를 제공하는 커스텀 Model Context Protocol (MCP) 서버입니다: 깔끔하게 읽을 수 있는 기사 텍스트, CSS 선택자에 의한 구조화된 데이터, 그리고 robots.txt 권한 확인.

MCP란 무엇인가?

MCP는 Anthropic이 처음 발표한 오픈 프로토콜로, AI 애플리케이션(예: Claude Desktop 또는 Claude Code)이 외부 도구 및 데이터 소스에 연결하는 방식을 표준화합니다. 모든 AI 앱이 자체 플러그인 형식을 만드는 대신, MCP 서버는 단순한 JSON-RPC 인터페이스를 통해 고정된 도구 집합(선택적으로 리소스와 프롬프트도)을 노출하며, MCP 호환 클라이언트는 동일한 방식으로 이를 발견하고 호출할 수 있습니다. 이 저장소는 그러한 서버 중 하나입니다. 작은 로컬 프로세스로 실행되며 stdio를 통해 MCP를 사용하므로, 어떤 MCP 클라이언트든 내부의 httpx, selectolax, trafilatura에 대해 전혀 알지 못해도 이 도구들을 나열하고 호출할 수 있습니다.

왜 유용한가?

기본 상태로는 LLM이 실제 웹 페이지를 가져올 수 없습니다. 이 서버는 작고 검증되었으며 범위가 명확한 도구 세트로 그 공백을 메웁니다. 에이전트는 기사에서 읽을 수 있는 텍스트를 뽑아내고, CSS 선택자로 페이지에서 특정 필드(가격, 제목, 태그, 페이지 구조에 따라 무엇이든)를 추출하며, 요청을 보내기 전에 해당 사이트의 robots.txt가 요청을 허용하는지 확인할 수 있습니다. 이는 범용 스크래핑 프레임워크라기보다 의도적으로 좁게 설계되었습니다. 올바르게 작동하고 예측 가능하게 실패하는 소수의 도구가, 때때로 제대로 작동하지 않는 넓은 표면보다 에이전트에게 더 유용하다는 이론에 기반합니다.

도구

fetch_and_extract(url: str) -> str

URL을 가져와서 스크립트, 스타일, 내비게이션, 광고, 푸터가 제거된 깔끔하고 읽기 쉬운 본문 텍스트를 반환합니다. 기사 추출에는 trafilatura를 사용하며, selectolax 기반의 단락 밀도 휴리스틱을 trafilatura가 확실하게 처리하지 못하는 페이지의 폴백으로 사용합니다.

extract_structured(url: str, css_selectors: dict) -> dict

URL을 가져와 CSS 선택자로 필드를 추출합니다. 예를 들면:

{"title": "h1", "price": ".price", "tags": ".tag-list a"}

반환:

{"title": "Trail Blazer 29 Mountain Bike", "price": "$1,249.00", "tags": ["mountain", "hardtail", "29er"]}

하나의 요소에 일치하는 선택자는 해당 텍스트를 반환하고, 여러 요소에 일치하면 텍스트 목록을 반환하며, 일치하는 것이 없으면 null을 반환합니다. 파싱은 selectolax로 수행됩니다.

check_robots_txt(url: str) -> dict

대상 사이트의 robots.txt를 가져와서 Python 표준 urllib.robotparser를 사용해 이 서버의 사용자 에이전트가 주어진 URL을 요청할 수 있는지 보고합니다. robots.txt가 없으면 권한이 실제로 부여되었다고 조용히 가정하지 않고 명시적으로 (robots_txt_found: false) 보고합니다.

스크래핑 예절은 사후 고려가 아니라 최우선 관심사여야 하므로 이 도구가 존재합니다. 에이전트(또는 이를 조종하는 사람)는 문제가 발생했을 때뿐만 아니라 가져오기 전에도 권한을 확인할 수 있어야 합니다.

설계 원칙

• 정직한 식별. 요청은 가짜 브라우저 UA가 아니라 이 도구를 식별하고 이 저장소로 연결되는 실제 User-Agent 문자열을 사용합니다.

• 제한된 요청. 모든 가져오기는 고정된 타임아웃(기본 10초)을 가지므로 느리거나 멈춘 서버가 전체 세션을 지연시킬 수 없습니다.

• robots.txt는 도구이지 조용히 강제되는 것이 아닙니다. check_robots_txt는 에이전트(또는 이를 조종하는 사람)가 스크래핑 전에 권한을 확인할 수 있도록 제공되지만, 현재 fetch_and_extract 또는 extract_structured를 자동으로 차단하지는 않습니다. 아래 제한 사항을 참조하세요.

• 잘못된 입력으로 인한 크래시 없음. 네트워크 오류, 타임아웃, 유효하지 않은 URL은 포착되어 깔끔한 오류 텍스트 또는 {"error": ...} 사전으로 반환되며, 서버 프로세스를 죽이는 처리되지 않은 예외로 끝나지 않습니다.

프로젝트 구조

mcp_web_tools/
  server.py        MCP server definition and the three tool entry points
  extractors.py     Pure HTML-parsing logic (no network), used for readable-text and CSS-selector extraction
  robots.py         robots.txt fetching and permission checking
  http_client.py    Shared httpx fetch helper: user agent, timeout, error handling
tests/
  test_extractors.py    Unit tests against local HTML fixtures, no network
  test_robots.py        Unit tests with the network call mocked out
  test_http_client.py   Unit tests for URL validation
  test_integration.py   Integration tests against live public sites, marked and run separately
  fixtures/              Static HTML used by the unit tests
scripts/
  test_client.py    Standalone script that launches the server and talks real MCP protocol to it

서버 실행

python -m venv venv
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

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

서버는 MCP 프로토콜을 사용해 stdio를 통해 통신합니다. 터미널에서 직접 실행하면 클라이언트가 연결되기를 기다리며 대기하기만 합니다. MCP 클라이언트(아래 참조) 또는 포함된 테스트 클라이언트 스크립트를 통해 사용하세요.

Claude Desktop 또는 Claude Code에서 MCP 서버로 구성하기

MCP 클라이언트의 서버 구성에 항목을 추가하세요. command는 venv의 Python 인터프리터를 가리키고 args는 모듈을 가리킵니다. Claude Desktop의 경우 이 구성은 claude_desktop_config.json에 들어갑니다:

{
  "mcpServers": {
    "web-tools": {
      "command": "C:\\path\\to\\mcp-web-tools-server\\venv\\Scripts\\python.exe",
      "args": ["-m", "mcp_web_tools.server"],
      "cwd": "C:\\path\\to\\mcp-web-tools-server"
    }
  }
}

macOS/Linux에서 command는 /path/to/mcp-web-tools-server/venv/bin/python이 됩니다.

Claude Code의 경우 다음을 실행하세요:

claude mcp add web-tools -- /path/to/mcp-web-tools-server/venv/bin/python -m mcp_web_tools.server

(해당하는 경우 Windows venv 경로로 대체하세요.) 또는 프로젝트의 .mcp.json에 동일한 항목을 추가하세요.

테스트 실행

단위 테스트는 로컬 HTML 픽스처에 대해 실행되며 네트워크에 접속하지 않습니다:

pytest

통합 테스트는 실제로 안정적인 공개 테스트 사이트(example.com 및 books.toscrape.com, 표준 공개 스크래핑 테스트/데모 대상)에 접속하며 기본 실행에서 제외됩니다. 네트워크에 접근할 수 있을 때 명시적으로 실행하세요:

pytest -m integration

또한 Python 함수를 직접 호출하는 대신 서버를 실제 하위 프로세스로 실행하고 실제 MCP 클라이언트/서버 프로토콜을 통해 구동하는 독립 실행형 스크립트도 있습니다:

python scripts/test_client.py

제한 사항 및 다음에 추가할 것

• JavaScript 렌더링 없음. 이 서버는 httpx로 원시 HTML을 가져옵니다. 콘텐츠를 클라이언트 측에서 렌더링하는 페이지(무거운 React/Vue SPA)는 유용한 결과를 거의 또는 전혀 반환하지 않습니다. Playwright를 감싸는 네 번째 도구로 헤드리스 브라우저 가져오기를 추가하는 것이 자연스러운 다음 단계지만, 실행 비용이 훨씬 더 무거워집니다.

• 속도 제한 없음. 각 도구 호출은 호출 시 한 번의 요청을 만듭니다. 에이전트가 동일한 호스트에 대해 빠르게 반복 호출하는 경우 내장된 도메인별 스로틀링이나 요청 큐가 없습니다. check_robots_txt는 사이트가 crawl_delay_seconds를 게시하면 이를 표시하지만, 현재 이를 강제하는 것은 없습니다.

• robots.txt는 권고 사항이지 강제 사항이 아닙니다. fetch_and_extract와 extract_structured는 가져오기 전에 check_robots_txt를 자동으로 참조하지 않습니다. 이는 이 버전의 의도적인 범위 결정입니다(에이전트가 먼저 check_robots_txt를 직접 호출해야 합니다). 그러나 허용되지 않은 가져오기를 자동으로 거부하는 더 엄격한 모드를 추가하는 것도 합리적일 것입니다.

• 가독성 휴리스틱은 기본적입니다. trafilatura가 확실한 결과를 생성하지 못할 때 사용되는 selectolax 폴백은 단순한 단락 밀도 점수 계산기입니다. 일반적인 기사 및 블로그 레이아웃에는 충분하지만, 비정형 페이지 구조에서는 특수 목적의 가독성 라이브러리보다 성능이 떨어집니다.

• 캐싱 없음. 모든 호출은 잠시 전의 동일한 URL이라도 다시 가져옵니다. 데모/포트폴리오 서버에는 괜찮지만, 더 많은 사용에는 이상적이지 않습니다.

• 실질적으로 단일 전송. 서버는 Claude Desktop과 Claude Code가 사용하는 stdio용으로 설정되어 있습니다. mcp SDK는 SSE와 streamable-HTTP 전송도 지원합니다. 이 서버를 로컬 하위 프로세스가 아닌 호스팅 서비스로 실행하려면 그 중 하나를 연결해야 합니다.