ref-tools/ref-tools-mcp

Helping coding agents never make mistakes working with public or private libraries without wasting the context window.

Ref MCP – 문서 조회를 위한 Model-Context-Protocol 서버

개요 – Ref MCP는 Model Context Protocol (MCP)을 구현한 소형 Node-JS 서비스입니다. LLM 기반 코딩 어시스턴트(예: Claude Code, Cursor)가 API나 라이브러리 문서에서 실제로 필요한 부분만 가져올 수 있게 하여 토큰 수와 비용을 낮게 유지합니다.

중요성 – 에이전트가 함수 시그니처나 사용 예제를 웹에서 검색할 때, 원본 HTML은 수만 개의 토큰에 달할 수 있습니다. 이 모든 내용을 모델에 전달하면 컨텍스트가 낭비되고, 모델의 추론 성능이 저하되며, API 비용이 상승합니다. Ref MCP는 다음과 같은 방식으로 이를 해결합니다:

검색 우선 – 에이전트가 자연어 쿼리로 ref_search_documentation을 호출합니다. Ref는 일치하는 URL의 짧은 목록을 반환합니다.
선택적 읽기 – 에이전트가 ref_read_url을 호출합니다. Ref는 세션의 검색 기록을 사용하여 페이지를 가장 관련성 높은 약 5k 토큰으로 다듬고 관련 없는 섹션을 제거합니다.
세션 인식 – 동일한 MCP 세션 내에서의 반복 검색은 중복 제거되며, 서버는 페이지의 어떤 부분이 이미 읽혔는지 기억하여 토큰 낭비를 더욱 줄입니다.

MCP를 통해 노출되는 핵심 도구

도구	목적	매개변수
`ref_search_documentation` (별칭 `search`)	공개 문서, GitHub 저장소, PDF 등에 대한 전체 텍스트 검색	`query` – 에이전트가 필요한 정보를 설명하는 문장이나 질문
`ref_read_url` (별칭 `fetch`)	URL을 가져와 Markdown으로 변환하고 관련성 필터링된 발췌문을 반환	`url` – 읽을 페이지

실행 방법

Streamable-HTTP 서버 (권장) – https://api.ref.tools/mcp에 서버를 배포하고 간단한 JSON 설정을 통해 에이전트를 연결합니다.
레거시 stdio 서버 – npx ref-tools-mcp@latest를 사용하여 로컬에서 실행합니다. 저장소에 이 모드에 대한 코드가 포함되어 있습니다.

두 모드 모두 ref.tools에서 얻은 API 키(REF_API_KEY)가 필요합니다.

일반적인 워크플로우 예시

Agent: SEARCH "Figma API post comment endpoint documentation"
Ref MCP → Figma 문서 URL 반환 (≈54 tokens)
Agent: READ https://www.figma.com/developers/api#post-comments-endpoint
Ref MCP → 엔드포인트를 설명하는 385토큰 스니펫만 반환

더 복잡한 쿼리의 경우 에이전트는 검색과 읽기를 교차 수행할 수 있으며, Ref는 세션 상태를 기억하여 중복 결과를 방지합니다.

개발 및 디버깅

npm run dev – 핫 리로딩 기능과 함께 서버를 시작합니다.
npm run inspect – 도구 호출의 시각적 테스트를 위해 MCP Inspector UI를 실행합니다.
표준 Node 스크립트(build, watch 등)가 제공됩니다.

라이선스 – MIT이므로 자유롭게 자신의 AI 도구 스택에 포함하거나 수정할 수 있습니다.

결론 – Ref MCP는 LLM 에이전트와 방대한 기술 문서 사이를 연결하는 실용적이고 토큰 효율적인 브리지입니다. 에이전트는 관련 없는 텍스트에 파묻히지 않고 항상 최신 상태를 유지할 수 있습니다.