Ref

Ref MCP

Um servidor ModelContextProtocol que dá à sua ferramenta de codificação ou agente de IA acesso à documentação de APIs, serviços, bibliotecas, etc. É o seu ponto central para manter seu agente atualizado com a documentação de forma rápida e eficiente em tokens.

Para mais informações, veja ref.tools

Busca agêntica pelo contexto exatamente certo

As ferramentas do Ref são projetadas para corresponder à forma como os modelos buscam, usando o mínimo de contexto possível para reduzir a deterioração do contexto. O objetivo é encontrar exatamente o contexto que seu agente de codificação precisa para ter sucesso, usando o mínimo de tokens.

Dependendo da complexidade do prompt, agentes de codificação LLM como o Claude Code normalmente farão uma ou mais buscas e, em seguida, escolherão alguns recursos para ler com mais profundidade.

Para uma consulta simples sobre a API REST de Comentários do Figma, ele fará algumas chamadas para obter exatamente o que precisa:

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

Para situações mais complexas, o LLM tentará refinar seu prompt à medida que lê os resultados. Por exemplo:

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)

O Ref aproveita as sessões MCP para rastrear a trajetória de busca e minimizar o uso de contexto. Há muito mais ideias em desenvolvimento, mas aqui está o que implementamos até agora.

1. Filtrando resultados de busca

Para buscas semelhantes repetidas em uma sessão, o Ref nunca retornará resultados repetidos. Tradicionalmente, você se aprofunda nos resultados da busca paginando para o próximo resultado, mas esta abordagem permite que o agente pagine E ajuste o prompt ao mesmo tempo.

2. Buscando a parte da página que importa

Ao ler uma página de documentação, o Ref usará o histórico de busca da sessão do agente para descartar seções menos relevantes e retornar os 5 mil tokens mais relevantes. Isso ajuda o Ref a evitar um grande problema com o web scraping fetch() padrão, que é quando atinge uma página de documentação grande, você pode facilmente acabar puxando mais de 20 mil tokens para o contexto, a maioria dos quais são irrelevantes.

Por que minimizar tokens do contexto da documentação é importante?

1. Mais contexto torna os modelos mais burros

Está bem documentado que, em julho de 2025, os modelos ficam mais burros conforme você insere mais tokens. Você pode ter ouvido falar que os modelos agora são ótimos com contexto longo, e isso é meio verdade, mas não é o quadro completo. Para uma introdução rápida a algumas pesquisas, confira este vídeo da equipe do Chroma.

2. Tokens custam $$$

Imagine que você está usando o Claude Opus como um agente em segundo plano e começa fazendo o agente puxar o contexto da documentação. Suponha que ele puxe 10.000 tokens de contexto, sendo 4.000 relevantes e 6.000 ruído extra. Com o preço da API, esses 6 mil tokens custam cerca de US$ 0,09 POR ETAPA. Se um prompt acabar levando 11 etapas com o Opus, você gastou US$ 1 sem motivo.

Configuração

Existem duas opções para configurar o Ref como um servidor MCP, seja através do servidor HTTP transmitido por streaming (recomendado) ou servidor stdio local (legado).

Este repositório contém o servidor stdio legado.

HTTP transmitido por streaming (recomendado)

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

stdio

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

Ferramentas

O servidor Ref MCP fornece todas as ferramentas relacionadas à documentação para as necessidades do seu agente.

ref_search_documentation

Uma ferramenta de busca poderosa para verificar documentação técnica. Ótima para encontrar fatos ou trechos de código. Pode ser usada para buscar documentação pública na web ou no github, bem como de recursos privados como repositórios e PDFs.

Parâmetros:

• query (obrigatório): Consulta para buscar documentação relevante. Deve ser uma frase completa ou pergunta.

ref_read_url

Uma ferramenta que busca conteúdo de uma URL e o converte para markdown para facilitar a leitura com o Ref. Isso é poderoso quando usado em conjunto com a ferramenta ref_search_documentation, que retorna URLs de conteúdo relevante.

Parâmetros:

• url (obrigatório): A URL da página da web a ser lida.

Suporte à pesquisa profunda do OpenAI

O Ref pode ser usado como uma fonte para pesquisa profunda. O OpenAI requer definições de ferramentas específicas, portanto, quando usado com um cliente OpenAI, o Ref fornecerá as mesmas ferramentas com nomes ligeiramente diferentes.

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

Desenvolvimento

npm install
npm run dev

Executando com o Inspector

Para fins de desenvolvimento e depuração, você pode usar a ferramenta MCP Inspector. O Inspector fornece uma interface visual para testar e monitorar as interações do servidor MCP.

Visite a documentação do Inspector para obter instruções detalhadas de configuração.

Para testar localmente com o Inspector:

npm run inspect

Ou execute ambos, o observador e o inspector:

npm run dev

Desenvolvimento Local

1. Clone o repositório
2. Instale as dependências:

npm install

3. Compile o projeto:

npm run build

4. Para desenvolvimento com reconstrução automática:

npm run watch

Licença

MIT