Documentation for your agent Website License npm version

Ref MCP

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

더 자세한 정보는 ref.tools를 확인하세요.

정확한 컨텍스트를 위한 에이전트 검색

Ref의 도구는 모델이 검색하는 방식에 맞춰 설계되었으며, 컨텍스트 로트(context rot)를 줄이기 위해 가능한 한 적은 컨텍스트를 사용합니다. 목표는 코딩 에이전트가 성공하는 데 필요한 정확한 컨텍스트를 최소한의 토큰으로 찾아내는 것입니다.

프롬프트의 복잡성에 따라, 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 토큰을 반환합니다. 이는 표준 fetch() 웹 스크래핑의 큰 문제점인, 대규모 문서 페이지를 불러올 때 대부분 관련 없는 20k+ 토큰이 컨텍스트에 포함되는 문제를 방지하는 데 도움이 됩니다.

Related MCP server: Firebase Realtime Database

문서 컨텍스트에서 토큰을 최소화하는 것이 왜 중요한가요?

1. 컨텍스트가 많을수록 모델은 멍청해집니다

2025년 7월 기준으로, 토큰을 많이 입력할수록 모델의 성능이 떨어진다는 것은 잘 알려진 사실입니다. 모델이 긴 컨텍스트를 잘 처리한다는 이야기를 들었을 수도 있지만, 그것은 전체적인 모습이 아닙니다. 연구에 대한 간단한 입문은 Chroma 팀의 이 비디오를 확인하세요.

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

Claude Opus를 백그라운드 에이전트로 사용하고 있다고 가정해 봅시다. 에이전트가 문서 컨텍스트를 가져오기 시작하는데, 4000 토큰은 관련이 있고 6000 토큰은 불필요한 노이즈라고 가정하면, 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

또는 watcher와 inspector를 모두 실행하려면:

npm run dev

로컬 개발

저장소 복제
의존성 설치:

npm install

프로젝트 빌드:

npm run build

자동 재빌드를 포함한 개발:

npm run watch

라이선스

MIT

Ref