Agent Bridge

개요

Agent Bridge는 AI 에이전트(Claude Code, Cursor, Cowork 등)가 Web2MD Chrome extension을 원격으로 제어하여 URL을 일괄 변환할 수 있게 해줍니다 — 특히 서버 측 API 접근을 차단하는 Reddit, JS 렌더링 페이지, 로그인 보호 페이지에 유용합니다. Web2MD API(Reddit이 차단하는)를 호출하는 대신, AI 에이전트는 Native Messaging을 통해 로컬 Chrome extension에 명령을 전송합니다. Extension은 실제 브라우저 세션(쿠키와 로그인 상태 포함)을 사용해 백그라운드 탭에서 각 페이지를 열고, 콘텐츠를 추출해 Markdown으로 변환한 뒤 결과를 반환합니다.

Agent Bridge를 사용하려면 PRO 플랜과 컴퓨터에 설치된 native messaging host가 필요합니다. Extension은 Chrome에서 열려 있어야 합니다.

아키텍처

AI Agent ←MCP/stdio→ MCP Server ←TCP:12315→ Native Host ←NM→ Chrome Extension → Any Website

구성 요소	역할
AI Agent	Claude Code, Cursor, Cowork — MCP 도구를 호출
MCP Server	MCP 도구 호출을 TCP 메시지로 변환
Native Host	TCP와 Chrome Native Messaging 사이를 중계
Chrome Extension	탭을 열고 HTML을 추출해 Markdown으로 변환

모든 통신은 로컬에서 이루어집니다 — 어떤 데이터도 사용자의 컴퓨터를 벗어나지 않습니다. Native Host는 localhost:12315에서만 대기합니다.

설정

1단계: MCP Server 빌드

cd packages/mcp-server
pnpm build

2단계: Native Messaging Host 설치

cd packages/mcp-server
./install.sh <your-extension-id>

개발자 모드를 켠 상태에서 chrome://extensions에서 Extension ID를 찾을 수 있습니다. Web2MD를 찾아 ID 문자열(예: ijmgpkkfgpijifldbjafjiapehppcbcn)을 복사하세요.

설치 후에는 반드시 Chrome을 완전히 종료(Mac에서 Cmd+Q)한 뒤 다시 열어야 합니다. Chrome은 Native Messaging manifest를 시작 시점에만 읽기 때문에, extension을 다시 로드하는 것만으로는 충분하지 않습니다.

설치 스크립트는 다음을 수행합니다.

Host 파일을 ~/.web2md/에 복사(~/Desktop의 macOS TCC 제한 회피)
node의 절대 경로를 확인(Chrome은 최소한의 PATH로 실행되므로)
NM manifest를 Chrome의 NativeMessagingHosts 디렉터리에 작성

3단계: MCP 설정

Claude Code
Cursor
Claude Desktop

~/.claude/settings.json에 추가하세요.

{
  "mcpServers": {
    "web2md-agent": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

~/.cursor/mcp.json에 추가하세요.

{
  "mcpServers": {
    "web2md-agent": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

Claude Desktop 설정에 추가하세요.

{
  "mcpServers": {
    "web2md-agent": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

4단계: 확인

Chrome에서 chrome://extensions를 열고 Web2MD의 “Service Worker” 링크를 클릭해 콘솔을 확인하세요.

[Web2MD] Service worker started
[Web2MD] Connected to native host
[Web2MD] Native host TCP relay ready on port 12315

이 세 줄이 보이면 Agent Bridge가 정상 작동하는 것입니다.

사용 가능한 도구

agent_convert

Chrome extension을 사용해 단일 URL을 변환합니다.

매개변수	타입	설명
`url`	string	변환할 URL

반환값: 제목, 원본 URL, 단어 수, 읽는 시간이 포함된 Markdown 콘텐츠. 적합한 용도: Reddit 스레드, 로그인 보호 페이지, JS 렌더링 사이트.

agent_batch_convert

최대 50개의 URL을 일괄 변환합니다. URL은 순차적으로 처리됩니다 — extension이 각 페이지를 백그라운드 탭에서 열고, 콘텐츠를 추출한 뒤 탭을 닫고 다음 URL로 넘어갑니다.

매개변수	타입	설명
`urls`	string[]	변환할 URL 배열(최대 50개)

반환값: 완료되는 대로 스트리밍되는 URL별 결과와 요약. 적합한 용도: 리서치 워크플로우 — Reddit 스레드, HN 토론, 경쟁사 페이지를 일괄 변환해 AI 분석에 활용.

성공적으로 변환된 모든 항목은 AI가 생성한 요약 및 태그와 함께 Dashboard History에 자동으로 저장됩니다.

사용 예시

Reddit 스레드 변환

사용자: 이 Reddit 스레드를 Markdown으로 변환해줘: https://www.reddit.com/r/LangChain/comments/1siwh6q/…Agent: (agent_convert 호출) 법률 문서에 대한 RAG 정확도를 논의하는 댓글 7개가 포함된 변환된 스레드입니다…

리서치를 위한 일괄 변환

사용자: 이 Reddit URL 5개를 일괄 변환하고 핵심 내용을 요약해줘.

Agent: (agent_batch_convert 호출) URL 5개 중 5개를 성공적으로 변환했습니다. 핵심 내용은 다음과 같습니다…

로그인 보호 페이지 변환

사용자: 회사 내부 위키 페이지 https://wiki.internal.com/architecture 를 변환해줘Agent: (agent_convert 호출) Chrome에서 해당 사이트에 로그인되어 있어서 전체 내용을 추출할 수 있었습니다…

지원 사이트

Agent Bridge는 extension과 동일한 16개 사이트별 추출기를 사용합니다.

사이트	방식	탭 필요 여부
Reddit	JSON API	불필요
Hacker News	Algolia API	불필요
YouTube	Transcript API	불필요
arXiv	HTML scraping	불필요
Twitter/X	DOM extraction	필요
GitHub Issues/PRs	REST API	불필요
Medium	DOM extraction	필요
Substack	DOM extraction	필요
Wikipedia	DOM extraction	필요
Stack Overflow	SE API	불필요
기타 모든 사이트	Full page HTML	필요

탭이 “불필요”로 표시된 사이트는 API 호출을 통해 변환되어 더 빠르고 안정적입니다. 나머지는 백그라운드 탭을 사용합니다.

문제 해결

'Native host not installed' 또는 'not found' 오류

Chrome이 NM manifest를 아직 불러오지 않은 상태입니다. Chrome을 완전히 종료(Cmd+Q)한 뒤 다시 여세요. Extension만 다시 로드하는 것으로는 충분하지 않습니다.

'Native host has exited'가 즉시 발생

Chrome이 host 스크립트를 실행하지 못하는 상태입니다. 흔한 원인은 다음과 같습니다.

node를 찾을 수 없음 — 절대 경로를 사용하는 ./install.sh를 다시 실행하세요
Host가 TCC 보호 디렉터리(~/Desktop, ~/Documents)에 있음 — 설치를 다시 실행해 ~/.web2md/로 이동하세요

MCP에서 'Agent connection error' 발생

Native Host TCP server가 실행되고 있지 않습니다. 다음을 확인하세요.

Chrome이 열려 있는지
Web2MD extension이 로드되어 있는지
Service Worker 콘솔에 “TCP relay ready on port 12315”가 표시되는지

'Failed to extract content from the page' 오류

Extension이 로그인되어 있지 않은 상태입니다. Chrome에서 Web2MD 팝업을 열고 PRO 계정으로 로그인하세요.

'Tab load timeout' 오류

대상 페이지 로딩이 너무 오래 걸리는 경우입니다. 느린 사이트에서는 정상적인 현상입니다. Extension은 탭당 최대 15초까지 대기합니다. Reddit은 JSON API 추출기를 사용해 탭이 필요 없으므로, Reddit에서 타임아웃이 발생한다면 대개 게시물 URL이 유효하지 않은(404) 경우입니다.

Dashboard History에 변환 결과가 나타나지 않아요

History 저장 기능을 사용하려면 extension이 PRO 계정으로 로그인되어 있어야 합니다. 저장은 fire-and-forget 방식이라 API 호출이 조용히 실패하면 변환 결과가 나타나지 않습니다. 인증 토큰이 유효한지 확인하세요.

MCP Server와의 차이점

기능	MCP Server (`convert_url`)	Agent Bridge (`agent_convert`)
실행 위치	서버 측 API 호출	사용자의 로컬 Chrome 브라우저
Reddit 지원	❌ Reddit에 의해 차단됨	✅ 실제 브라우저 세션 사용
로그인 보호 페이지	❌ 접근 불가	✅ 사용자의 쿠키 사용
JS 렌더링 페이지	❌ JavaScript 미지원	✅ 완전한 Chrome 렌더링
속도	더 빠름(탭 오버헤드 없음)	더 느림(실제 탭을 염)
Chrome 실행 필요 여부	불필요	필요

기본 원칙: 공개 페이지에는 convert_url을 사용하세요. Reddit, 인증이 필요한 페이지, JS 비중이 높은 사이트에는 agent_convert / agent_batch_convert를 사용하세요.

시작하기

핵심 기능

고급

요금제

개요

아키텍처

설정

1단계: MCP Server 빌드

2단계: Native Messaging Host 설치

3단계: MCP 설정

4단계: 확인

사용 가능한 도구

agent_convert

agent_batch_convert

사용 예시

지원 사이트

문제 해결

MCP Server와의 차이점

​개요

​아키텍처

​설정

​1단계: MCP Server 빌드

​2단계: Native Messaging Host 설치

​3단계: MCP 설정

​4단계: 확인

​사용 가능한 도구

​agent_convert

​agent_batch_convert

​사용 예시

​지원 사이트

​문제 해결

​MCP Server와의 차이점

개요

아키텍처

설정

1단계: MCP Server 빌드

2단계: Native Messaging Host 설치

3단계: MCP 설정

4단계: 확인

사용 가능한 도구

agent_convert

agent_batch_convert

사용 예시

지원 사이트

문제 해결

MCP Server와의 차이점