> ## Documentation Index
> Fetch the complete documentation index at: https://web2md.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Bridge

> AI 에이전트가 Chrome extension을 통해 Reddit과 모든 웹사이트를 일괄 변환하도록 하세요

## 개요

Agent Bridge는 AI 에이전트(Claude Code, Cursor, Cowork 등)가 Web2MD Chrome extension을 원격으로 제어하여 URL을 일괄 변환할 수 있게 해줍니다 — 특히 서버 측 API 접근을 차단하는 Reddit, JS 렌더링 페이지, 로그인 보호 페이지에 유용합니다.

Web2MD API(Reddit이 차단하는)를 호출하는 대신, AI 에이전트는 [Native Messaging](https://developer.chrome.com/docs/extensions/develop/concepts/native-messaging)을 통해 로컬 Chrome extension에 명령을 전송합니다. Extension은 **실제 브라우저 세션**(쿠키와 로그인 상태 포함)을 사용해 백그라운드 탭에서 각 페이지를 열고, 콘텐츠를 추출해 Markdown으로 변환한 뒤 결과를 반환합니다.

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

## 아키텍처

```
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 빌드

```bash theme={null}
cd packages/mcp-server
pnpm build
```

### 2단계: Native Messaging Host 설치

```bash theme={null}
cd packages/mcp-server
./install.sh <your-extension-id>
```

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

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

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

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

### 3단계: MCP 설정

<Tabs>
  <Tab title="Claude Code">
    `~/.claude/settings.json`에 추가하세요.

    ```json theme={null}
    {
      "mcpServers": {
        "web2md-agent": {
          "command": "node",
          "args": ["/path/to/packages/mcp-server/dist/index.js"],
          "env": {
            "WEB2MD_API_KEY": "w2m_your_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    `~/.cursor/mcp.json`에 추가하세요.

    ```json theme={null}
    {
      "mcpServers": {
        "web2md-agent": {
          "command": "node",
          "args": ["/path/to/packages/mcp-server/dist/index.js"],
          "env": {
            "WEB2MD_API_KEY": "w2m_your_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Claude Desktop 설정에 추가하세요.

    ```json theme={null}
    {
      "mcpServers": {
        "web2md-agent": {
          "command": "node",
          "args": ["/path/to/packages/mcp-server/dist/index.js"],
          "env": {
            "WEB2MD_API_KEY": "w2m_your_key_here"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### 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 분석에 활용.

<Info>
  성공적으로 변환된 모든 항목은 AI가 생성한 요약 및 태그와 함께 [Dashboard History](https://web2md.org/dashboard/history)에 자동으로 저장됩니다.
</Info>

## 사용 예시

<AccordionGroup>
  <Accordion title="Reddit 스레드 변환">
    **사용자:** 이 Reddit 스레드를 Markdown으로 변환해줘: [https://www.reddit.com/r/LangChain/comments/1siwh6q/](https://www.reddit.com/r/LangChain/comments/1siwh6q/)...

    **Agent:** *(`agent_convert` 호출)* 법률 문서에 대한 RAG 정확도를 논의하는 댓글 7개가 포함된 변환된 스레드입니다...
  </Accordion>

  <Accordion title="리서치를 위한 일괄 변환">
    **사용자:** 이 Reddit URL 5개를 일괄 변환하고 핵심 내용을 요약해줘.

    * [https://reddit.com/r/MachineLearning/comments/](https://reddit.com/r/MachineLearning/comments/)...
    * [https://reddit.com/r/LocalLLaMA/comments/](https://reddit.com/r/LocalLLaMA/comments/)...
    * [https://reddit.com/r/LangChain/comments/](https://reddit.com/r/LangChain/comments/)...
    * [https://reddit.com/r/artificial/comments/](https://reddit.com/r/artificial/comments/)...
    * [https://reddit.com/r/ChatGPT/comments/](https://reddit.com/r/ChatGPT/comments/)...

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

  <Accordion title="로그인 보호 페이지 변환">
    **사용자:** 회사 내부 위키 페이지 [https://wiki.internal.com/architecture](https://wiki.internal.com/architecture) 를 변환해줘

    **Agent:** *(`agent_convert` 호출)* Chrome에서 해당 사이트에 로그인되어 있어서 전체 내용을 추출할 수 있었습니다...
  </Accordion>
</AccordionGroup>

## 지원 사이트

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 호출을 통해 변환되어 더 빠르고 안정적입니다. 나머지는 백그라운드 탭을 사용합니다.

## 문제 해결

<AccordionGroup>
  <Accordion title="'Native host not installed' 또는 'not found' 오류">
    Chrome이 NM manifest를 아직 불러오지 않은 상태입니다. **Chrome을 완전히 종료(Cmd+Q)한 뒤 다시 여세요.** Extension만 다시 로드하는 것으로는 충분하지 않습니다.
  </Accordion>

  <Accordion title="'Native host has exited'가 즉시 발생">
    Chrome이 host 스크립트를 실행하지 못하는 상태입니다. 흔한 원인은 다음과 같습니다.

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

  <Accordion title="MCP에서 'Agent connection error' 발생">
    Native Host TCP server가 실행되고 있지 않습니다. 다음을 확인하세요.

    1. Chrome이 열려 있는지
    2. Web2MD extension이 로드되어 있는지
    3. Service Worker 콘솔에 "TCP relay ready on port 12315"가 표시되는지
  </Accordion>

  <Accordion title="'Failed to extract content from the page' 오류">
    Extension이 로그인되어 있지 않은 상태입니다. Chrome에서 Web2MD 팝업을 열고 PRO 계정으로 로그인하세요.
  </Accordion>

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

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

## 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`를 사용하세요.