Ref MCP Server

Ref MCP

Un servidor ModelContextProtocol que le da a tu herramienta de codificación o agente de IA acceso a documentación de APIs, servicios, librerías, etc. Es tu ventanilla única para mantener a tu agente actualizado con la documentación de forma rápida y eficiente en tokens.

Para más información consulta ref.tools

Búsqueda agéntica para el contexto exacto

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

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

Para una consulta simple sobre la API REST de comentarios de Figma, hará 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 prompt 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 MCP para rastrear la trayectoria de búsqueda y minimizar el uso de contexto. Hay muchas más ideas en desarrollo, pero esto es 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, se profundiza en los resultados de búsqueda paginando al siguiente resultado, pero este enfoque permite al agente paginar Y ajustar el prompt al mismo tiempo.

2. Obtención de la parte relevante de la página

Al leer una página de documentación, Ref usará 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 es que cuando encuentra una página de documentación grande, fácilmente puedes terminar trayendo más de 20k tokens al contexto, la mayoría irrelevantes.

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

1. Más contexto hace a los modelos más tontos

Está bien documentado que a partir de julio de 2025, los modelos se vuelven más tontos a medida que introduces más tokens. Puede que hayas oído que los modelos ahora son geniales con contextos largos, y eso es en parte cierto, pero no es la imagen completa. Para una introducción rápida a algunas investigaciones, mira este video del equipo de Chroma.

2. Los tokens cuestan dinero

Imagina que estás usando Claude Opus como agente en segundo plano y empiezas haciendo que el agente traiga contexto de documentación. Supón que trae 10000 tokens de contexto, de los cuales 4000 son relevantes y 6000 son ruido extra. A precio de API, esos 6k tokens cuestan alrededor de $0.09 POR PASO. Si un prompt termina tomando 11 pasos con Opus, has gastado $1 sin razón.

Configuración

Hay dos opciones para configurar Ref como un servidor MCP, ya sea a través del servidor HTTP transmitible (recomendado) o el servidor stdio local (heredado).

Este repositorio contiene el servidor stdio heredado.

HTTP transmitible (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 datos o fragmentos de código. Se puede usar para buscar documentación pública en la web o GitHub, así como en recursos privados como repositorios y PDFs.

Parámetros:

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

ref_read_url

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

Parámetros:

• url (requerido): La URL de la página web a leer.

Soporte para investigación profunda de OpenAI

Ref se puede usar como fuente para investigación profunda. OpenAI requiere definiciones de herramientas específicas, por lo que cuando se usa 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 usar 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 instrucciones detalladas de configuración.

Para probar localmente con 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