Ref MCP Server

공식

코딩 에이전트를 위한 최신 문서입니다. 수천 개의 공개 저장소와 사이트를 다룹니다. ref.tools에서 제작했습니다.

GitHub
1.1k

문서

Documentation for your agent smithery badge Website License npm version

Ref MCP

AI 코딩 도구나 에이전트가 API, 서비스, 라이브러리 등의 문서에 접근할 수 있게 해주는 ModelContextProtocol 서버입니다. 빠르고 토큰 효율적인 방식으로 에이전트가 최신 문서를 유지하도록 돕는 원스톱 솔루션입니다.

자세한 내용은 ref.tools를 참조하세요.

정확한 맥락을 위한 에이전틱 검색

Ref의 도구는 컨텍스트 로트를 줄이기 위해 가능한 한 적은 컨텍스트를 사용하면서 모델이 검색하는 방식을 반영하도록 설계되었습니다. 목표는 최소한의 토큰을 사용하면서 코딩 에이전트가 성공하는 데 필요한 컨텍스트를 정확히 찾는 것입니다.

프롬프트의 복잡성에 따라 Claude Code와 같은 LLM 코딩 에이전트는 일반적으로 한 번 이상의 검색을 수행한 다음 더 깊이 읽을 몇 가지 리소스를 선택합니다.

Figma의 Comment REST API에 대한 간단한 쿼리의 경우 필요한 것을 정확히 얻기 위해 몇 번의 호출을 수행합니다:

SEARCH 'Figma API post comment endpoint documentation' (54 tokens)
READ https://www.figma.com/developers/api#post-comments-endpoint (385 tokens)

더 복잡한 상황에서는 LLM이 결과를 읽으면서 프롬프트를 구체화하려고 시도합니다. 예를 들어:

SEARCH 'n8n merge node vs Code node multiple inputs best practices' (126)
READ https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.merge/#merge (4961)
READ https://docs.n8n.io/flow-logic/merging/#merge-data-from-multiple-node-executions (138)
SEARCH 'n8n Code node multiple inputs best practices when to use' (107)
READ https://docs.n8n.io/code/code-node/#usage (80)
SEARCH 'n8n Code node access multiple inputs from different nodes' (370)
SEARCH 'n8n Code node $input access multiple node inputs' (372)
READ https://docs.n8n.io/code/builtin/output-other-nodes/#output-of-other-nodes (2310)

Ref는 MCP 세션을 활용하여 검색 궤적을 추적하고 컨텍스트 사용을 최소화합니다. 더 많은 아이디어가 준비 중이지만 현재까지 구현된 내용은 다음과 같습니다.

1. 검색 결과 필터링

세션 내에서 유사한 검색이 반복될 경우, Ref는 중복된 결과를 절대 반환하지 않습니다. 기존에는 다음 결과로 페이징하여 검색 결과를 더 깊이 파고들지만, 이 접근 방식을 통해 에이전트는 페이징과 동시에 프롬프트를 조정할 수 있습니다.

2. 중요한 페이지 부분 가져오기

문서 페이지를 읽을 때, Ref는 에이전트의 세션 검색 기록을 사용하여 덜 관련성 있는 섹션을 제외하고 가장 관련성 높은 5k 토큰을 반환합니다. 이를 통해 Ref는 표준 fetch() 웹 스크래핑의 큰 문제점, 즉 대용량 문서 페이지에 접근할 때 대부분 관련 없는 20k 이상의 토큰이 컨텍스트로 쉽게 유입되는 문제를 피할 수 있습니다.

문서 컨텍스트에서 토큰을 최소화해야 하는 이유는 무엇인가요?

1. 더 많은 컨텍스트는 모델을 더 멍청하게 만듭니다

2025년 7월 현재, 더 많은 토큰을 입력할수록 모델이 더 멍청해진다는 것은 잘 문서화되어 있습니다. 모델이 이제 긴 컨텍스트를 잘 처리한다는 이야기를 들어보셨을 수 있으며, 이는 어느 정도 사실이지만 전체 그림은 아닙니다. 연구에 대한 간략한 소개를 보려면 Chroma 팀의 이 비디오를 확인하세요.

2. 토큰은 비용이 듭니다 $$$

Claude Opus를 백그라운드 에이전트로 사용하고 에이전트가 문서 컨텍스트를 가져오는 것으로 시작한다고 가정해 보겠습니다. 10,000 토큰의 컨텍스트를 가져오고 그중 4,000개는 관련성이 있고 6,000개는 추가 노이즈라고 가정합니다. API 가격으로 6k 토큰은 단계당 약 $0.09의 비용이 듭니다. 하나의 프롬프트가 Opus로 11단계를 거치게 되면 아무 이유 없이 $1를 지출한 셈입니다.

설정

Ref를 MCP 서버로 설정하는 방법에는 streamable-http 서버(권장) 또는 로컬 stdio 서버(레거시)를 통한 두 가지 옵션이 있습니다.

이 저장소에는 레거시 stdio 서버가 포함되어 있습니다.

Streamable HTTP (권장)

Install Ref MCP in Cursor

"Ref": {
  "type": "http",
  "url": "https://api.ref.tools/mcp?apiKey=YOUR_API_KEY"
}

stdio

Install Ref MCP in Cursor (stdio)

"Ref": {
  "command": "npx",
  "args": ["ref-tools-mcp@latest"],
  "env": {
    "REF_API_KEY": <sign up to get an api key>
  }
}

도구

Ref MCP 서버는 에이전트 요구에 맞는 모든 문서 관련 도구를 제공합니다.

ref_search_documentation

기술 문서를 확인하기 위한 강력한 검색 도구입니다. 사실이나 코드 스니펫을 찾는 데 유용합니다. 웹이나 GitHub의 공개 문서뿐만 아니라 저장소 및 PDF와 같은 비공개 리소스에서도 검색하는 데 사용할 수 있습니다.

매개변수:

  • query (필수): 관련 문서를 검색하기 위한 쿼리입니다. 완전한 문장이나 질문이어야 합니다.

ref_read_url

URL에서 콘텐츠를 가져와 Ref로 쉽게 읽을 수 있도록 마크다운으로 변환하는 도구입니다. 관련 콘텐츠의 URL을 반환하는 ref_search_documentation 도구와 함께 사용할 때 강력합니다.

매개변수:

  • url (필수): 읽을 웹페이지의 URL입니다.

OpenAI 심층 연구 지원

Ref는 심층 연구의 소스로 사용될 수 있습니다. OpenAI는 특정 도구 정의를 요구하므로 OpenAI 클라이언트와 함께 사용할 때 Ref는 약간 다른 이름으로 동일한 도구를 제공합니다.

ref_search_documentation(query) -> search(query)
ref_read_url(url) -> fetch(id)

개발

npm install
npm run dev

Inspector로 실행하기

개발 및 디버깅 목적으로 MCP Inspector 도구를 사용할 수 있습니다. Inspector는 MCP 서버 상호 작용을 테스트하고 모니터링하기 위한 시각적 인터페이스를 제공합니다.

자세한 설정 지침은 Inspector 문서를 방문하세요.

Inspector로 로컬에서 테스트하려면:

npm run inspect

또는 감시자와 Inspector를 함께 실행합니다:

npm run dev

로컬 개발

  1. 저장소 복제
  2. 종속성 설치:
npm install
  1. 프로젝트 빌드:
npm run build
  1. 자동 재빌드를 통한 개발:
npm run watch

라이선스

MIT