Ref MCP

Un servidor ModelContextProtocol que proporciona a tu herramienta de programación o agente de IA acceso a documentación de APIs, servicios, bibliotecas, etc. Es tu solución integral para mantener a tu agente actualizado con la documentación de forma rápida y eficiente en cuanto a tokens.

Para más información, visita ref.tools

Búsqueda agentica para obtener exactamente el contexto correcto

Las herramientas de Ref están diseñadas para coincidir con la forma en que los modelos buscan, utilizando la menor cantidad de contexto posible para reducir la degradación del contexto. El objetivo es encontrar exactamente el contexto que tu agente de programación necesita para tener éxito utilizando el mínimo de tokens.

Dependiendo de la complejidad de la instrucción, los agentes de programación LLM como Claude Code normalmente realizarán una o más búsquedas y luego elegirán algunos recursos para leer con mayor profundidad.

Para una consulta sencilla sobre la API REST de comentarios de Figma, realizará un par de llamadas para obtener exactamente lo que necesita:

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

Para situaciones más complejas, el LLM intentará refinar su instrucción a medida que lee los resultados. Por ejemplo:

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 aprovecha las sesiones de MCP para rastrear la trayectoria de búsqueda y minimizar el uso de contexto. Hay muchas más ideas en desarrollo, pero aquí presentamos lo que hemos implementado hasta ahora.

1. Filtrado de resultados de búsqueda

Para búsquedas similares repetidas en una sesión, Ref nunca devolverá resultados repetidos. Tradicionalmente, profundizas en los resultados de búsqueda pasando a la siguiente página, pero este enfoque permite al agente paginar Y ajustar la instrucción al mismo tiempo.

2. Obtención de la parte de la página que importa

Al leer una página de documentación, Ref utilizará el historial de búsqueda de la sesión del agente para descartar secciones menos relevantes y devolver los 5k tokens más relevantes. Esto ayuda a Ref a evitar un gran problema con el web scraping estándar fetch(), que ocurre cuando se accede a una página de documentación extensa y se pueden terminar extrayendo más de 20k tokens al contexto, la mayoría de los cuales son irrelevantes.

Related MCP server: Firebase Realtime Database

¿Por qué es importante minimizar los tokens del contexto de la documentación?

1. Más contexto hace que los modelos sean menos inteligentes

Está bien documentado que, a fecha de julio de 2025, los modelos se vuelven menos inteligentes a medida que se introducen más tokens. Es posible que hayas oído hablar de cómo los modelos son excelentes con contextos largos ahora, y eso es cierto en parte, pero no es la imagen completa. Para una introducción rápida sobre algunas investigaciones, mira este video del equipo de Chroma.

2. Los tokens cuestan $$$

Imagina que estás usando Claude Opus como agente en segundo plano y comienzas haciendo que el agente extraiga contexto de la documentación; supongamos que extrae 10,000 tokens de contexto, de los cuales 4,000 son relevantes y 6,000 son ruido adicional. Según los precios de la API, esos 6k tokens cuestan alrededor de $0.09 POR PASO. Si una instrucción termina tomando 11 pasos con Opus, has gastado $1 sin ninguna razón.

Configuración

Hay dos opciones para configurar Ref como servidor MCP: a través del servidor streamable-http (recomendado) o el servidor stdio local (legado).

Este repositorio contiene el servidor stdio legado.

Streamable HTTP (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>
  }
}

Herramientas

El servidor Ref MCP proporciona todas las herramientas relacionadas con la documentación que tu agente necesita.

ref_search_documentation

Una potente herramienta de búsqueda para consultar documentación técnica. Ideal para encontrar hechos o fragmentos de código. Se puede utilizar para buscar documentación pública en la web o en GitHub, así como en recursos privados como repositorios y archivos PDF.

Parámetros:

• query (obligatorio): Consulta para buscar documentación relevante. Debe ser una oración completa o una pregunta.

ref_read_url

Una herramienta que obtiene contenido de una URL y lo convierte a markdown para facilitar su lectura con Ref. Es muy potente cuando se utiliza junto con la herramienta ref_search_documentation, que devuelve URLs de contenido relevante.

Parámetros:

• url (obligatorio): La URL de la página web que se desea leer.

Soporte para investigación profunda de OpenAI

Ref puede utilizarse como fuente para investigación profunda. OpenAI requiere definiciones de herramientas específicas, por lo que cuando se utiliza con un cliente de OpenAI, Ref proporcionará las mismas herramientas con nombres ligeramente diferentes.

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

Desarrollo

npm install
npm run dev

Ejecución con Inspector

Para fines de desarrollo y depuración, puedes utilizar la herramienta MCP Inspector. El Inspector proporciona una interfaz visual para probar y monitorear las interacciones del servidor MCP.

Visita la documentación del Inspector para obtener instrucciones detalladas de configuración.

Para probar localmente con el Inspector:

npm run inspect

O ejecuta tanto el observador como el inspector:

npm run dev

Desarrollo local

1. Clona el repositorio

2. Instala las dependencias:

npm install

3. Construye el proyecto:

npm run build

4. Para desarrollo con reconstrucción automática:

npm run watch

Licencia

MIT