Groundlane

English | 繁體中文

AI 에이전트를 위한 신뢰할 수 있는 웹 접근 계층.

Groundlane은 AI 에이전트에게 공개 웹에 대한 통제된 접근을 제공하는 오픈소스, 벤더 중립적 원격 MCP 서버입니다. 검색, 검색 결과 가져오기, 결정적 추출을 위한 하나의 안정적인 인터페이스를 제공하며, 검색을 교체 가능한 공급자로 라우팅하고, 어려운 Markdown 읽기는 선택적 Jina Reader를 거친 후 격리된 로컬 또는 Browserless 브라우저를 사용하기 전에 에스컬레이션합니다.

[!IMPORTANT] Groundlane은 초기 프리뷰입니다. 도구 계약과 배포 모델은 아직 발전 중이며, 현재 릴리스를 호스팅 서비스나 범용 안티봇 우회 수단으로 취급하지 마십시오.

왜 Groundlane인가?

• 모델 중립적: 모델 벤더의 내장 웹 도구에 의존하는 대신 모든 Streamable HTTP MCP 클라이언트를 연결할 수 있습니다.

• 공급자 중립적: 하나의 정규화된 결과 계약 뒤에서 월간 무료 할당량이 반복되는 검색 API 전반에 걸쳐 라우팅합니다.

• HTTP 우선, 필요할 때만 브라우저: 일반적인 읽기는 빠르게 유지하고 Chromium은 JavaScript, 대기 조건, 지원되는 폴백 신호를 위해 예약합니다.

• 결정적 추출: CSS 선택자로 필드를 선택하고 암시적 LLM 단계 없이 구조화된 JSON을 수신합니다.

• 보안 우선: MCP 엔드포인트를 인증하고 URL, 리디렉션, 네트워크, 마감 시간, 바이트, 출력, 동시성 제한을 적용합니다.

• 자체 통제 배포: Cloudflare Workers 및 Containers를 포함한 자체 환경에서 컨트롤 플레인과 브라우저 워크로드를 실행합니다.

Related MCP server: agentfetch

MVP 도구

브라우저 자동화는 Groundlane Browser라고 하는 내부 구현 세부 사항입니다. Groundlane은 MVP에서 영구 브라우저 세션을 노출하지 않습니다.

빠른 시작

사전 요구 사항

• Node.js 22 이상

• pnpm 10

• 브라우저 폴백용 Chromium

• web_search를 사용하려면 월간 무료 검색 공급자 키가 하나 이상 필요합니다 (Tavily, Exa, Parallel, Browserbase, Brave, Firecrawl 또는 SerpApi)

로컬에서 실행

이 저장소를 클론한 후 다음을 실행합니다:

pnpm install
pnpm exec playwright install chromium
cp .env.example .env
set -a
source .env
set +a
pnpm dev

.env에 강력한 GROUNDLANE_AUTH_TOKEN을 설정합니다. 검색을 활성화하려면 지원되는 공급자 키를 하나 이상 추가합니다. 로컬 서버는 구성된 PORT에서 수신 대기하며 다음을 제공합니다:

• POST /mcp — 인증된 Streamable HTTP MCP 엔드포인트

• GET /healthz — 프로세스 활성 상태

• GET /readyz — Container 연결 가능성 및 서비스 구성 준비 상태

MCP 클라이언트 연결

서버 URL과 bearer 토큰으로 Streamable HTTP MCP 클라이언트를 구성합니다. 클라이언트 구성 형태는 다르지만 연결 값은 다음과 같습니다:

URL: http://localhost:8080/mcp
Authorization: Bearer <GROUNDLANE_AUTH_TOKEN>

토큰을 쿼리 문자열에 넣거나 소스 제어에 커밋하지 마십시오.

서버가 실행 중인 상태에서 다른 셸을 열고 동일한 .env를 로드한 후 MCP 핸드셰이크와 공개 HTTP 경로를 확인합니다:

set -a
source .env
set +a
pnpm smoke

브라우저 경로를 포함하려면 GROUNDLANE_SMOKE_BROWSER=1을 설정합니다.

구성

Groundlane은 환경 변수에서 구성을 읽습니다. 전체 로컬 템플릿은 .env.example을 참조하십시오.

검색 자격 증명이 없어도 web_fetch 또는 web_extract가 작동하지 않는 것은 아닙니다. 다만 해당 검색 공급자를 사용할 수 없게 될 뿐입니다.

월간 예산은 재시도 가능한 실패를 포함한 시도된 공급자 요청을 계산하며, 실행 중인 Groundlane 인스턴스가 구성된 상한 이후에 공급자를 선택하지 못하게 합니다. 의도적으로 보수적으로 설정되어 있지만 청구의 진실은 아닙니다: Containers는 재시작되고, 여러 인스턴스는 카운터를 공유하지 않으며, 일부 공급자는 가변 크레딧을 청구합니다. 공급자 측 지출 한도를 활성화된 상태로 유지하고 실제 플랜에 맞게 예산을 재정의하십시오.

아키텍처

MCP client
    |
    v
Cloudflare Worker / Node HTTP edge
    |  authentication, limits, request identity
    v
tool registry
    |-- web_search  -> monthly-free provider router (7 adapters)
    |-- web_fetch   -> safe HTTP -> optional Jina Reader -> browser fallback
    `-- web_extract -> fetch pipeline -> deterministic DOM extraction

핵심 정책과 계약은 공급자나 브라우저 런타임에 의존하지 않습니다. 어댑터는 좁은 인터페이스 뒤에 있습니다. 브라우저 백엔드는 Container 로컬 Playwright 또는 Browserless /content일 수 있습니다. engine 및 backend 출력 필드는 공개 MCP 도구를 변경하지 않고 어떤 경로가 결과를 생성했는지 공개합니다. 호스팅 백엔드는 요청된 공개 URL을 수신하므로 기본값이 아닌 옵트인 방식입니다.

구성 요소 경계, 요청 흐름 및 설계 결정은 아키텍처를 읽으십시오.

보안

웹 검색은 SSRF에 민감한 기능입니다. Groundlane은 사용자 URL, 리디렉션, 브라우저 하위 리소스 및 검색 공급자 URL을 신뢰할 수 없는 것으로 취급합니다. 배포 시 인증을 활성화된 상태로 유지하고, 아웃바운드 네트워크 정책을 사용하며, 기본 리소스 제한을 유지해야 합니다.

이 프로젝트는 범용 CAPTCHA 해결, 보이지 않는 자동화 또는 권한이 없는 콘텐츠에 대한 접근을 약속하지 않습니다. 운영자는 대상 사이트의 이용 약관, robots 정책, 개인정보 보호 의무 및 적용 법률에 대한 책임이 있습니다.

보안 모델 및 비공개 취약점 보고 절차는 SECURITY.md를 참조하십시오.

배포

의도된 프로덕션 토폴로지는 Cloudflare Worker를 공개 컨트롤 플레인으로, Cloudflare Container를 Node/Playwright 브라우저 워크로드로 사용합니다. 사전 요구 사항, 비밀, 배포 단계 및 검증은 Cloudflare에 배포를 참조하십시오.

로드맵

• 벤더 중립적 web_fetch, web_search 및 결정적 web_extract 표면 정의

• 출처 정보가 포함된 옵트인 Jina Reader 및 Browserless 검색 백엔드 추가

• MCP 계약 안정화 및 호환성 픽스처 게시

• Cloudflare Worker + Container 배포 및 운영 텔레메트리 강화

• 캐시 어댑터 및 공급자 상태/비용 인지 라우팅 추가

• 명시적 예산이 있는 옵트인 배치/크롤링 프리미티브 추가

• 상태 저장 브라우저 세션을 별도의 수명 주기 안전 기능으로 평가

로드맵은 방향성을 제시할 뿐 릴리스 약속이 아닙니다. 현재 범위의 근거는 연구 아카이브를 참조하십시오.

문서

• 아키텍처

• MVP 제품 요구 사항

• Cloudflare 배포

• 보안 정책

• 기여

• 연구 아카이브

기여

이슈와 풀 리퀘스트를 환영합니다. 기여 전에 CONTRIBUTING.md와 행동 강령을 읽으십시오. 보안 취약점은 SECURITY.md에 설명된 대로 비공개로 보고해야 합니다.

라이선스

Groundlane은 Apache License 2.0에 따라 라이선스가 부여됩니다.