MCP Research Friend

공식

연구 도구, Sqlite 기반 문서 저장소 포함

GitHub

Research Friend MCP(으)로 무엇을 할 수 있나요?

  • 웹 페이지 가져오기 및 추출 — friendly_web_fetch를 사용하여 페이지의 주요 콘텐츠를 깔끔한 마크다운으로 검색하도록 어시스턴트에 요청하세요.
  • 웹 검색 — friendly_search를 통해 DuckDuckGo 또는 Google로 웹 검색을 실행하고 제목, URL, 스니펫을 반환하도록 어시스턴트에 요청하세요.
  • PDF 추출 또는 대형 페이지 페이지 매김 — friendly_web_extract를 사용하여 PDF에서 텍스트를 추출하거나, 오프셋으로 페이지를 나누거나, 문서 내에서 구문을 검색하세요.
  • URL에 대한 질문에 답변 — 페이지나 PDF를 가져와서 friendly_web_ask를 통해 LLM이 특정 질문에 답변하도록 어시스턴트에 요청하세요.
  • 로컬 문서 저장소 구축 및 검색 — 파일을 받은 편지함에 넣고 stash_process_inbox로 처리한 후, stash_search를 사용하여 파일 이름과 콘텐츠를 검색하세요.
  • LLM으로 보관된 문서 질의 — stash_ask를 사용하여 저장된 문서에 대해 주 대화에 로드하지 않고 질문하세요.

문서

Research Friend

웹에서 정보를 찾고 로컬 연구 보관함을 관리해야 하는 AI 어시스턴트를 위한 친절한 도우미입니다.

Research Friend는 AI 도구가 웹 페이지를 가져오고 인터넷을 검색할 수 있게 해주는 MCP 서버입니다. 내부적으로 실제 웹 브라우저를 사용하므로 JavaScript에 크게 의존하는 최신 웹사이트에서도 잘 작동합니다. 또한 문서를 저장하고, 텍스트를 추출하며, 라이브러리 전체를 검색할 수 있는 로컬 "보관함" 기능도 포함합니다.

모든 기능을 활용하려면 프롬프트(일반적)와 샘플링(덜 일반적)을 지원하는 MCP 클라이언트가 필요합니다. Research Friend는 두 가지를 모두 지원하는 Chabeau와 함께 개발하고 있습니다.

무엇을 할 수 있나요?

  • 실제 브라우저로 웹 페이지 가져오기 (JS가 많은 사이트 포함)
  • PDF 가져오기 및 텍스트 콘텐츠 추출
  • DuckDuckGo 또는 Google을 통해 웹 검색
  • 검색, 목록 보기, 추출을 위한 로컬 문서 보관함 유지

시작하기

컴퓨터에 Node.js 버전 20 이상이 설치되어 있어야 합니다.

1. 의존성 설치

이 폴더에서 터미널을 열고 다음을 실행하세요:

npm install

2. 브라우저 지원 설치

Research Friend는 Playwright를 사용하여 웹 브라우저를 제어합니다. 의존성을 설치한 후 브라우저를 설치해야 합니다:

npx playwright install chromium

이 명령은 Playwright가 사용할 Chromium 사본을 다운로드합니다. 이미 설치된 브라우저와는 별개입니다.

3. 서버 시작

node src/index.js

서버는 표준 입출력(stdio)을 통해 통신하며, 이것이 MCP 클라이언트가 연결하는 방식입니다.

MCP 클라이언트에 추가하기

Research Friend를 추가하는 방법은 사용 중인 MCP 클라이언트에 따라 다릅니다. 다음은 구성이 어떻게 보일지에 대한 일반적인 예시입니다:

[[mcp_servers]]
id = "research-friend"
command = "node"
args = ["/path/to/mcp-research-friend/src"]
transport = "stdio"

/path/to/mcp-research-friend을 컴퓨터에서 이 폴더의 실제 경로로 바꾸세요.

도구

웹 도구

friendly_web_fetch

웹 페이지를 가져와 콘텐츠를 반환합니다. 기본적으로 링크가 보존된 마크다운을 반환하여 LLM에 이상적입니다. Readability를 사용하여 주요 콘텐츠를 추출합니다(탐색 메뉴, 광고 등 제거). PDF, 페이지 매김 또는 콘텐츠 내 검색에는 friendly_web_extract를 대신 사용하세요.

매개변수:

  • url (필수) - 가져올 웹 주소
  • outputFormat - 출력 형식: markdown (기본값), text, 또는 html
  • waitMs - 콘텐츠가 천천히 나타나는 경우 페이지 로드 후 추가 대기 시간
  • timeoutMs - 포기하기 전까지 기다릴 시간 (기본값: 15초)
  • maxChars - 반환할 최대 콘텐츠 양 (기본값: 40,000자)
  • includeHtml - 콘텐츠와 함께 원시 HTML도 반환하려면 true로 설정
  • headless - 브라우저 창을 보려면 false로 설정 (디버깅에 유용)

반환값:

  • url - 요청된 URL
  • finalUrl - 리디렉션 후의 URL
  • title - 페이지 제목
  • content - 추출된 콘텐츠 (요청된 형식)
  • html - 원시 HTML (includeHtml이 true인 경우에만)
  • meta - 페이지 메타데이터 (설명, 저자, 게시 시간 등)
  • fetchedAt - 페이지를 가져온 ISO 타임스탬프
  • truncated - 콘텐츠가 maxChars에 맞게 잘렸는지 여부

friendly_search

웹을 검색하고 결과 목록을 반환합니다.

매개변수:

  • query (필수) - 검색할 내용
  • engine - 사용할 검색 엔진 (duckduckgo 또는 google)
  • maxResults - 반환할 결과 수 (기본값: 10, 최대: 50)
  • timeoutMs - 포기하기 전까지 기다릴 시간 (기본값: 15초)
  • headless - 브라우저 창을 보려면 false로 설정

반환값:

  • query - 사용된 검색 쿼리
  • engine - 사용된 검색 엔진
  • results - 결과 배열, 각 결과는 title, url, snippet 포함
  • searchedAt - 검색이 수행된 ISO 타임스탬프
  • fallback_result_html - 페이지의 원시 HTML (결과가 없을 때만 포함)
  • debug_info - 검색 시도에 대한 진단 정보

CAPTCHA 처리: 헤드리스 모드에서 실행 중 CAPTCHA가 감지되면, 도구는 자동으로 보이는 브라우저 창으로 다시 시도합니다. 이를 통해 수동으로 CAPTCHA를 해결할 기회를 제공합니다. debug_info.retried 필드는 이 대체 방법이 사용되었는지 나타냅니다.

friendly_web_extract

URL에서 콘텐츠를 추출합니다. URL이 PDF인지 웹 페이지인지 자동 감지하여 각각 적절하게 처리합니다.

매개변수:

  • url (필수) - 가져올 URL (PDF 또는 웹 페이지)
  • maxChars - 반환할 최대 텍스트 양 (기본값: 40,000자)
  • offset - 시작할 문자 위치 (기본값: 0). 큰 콘텐츠를 페이지별로 나누는 데 사용합니다.
  • search - 전체 콘텐츠 대신 구문을 검색하고 주변 문맥과 함께 일치 항목 반환
  • contextChars - 각 검색 일치 항목 주변의 문맥 문자 수 (기본값: 200)
  • waitMs - 동적 콘텐츠를 위한 페이지 로드 후 추가 대기 시간 (웹 페이지 전용)
  • timeoutMs - 포기하기 전까지 기다릴 시간 (기본값: 15초, 웹 페이지 전용)
  • headless - 브라우저 창을 보려면 false로 설정 (웹 페이지 전용)

반환값 (일반 모드):

  • url - 요청된 URL
  • contentType - pdf 또는 html
  • title - 페이지/문서 제목
  • author - PDF 저자 (PDF 전용, 가능한 경우)
  • creationDate - PDF 생성 시기 (PDF 전용, 가능한 경우)
  • pageCount - 페이지 수 (PDF 전용)
  • totalChars - 총 문자 수 (페이지 매김을 위해 offset와 함께 사용)
  • offset - 사용된 오프셋
  • content - 추출된 텍스트 콘텐츠
  • fetchedAt - ISO 타임스탬프
  • truncated - 이 청크 이후에 더 많은 콘텐츠가 남아 있는지 여부

반환값 (검색 모드):

  • url, contentType, title, totalChars, fetchedAt - 위와 동일
  • search - 사용된 검색 구문
  • matchCount - 발견된 일치 항목 수
  • matches - 일치 항목 배열, 각 항목은 position, context, prefix, suffix 포함

friendly_web_ask

URL(PDF 또는 웹 페이지)을 가져와 LLM이 이에 대한 질문에 답하도록 합니다. 콘텐츠 유형을 자동 감지합니다. 문서는 별도의 컨텍스트에서 처리되므로 주 대화를 간결하게 유지합니다.

매개변수:

  • url (필수) - 가져올 URL (PDF 또는 웹 페이지)
  • ask (필수) - LLM에 대한 질문 또는 지시 (요약, 정보 추출, 질문 답변 등)
  • askMaxInputTokens - LLM 호출당 최대 입력 토큰 (기본값: 150,000)
  • askMaxOutputTokens - LLM 호출당 최대 출력 토큰 (기본값: 4,096)
  • askTimeout - 밀리초 단위 타임아웃 (기본값: 300,000 = 5분)
  • askSplitAndSynthesize - 큰 문서의 경우: 청크로 분할하여 각각 처리한 후 결과 합성 (기본값: false). 경고: 많은 토큰을 소비합니다.
  • waitMs - 동적 콘텐츠를 위한 페이지 로드 후 추가 대기 시간 (웹 페이지 전용)
  • timeoutMs - 포기하기 전까지 기다릴 시간 (기본값: 15초, 웹 페이지 전용)
  • headless - 브라우저 창을 보려면 false로 설정 (웹 페이지 전용)

반환값:

  • url - 요청된 URL
  • contentType - pdf 또는 html
  • title - 페이지/문서 제목
  • totalChars - 문서의 총 문자 수
  • ask - 주어진 지시 사항
  • answer - LLM의 응답
  • model - 응답을 생성한 모델
  • chunksProcessed - 처리된 청크 수 (작은 문서는 1, askSplitAndSynthesize 사용 시 더 많음)
  • fetchedAt - ISO 타임스탬프

질문 모드는 MCP 샘플링을 사용하여 LLM이 모든 지시 사항으로 문서를 처리하도록 합니다. 이는 다음에 유용합니다:

  • 컨텍스트를 압도할 큰 문서
  • 주 대화의 토큰 비용 절감

askSplitAndSynthesize이 활성화되면 askMaxInputTokens을 초과하는 문서는 자동으로 겹치는 청크로 분할됩니다. 각 청크는 개별적으로 처리되고 결과는 하나의 일관된 답변으로 합성됩니다. 최종 응답은 문서의 언어와 관계없이 요청과 동일한 언어로 제공됩니다.

문서 보관함

보관함은 로컬에서 검색 가능한 문서 라이브러리입니다. PDF, HTML 파일 및 일반 텍스트(Markdown/TXT)를 지원합니다. 문서를 추가하면 Research Friend는 원본 파일을 저장하고, 텍스트를 추출하며(PDF/HTML의 경우), 메타데이터를 로컬 데이터베이스에 저장합니다. 검색은 내부적으로 ripgrep을 사용하여 빠르고 구문 인식이 가능한 매칭을 수행합니다.

보관함 위치

보관함은 ~/.research-friend/ 아래에 위치합니다:

  • inbox/ - 처리할 파일을 여기에 드롭하세요
  • store/ - 정리된 문서 저장소 및 추출된 텍스트
  • stash.db - 메타데이터 데이터베이스

지원 파일 형식

  • PDF: .pdf (텍스트 추출됨)
  • HTML: .html, .htm (텍스트 추출됨)
  • Markdown: .md, .markdown (일반 텍스트로 저장됨)
  • 텍스트: .txt (일반 텍스트로 저장됨)

보관함 도구

stash_open_inbox

드래그 앤 드롭을 쉽게 하기 위해 파일 관리자에서 보관함 받은 편지함 폴더를 엽니다.

반환값:

  • opened - 폴더 열기 요청이 전송되었는지 여부
  • inboxPath - 받은 편지함의 절대 경로
  • command - 사용된 OS 명령
  • args - 사용된 명령 인수

stash_process_inbox

inbox/에 있는 파일을 처리하여 주제별로 분류하고, 텍스트를 추출하며, 결과를 저장합니다. 긴 문서의 경우, 분류는 샘플링된 섹션(시작/중간/끝과 몇 개의 무작위 청크)을 사용하여 주제 정확도를 향상시킵니다.

반환값:

  • processed - 성공적으로 처리된 파일 이름 배열
  • errors - 발생한 모든 오류
  • documents - 생성된 문서 레코드 배열

reindex_stash

보관된 문서에 대한 요약을 재생성하고, 주제를 재할당하며, 저장소 메타데이터를 업데이트합니다. ids이 생략되거나 비어 있으면 모든 문서가 재색인됩니다.

매개변수:

  • ids - 재색인할 문서 ID (선택 사항)

반환값:

  • reindexed - 재색인된 문서 ID
  • errors - 발생한 모든 오류
  • documents - 업데이트된 문서 레코드 배열

stash_list

보관함의 문서를 나열합니다.

매개변수:

  • topic - 주제로 필터링 (선택 사항)
  • limit - 최대 결과 수 (기본값: 50)
  • offset - 페이지 매김 오프셋 (기본값: 0)

반환값:

  • type - all 또는 topic
  • totalDocuments - 총 문서 수 (type가 all일 때만)
  • count - 페이지 매김 후 반환된 결과
  • offset - 사용된 페이지 매김 오프셋
  • limit - 사용된 페이지 매김 제한
  • topics - 알려진 주제 및 문서 수 요약
  • documents - 메타데이터가 포함된 문서 목록 (주제 나열 시 isPrimary 포함)

stash_search

보관함 전체에서 파일 이름과 콘텐츠를 검색합니다. 모든 검색어가 존재해야 합니다(AND 논리). 파일 이름 일치 항목이 먼저 나열됩니다. 정확한 구문에는 따옴표를 사용하세요.

매개변수:

  • query (필수) - 검색어. 구문에는 따옴표 사용: "sparkling wine"
  • topic - 주제로 필터링 (선택 사항)
  • ids - 특정 문서 ID로 필터링 (선택 사항)
  • limit - 반환할 최대 문서 수 (기본값: 20)
  • offset - 페이지 매김 오프셋 (기본값: 0)
  • maxMatchesPerDoc - 문서당 최대 일치 항목 수 (기본값: 50)
  • context - 각 일치 항목 주변의 문맥 줄 수 (기본값: 1, 최대: 5). 용어가 일치하기 위해 얼마나 가까이 나타나야 하는지와 반환되는 주변 텍스트의 양을 모두 제어합니다. 반환값:
  • totalMatches - 페이지네이션 전 일치하는 총 문서 수
  • count - 페이지네이션 후 반환된 결과
  • results - 문서 배열, 각 문서는 다음을 포함:
    • id, filename, fileType, summary, charCount, createdAt
    • matchType - filename, content, 또는 filename+content
    • matches - 각 일치 위치에 대한 { line, context } 배열

line 값과 stash_extract을 사용하여 일치 위치로 바로 이동하세요.

stash_extract

보관된 문서에서 내용을 추출하여 읽습니다. stash_search 결과의 줄 번호를 사용하여 일치 항목으로 바로 이동하세요.

매개변수:

  • id (필수) - stash_list/stash_search의 문서 ID
  • maxChars - 반환할 최대 텍스트 양 (기본값: 40,000자)
  • offset - 시작할 문자 위치 (line과 상호 배타적)
  • line - 시작할 줄 번호 (offset과 상호 배타적)

반환값:

  • id, filename, fileType, summary - 문서 메타데이터
  • totalChars - 문서의 총 문자 수
  • offset - 문자 오프셋 (참조용으로 line 사용 시 포함)
  • line - 줄 번호 (line 매개변수가 사용된 경우에만)
  • content - 추출된 텍스트 내용
  • truncated - 이 청크 이후에 더 많은 내용이 남아 있는지 여부

stash_ask

보관된 문서에 대해 LLM이 질문에 답변하도록 합니다. 문서는 별도의 컨텍스트에서 처리되므로 주 대화를 간결하게 유지할 수 있습니다.

매개변수:

  • id (필수) - stash_list/stash_search의 문서 ID
  • ask (필수) - LLM에 대한 질문 또는 지시사항
  • askMaxInputTokens - LLM 호출당 최대 입력 토큰 (기본값: 150,000)
  • askMaxOutputTokens - LLM 호출당 최대 출력 토큰 (기본값: 4,096)
  • askTimeout - 제한 시간(밀리초) (기본값: 300,000 = 5분)
  • askSplitAndSynthesize - 대용량 문서의 경우: 청크로 분할하여 각각 처리한 후 결과 합성 (기본값: false)

반환값:

  • id, filename, fileType, summary - 문서 메타데이터
  • totalChars - 문서의 총 문자 수
  • ask - 주어진 지시사항
  • answer - LLM의 응답
  • model - 응답을 생성한 모델
  • chunksProcessed - 처리된 청크 수

일반적인 흐름

  1. ~/.research-friend/inbox/에 파일 드롭
  2. stash_process_inbox 실행
  3. stash_list를 사용하여 주제 탐색
  4. stash_search를 사용하여 관련 문서 찾기
  5. stash_extract을 사용하여 특정 문서 읽기 또는 stash_ask을 사용하여 문서에 대해 질문하기

문제 해결

"브라우저가 예기치 않게 닫혔습니다" 또는 유사한 오류

브라우저 재설치를 시도하세요:

npx playwright install chromium --force

Linux에서는 시스템 종속성이 필요할 수도 있습니다:

npx playwright install-deps chromium

서버가 시작되지 않음

Node.js 20 이상을 사용하고 있는지 확인하세요:

node --version

버전이 더 낮은 경우 nodejs.org를 방문하여 최신 버전을 다운로드하세요.

라이선스

MIT