Skip to main content
Glama
deenesjakoruzh
ref-tools

Ref

by ref-tools
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

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: graphpilot

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

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

로컬 개발

  1. 저장소 복제

  2. 의존성 설치:

npm install

  1. 프로젝트 빌드:

npm run build

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

npm run watch

라이선스

MIT

Available Tools

2 tools
ref_read_urlAInspect

Read the content of a url as markdown. The entire exact URL from a Ref 'ref_search_documentation' result should be passed to this tool to read it.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesThe URL of the webpage to read.

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool reads content and converts it to markdown, but lacks details on error handling, rate limits, authentication needs, or output format. For a tool with no annotations, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is highly concise and well-structured in two sentences. The first sentence states the core purpose, and the second provides usage context. There is no wasted language, making it front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (reading and converting web content) and lack of annotations or output schema, the description is adequate but incomplete. It covers purpose and basic usage but omits behavioral details like error cases or output specifics, leaving room for improvement in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with the parameter 'url' documented as 'The URL of the webpage to read.' The description adds minimal value beyond this by specifying that the URL should come from 'ref_search_documentation' results, but does not provide additional syntax or format details. Baseline 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Read the content of a url as markdown.' It specifies the verb ('Read') and resource ('content of a url'), making the action explicit. However, it does not explicitly distinguish this tool from its sibling 'ref_search_documentation', which likely searches rather than reads content, so it misses full differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: 'The entire exact URL from a Ref 'ref_search_documentation' result should be passed to this tool to read it.' This implies usage after obtaining a URL from the sibling tool, offering a workflow guideline. However, it does not specify when not to use it or alternatives, keeping it from a perfect score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ref_search_documentationBInspect

Search for documentation on the web or github as well from private resources like repos and pdfs. Use Ref 'ref_read_url' to read the content of a url.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesQuery for documentation. Should include programming language and framework or library names. Searches public only docs by default, include ref_src=private to search a user's private docs.

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but only mentions searching capabilities and a related tool. It fails to disclose critical behavioral traits like whether this is a read-only operation, potential rate limits, authentication needs for private resources, or what the search results look like (e.g., format, pagination).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences that directly state the tool's function and a usage tip. It's front-loaded and avoids unnecessary words, though it could be slightly more structured for clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a search tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., search results format), how private resources are accessed, or error handling, leaving significant gaps for an AI agent to use it effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage, fully describing the single 'query' parameter with details on including language/framework names and the 'ref_src=private' option. The description adds no additional parameter semantics beyond what the schema provides, so it meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as searching for documentation across web, GitHub, and private resources, which is specific and actionable. However, it doesn't explicitly differentiate from its sibling 'ref_read_url', which is for reading URL content rather than searching, so it misses full sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by mentioning 'ref_read_url' for reading content, suggesting a workflow, but lacks explicit guidance on when to use this tool versus alternatives or any exclusions. It provides some context but no clear when/when-not rules.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
Disambiguation5/5

The two tools have clearly distinct purposes: ref_search_documentation finds documentation resources, while ref_read_url reads the content of specific URLs. There is no overlap or ambiguity between searching and reading operations.

Naming Consistency5/5

Both tools follow a consistent 'ref_verb_noun' naming pattern with snake_case. The prefix 'ref_' provides clear namespace identification, and the verb-noun structure (search_documentation, read_url) is uniform and predictable.

Tool Count3/5

With only two tools, the server feels minimal but functional for its documentation search/read purpose. While it covers core workflows, the count is borderline thin—additional tools for filtering, saving, or managing searches might enhance completeness without overcomplication.

Completeness4/5

The tool set covers the essential documentation workflow: searching and reading. However, there are minor gaps, such as no tools for saving results, filtering searches, or managing cached content, which agents might need to work around for advanced use cases.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ref-tools/ref-tools-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server