web-basics-mcp

에이전트를 위한 작고 신뢰할 수 있는 웹 도구입니다. API 키가 필요 없고 번들 인프라도 없습니다.

도구

fetch_url은 HTML 페이지와 Reddit 게시물의 경우 깔끔한 Markdown을, PDF의 경우 선택 가능한 텍스트를, text/Markdown/JSON/XML 응답의 경우 직접 콘텐츠를, PNG, JPEG, WebP, GIF 이미지의 경우 네이티브 MCP 이미지 콘텐츠를 반환합니다.

긴 텍스트는 제한된 청크 단위로 읽힙니다. 반환된 next_start_index를 사용하여 동일한 URL을 다시 호출하세요:

{
  "url": "https://example.com/long-page",
  "start_index": 8000,
  "max_length": 8000
}

성공적인 가져오기는 메모리에 5분간 캐시되므로 오프셋 읽기는 일반적으로 동일한 추출 문서를 사용합니다. 검색 결과는 2분간 캐시되어 에이전트 실행 중 동일한 SearXNG 작업이 반복되는 것을 방지합니다. 두 캐시 모두 크기가 제한되어 있고, 동시 중복 요청을 병합하며, 언제든지 폐기될 수 있습니다. 도구의 정확성은 이 캐시에 의존하지 않습니다.

Related MCP server: Basic MCP Tools

요구 사항

• Node.js 20.18.1 이상

• JSON 응답이 활성화된 기존 SearXNG 인스턴스

기본 URL을 환경 변수 또는 이 패키지의 .env 파일에 설정하세요:

SEARXNG_URL=http://127.0.0.1:8088

서버는 SearXNG를 사용할 수 없어도 시작되므로 fetch_url은 계속 사용할 수 있습니다. web_search 호출은 SearXNG에 연결 가능해질 때까지 명확한 연결 오류를 반환합니다.

설치

git clone https://github.com/yoloyash/web-basics-mcp.git
cd web-basics-mcp
npm install
npm run build

MCP 클라이언트가 stdio를 통해 build/index.js를 실행하도록 구성하세요. 예를 들어:

codex mcp add web-basics -- node /absolute/path/to/web-basics-mcp/build/index.js

도구 입력

web_search

{
  "query": "Model Context Protocol",
  "limit": 5
}

limit의 기본값은 5이며 1부터 10까지의 값을 허용합니다. 결과는 안정적인 형태 {link, title, snippet}을 사용합니다.

fetch_url

{
  "url": "https://example.com",
  "start_index": 0,
  "max_length": 8000
}

• start_index의 기본값은 0입니다.

• max_length의 기본값은 8000이며 최대 20000으로 제한됩니다.

• 텍스트 응답은 total_chars, returned_chars, truncated를 보고하며, 더 많은 콘텐츠가 남아 있을 경우 next_start_index도 보고합니다.

• HTML은 먼저 Defuddle을 사용하고, 게이트된 폴백으로 Mozilla Readability를 사용합니다. 응답은 선택된 extractor와 해당되는 경우 폴백 이유를 보고합니다.

• Defuddle의 선택적 네트워크 기반 추출기는 비활성화됩니다. 모든 원격 요청은 이 서버의 검증된 HTTP 경로 내에서 이루어집니다.

• Reddit 게시물 URL은 Reddit의 RSS 피드를 통해 가져오며, 게시물과 해당 피드에서 사용 가능한 댓글을 포함합니다. RSS에는 웹사이트보다 적은 댓글이 포함될 수 있습니다.

안전 및 제한 사항

• 공개 HTTP(S) URL만 허용됩니다.

• URL 자격 증명, 개인 호스트 이름, 개인 DNS 결과, 안전하지 않은 리디렉션은 거부됩니다.

• 각 리디렉션은 독립적으로 검증됩니다.

• 요청에는 타임아웃, 제한된 재시도, 응답 크기 제한, 안정적인 사용자 에이전트가 사용됩니다.

• 표준 응답 및 이미지는 5MiB로 제한되며, PDF는 15MiB로 제한됩니다.

• 가져오기 캐싱은 Cache-Control: no-store, no-cache, max-age=0을 준수합니다.

이 서버는 의도적으로 브라우저 자동화, JavaScript 렌더링, 크롤링, 인증, 쿠키, 프록시/VPN 라우팅 또는 답변 합성을 제공하지 않습니다.

개발

npm test
npm pack --dry-run

테스트는 공개 서비스를 반복적으로 쿼리하는 대신 저장된 픽스처와 로컬 스텁을 사용합니다.