Guion Web

Guion Web은 Node.js 웹 리서치 툴킷입니다. CLI, stdio MCP 서버, Pi 확장, DeepSeek Harness(DSH) 통합을 통해 Exa 또는 Brave 검색, Context7 라이브러리 문서 조회, Sourcegraph 공개 코드 검색, 그리고 두 가지 페이지 가져오기 백엔드를 제공합니다. 이 백엔드는 지원되는 호스트에서 클라이언트 렌더링 페이지를 위한 직접 HTML-to-Markdown 추출과 명시적 agent-browser 렌더링입니다.

설치 및 구성

Node.js 20 이상이 필요합니다. @guionai/web은 의도적으로 web 실행 파일과 stdio MCP 서버만 노출합니다. 루트 JavaScript 또는 TypeScript SDK는 제공하지 않습니다. 호스트 통합에는 Pi 또는 DSH 패키지를 사용하세요.

npm install --global @guionai/web
# or run without a global install
npx @guionai/web --help

검색에는 하나의 공급자 자격 증명이 필요합니다. 둘 다 있으면 기본적으로 Exa가 선택됩니다. --provider exa 또는 --provider brave로 공급자를 명시적으로 선택하세요. Context7은 키가 없으면 익명으로 동작합니다.

export EXA_API_KEY="..."
# or
export BRAVE_API_KEY="..."
# optional, for authenticated Context7 requests
export CONTEXT7_API_KEY="..."

명령 인수에 자격 증명을 넣거나 커밋하지 마세요. CLI는 이러한 환경 변수를 직접 읽습니다. dotenv 파일이나 이전 애플리케이션 구성 경로는 자동으로 로드하지 않습니다.

Related MCP server: FireScrape MCP Server

CLI

web는 기본적으로 사람이 읽을 수 있는 출력을 제공합니다. --json을 추가하면 stdout에 JSON 문서가 정확히 하나 생성됩니다. 자동화에 유용합니다.

web search --provider exa -- "Node AbortSignal"
web fetch https://example.com/article --tree
web fetch https://example.com/article --section introduction
web docs resolve react
web docs fetch /facebook/react --topic hooks --tokens 2000
web sgraph --count 10 -- "repo:^github\\.com/nodejs/node$ AbortSignal"

하이픈으로 시작하는 검색어나 Sourcegraph 질의 앞에 --를 사용하세요. fetch는 --full, --tree, --section을 지원합니다. 긴 추출 문서는 기본적으로 heading 트리를 사용하므로 이후 요청에서 안정적인 section ID를 가져올 수 있습니다.

MCP

동일한 자격 증명 환경에서 stdio 서버를 실행하세요:

web mcp
# Pin search selection for the lifetime of this MCP process:
web mcp --provider brave

서버는 search, fetch, docs_resolve, docs_fetch, source_search라는 다섯 가지 읽기 전용 도구를 노출합니다. stdout은 MCP 프로토콜 메시지 전용입니다. 진단 내용은 stderr로 전달됩니다. 클라이언트 렌더링 페이지의 경우 render: "agent-browser"와 정수 waitMs로 fetch를 명시적으로 호출하세요. 이 선택적 재시도는 호스트에 설치된 실행 파일이 필요하며 자동으로 실행되지 않습니다.

Pi

독립적으로 번들된 Pi 확장을 설치하세요:

pi install npm:@guionai/pi-web

web_search, web_fetch, web_docs, web_source_search를 등록하며 번들된 코어는 프로세스 내에서 호출합니다. Pi와 TypeBox는 호스트가 제공하는 peer 의존성입니다. CLI 실행 파일이나 MCP 설정은 필요하지 않습니다. web_fetch는 기본적으로 직접 fetch를 사용하며, 호스트가 선택적 실행 파일을 제공하면 정수 waitMs와 함께 render: "agent-browser"를 명시적으로 사용할 수 있습니다.

DSH

기존 Web 프로필에 DSH 번들을 설치하세요:

dsh plugin --profile web add @guionai/dsh-web

포함된 프로필 패치는 기본 PTC 웹 검색을 선택한 Exa 또는 Brave 공급자를 통해 라우팅합니다. 설정 UI는 공급자 선택을 저장하고 네임 스페이스화된 쓰기 전용 자격 증명을 관리합니다. Fetch, 문서, 그리고 Sourcegraph 도구도 프로세스 내에서 실행됩니다. 호스트 DSH 패키지와 React는 DSH가 제공하는 peer 의존성입니다. web_fetch는 기본적으로 직접 fetch를 사용하며, 선택적 실행 파일을 제공하는 호스트에서는 정수 waitMs와 함께 render: "agent-browser"를 명시적으로 사용할 수 있습니다.

페이지 가져오기 백엔드

web fetch에는 두 가지 백엔드가 있습니다. 기본값인 fetch는 Node fetch, linkedom, Defuddle을 사용해서 정적, SSR 및 사전 렌더링된 페이지에서 HTML을 Markdown으로 직접 추출합니다. agent-browser는 별도로 설치한 호스트 실행 파일을 통해 클라이언트 측를 렌더링합니다. 기본적으로 직접 fetch가 사용되며, agent-browser는 필요할 때 명시적으로 선택하세요. 구현은 절대 자동으로 fallback하지 않습니다:

web fetch https://example.com/app --render=agent-browser --wait=2000
# If it is still incomplete, retry explicitly with more time, or abandon it:
web fetch https://example.com/app --render=agent-browser --wait=10000

--render=agent-browser와 사용할 때 --wait는 필수이며 --wait=0도 허용하고, 0~30,000밀리초 사이의 정수만 허용됩니다. 직접 fetch 요청은 --wait을 제공하면 안 됩니다. render: "agent-browser" 및 필수 waitMs 필드는 MCP fetch, Pi web_fetch, DSH web_fetch 도구에도 동일하게 있습니다. 직접 fetch가 실패한 경우 구조화된 힌트 javascript_rendering_may_be_required와 2,000 ms 제안을 반환할 수 있습니다. 이 경우 에이전트가 대기 시간을 늘려 재시도할지, 페이지를 포기할지 결정합니다.

렌더링은 선택적인 호스트 기능입니다. 사용하기로 했거나 agent-browser를 호스트에 별도로 설치하세요:

npm install --global agent-browser
agent-browser install

agent-browser install은 자체 브라우저 런타임을 관리합니다. Guion 패키지는 브라우저를 실행하거나 번들로 포함하지 않으며, 브라우저 자격 증명을 재사용하지 않습니다. 호환되는 실행 파일은 셸 없이 PATH에서 직접 실행 가능해야 합니다. 렌더러는 macOS와 Linux 호스트에서 지원됩니다. agent-browser가 없는 경우에도 직접 fetch는 계속 사용 가능하고 세 npm 패키지는 계속 설치 가능합니다.

렌더링된 세션은 새로 시작되고 비영속적입니다. 시작 전에 대상은 HTTP(S) 공개 호스트명 또는 주소여야 합니다. 그러면 브라우저 허용 목록에는 요청한 호스트명, *.<requested-hostname>(대상의 하위 도메인 포함), 그리고 다음 고정된 CDN 목록만 포함됩니다:

• cdn.jsdelivr.net

• pkg.com

• cdnjs.cloudflare.com

• ajax.googleapis.com

• fonts.googleapis.com

• fonts.gstatic.com

• esm.sh

호출자는 이 목록을 확장할 수 없습니다. Redirects, API, frames, workers, sockets 또는 알 수 없는 도메인에 대한 다른 종속성은 render_domain_not_allowed로 안전하게 차단됩니다. waitMs를 늘려도 문제가 해결되지 않습니다. First-party 또는 공용 CDN 도메인이 누락된 https://github.com/guion/web/issues/new에 페이지 URL과 차단된 도메인을 포함하여 보고하세요. 콘솔 자격 증명이나 페이지의 비밀 정보는 포함하지 마세요.

이것은 브라우저 수준의 호스트명 경계이며 완전한 SSRF 방어거나 호스트의 이그레스 방화벽은 아닙니다. 레거시 주소 및 DNS로 확인된 Private/예약 대상은 시작 전에 거부되지만, 허용된 악성 호스트명은 검증 후 DNS 응답을 Private 주소로 변경할 수 있습니다(DNS rebinding). 여기서는 OS 수준의 호스트-egress 격리가 없으므로, 커넥션 별 SSRF 필터 프록시 또는 컨테이너/microVM egress 격리 없이 민감하지 않는 임의의 URL이 있는 public 혹은 multi-tenant 서비스에서 이 백엔드를 사용하지 마십시오.

개발

pnpm workspace입니다. 의존성을 설치하고 CI가 사용하는 로컬 게이트를 그대로 실행하세요:

pnpm install --frozen-lockfile
pnpm format:check
pnpm typecheck
pnpm build
pnpm test
pnpm test:release
pnpm test:pack

test:release는 임시 매니페스트를 사용해 태그-버전 동기화를 전 test 합니다. test:pack은 각 공개 패키지의 압축 설치 또는 호스트 로딩 계약을 테스트가 소유한 임시 디렉터리에서 실행합니다.

릴리스

v<semver> 태그는 세 가지 공개 패키지의 릴리스 원본(source of truth)입니다: @guionai/web, @guionai/pi-web, @guionai/dsh-web. 릴리스 사전 점검은 해당 태그의 체크아웃 장애 목록을 먼저 동기화하고, 형식 맞춤, 타입 검사, 빌드, 테스트, 릴리스 버전 검증, 패키지 스모크 테스트를 끝낸 뒤 게시를 시작합니다.

세 개의 인디펜던트한, non-fail-fast protected npm Environment 매트릭스 셀은 각각 하나의 npm 패키지를 npm Trusted Publishing 및 provenance 방식으로 게시합니다. 동기화된 버전은 안정적인 SemVer의 경우 npm latest 태그, 프리릴리리스인 경우 beta 태그를 선택합니다. 세 셀이 모두 성공하면 워크플로는 생성된 릴리스 노트와 소스 아카이브가 포함된 GitHub Release를 만듭니다. 바이너리나 플랫폼 아카이브는 게시되지 않습니다.

게시가 부분 실패하면 GitHub Actions의 Re-run failed jobs를 사용하세요. Re-run all jobs는 사용하지 마세요. npm 버전은 불변이므로 이미 게시된 성공 작업을 다시 실행할 수 없습니다.

First beta bootstrap 및 Trusted Publishing

이 작업은 릴리스 커밋이 병합된 뒤, routine OIDC 릴리스를 켜기 전에 한 번만 수행합니다.

1. 의도된 커밋 브랜치에서 소스 항목을 가져와 0.1.0-beta.1 같은 동기화된 beta 버전을 선택합니다.

2. @guionai publish 권한과 2FA가 있는 관리자 npm 계정으로 node을 실행합니다. node scripts/sync-version.mjs 0.1.0-beta.1, 빌드, 테스트, pack, node scripts/release-dry-run.mjs 0.1.0-beta.1을 실행하세요.

3. 각 공개 패키지 디렉터리에서 synchronized beta를 발행합니다. npm publish --access public --tag beta 를 사용하세요. 이 부트스트랩은 관리자 자격 증명으로 인증하며, 프로비넌스를 GitHub OIDC 릴리스 작업 밖으로 전달하지 마세요.

4. npm 패키지 설정에서 @guionai/web, @guionai/pi-web, @guionai/dsh-web 각각에 대해 GitHub Trusted Publisher 관계를 하나씩 만드세요. 각 관계는 저장소 guionai/web, workflow .github/workflows/release.yaml, 그리고 보호된 npm Environment를 대상으로 해야 합니다.

5. npm에서 세 관계와 게시 접근 정책을 모두 확인하고, 이후 일반 게시 workflow를 시작/태그합니다. 이 workflow는 npm 로그 없이 GitHub OIDC를 사용하며 모든 정상 게시에 provenance를 요청합니다.

버전을 덮어쓰거나 unpublish하지 마세요. GitHub Release가 부분 비실패 면, 실패한 셀만 다시 실행하세요.