Ref MCP

¿Qué es Ref MCP?

Ref MCP es un servidor MCP especializado que conecta a agentes de codificación y herramientas de desarrollo con un universo curado de documentación técnica. Permite a los agentes buscar, recuperar y analizar las partes más relevantes de la documentación bajo demanda, reduciendo el uso de tokens y mejorando el rendimiento de los modelos de lenguaje al trabajar con APIs y bibliotecas.

Cómo Configurar Ref MCP

Hay dos métodos principales para configurar Ref MCP como un servidor MCP:

1. HTTP transmitible (Recomendado):

• Instala Ref MCP a través de clientes compatibles (como Cursor) utilizando los enlaces de instalación proporcionados o especificando la configuración del servidor directamente:

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

• Necesitas registrarte en ref.tools para obtener una clave de API.

2. Servidor stdio local (Legado):

"Ref": {
  "command": "npx",
  "args": ["ref-tools-mcp@latest"],
  "env": {
    "REF_API_KEY": <tu_api_key>
  }
}

• Requiere Node.js y npm.

Opcionalmente, para desarrollo y depuración locales, puedes clonar el repositorio de Ref MCP, instalar las dependencias con npm install y ejecutar con npm run dev.

Cómo Usar Ref MCP

1. Conecta tu agente o herramienta compatible con MCP al servidor Ref MCP utilizando la configuración descrita arriba.
2. Usa herramientas disponibles, como ref_search_documentation para buscar documentación de APIs, o ref_read_url para obtener y destilar contenido relevante de la documentación.
3. Los agentes pueden realizar búsquedas y lecturas iterativas, reduciendo inteligentemente el contexto solo a lo necesario para generar o comprender el código.
4. Para integraciones de OpenAI, Ref MCP asigna automáticamente sus herramientas a nombres de funciones compatibles con OpenAI.

Para desarrollo e inspección, usa el Inspector MCP para probar y monitorear interacciones visualmente.

Características Clave

• Recuperación de documentación eficiente en tokens: Devuelve solo las secciones más relevantes en contexto, evitando costos excesivos de tokens y degradación del rendimiento.
• Búsqueda iterativa y amigable para agentes: Adapta los resultados de búsqueda a lo largo de una sesión, sin repetir resultados para indicaciones similares.
• Enriquecimiento de contexto bajo demanda: Permite a los LLM extraer documentación exactamente cuando y donde se necesita.
• Soporta fuentes públicas y privadas: Busca en documentación pública, páginas web, GitHub, y recursos privados como repositorios internos o PDFs.
• Gestión de sesión integrada: Rastrea la trayectoria de búsqueda y lectura dentro de una sesión de agente para una curaduría de contexto óptima.
• Compatibilidad con OpenAI: Adapta automáticamente la nomenclatura de herramientas para un uso fluido con los agentes de investigación y codificación de OpenAI.

Casos de Uso

• Asistentes de código potenciado por IA: Aumenta los agentes de codificación (como Claude Desktop o Cursor) con acceso preciso a documentación técnica.
• Integración automática de API: Ayuda a los agentes a entender, implementar y solucionar problemas de endpoints de API al mostrar la documentación más relevante.
• Bots de revisión y auditoría de código: Proporciona a los agentes la capacidad de fetch y citar documentos autorizados al revisar código.
• Herramientas de incorporación de desarrolladores: Responde dinámicamente a preguntas comunes de desarrolladores buscando y extrayendo información de documentos de la empresa o públicos.
• Investigación técnica profunda: Consulta eficientemente múltiples fuentes y se centra en el conjunto de contexto más pequeño posible para respuestas precisas.

Preguntas Frecuentes

Q1: ¿Por qué es importante minimizar los tokens en el contexto de la documentación?
A1: Los LLM tienden a desempeñarse peor con ventanas de contexto grandes y ruidosas, y los tokens cuestan dinero. Al extraer solo las partes relevantes de la documentación, Ref MCP mejora el rendimiento de los LLM y reduce el gasto innecesario en API.

Q2: ¿Qué tipo de documentación puede buscar Ref MCP?
A2: Ref MCP busca una amplia gama de documentación pública (APIs, bibliotecas, docs web), y también puede indexar recursos privados/internos, incluyendo repositorios de GitHub y PDFs.

Q3: ¿Cómo asegura Ref MCP que los agentes de LLM no lean el mismo contenido repetidamente?
A3: Dentro de una sesión activa, Ref MCP rastrea búsquedas previas y resultados devueltos, asegurando que cada búsqueda similar produzca documentos nuevos y no duplicados, promoviendo una ingeniería de prompts eficiente.

Q4: ¿Puedo usar Ref MCP con mi propio agente o herramienta?
A4: Sí, cualquier agente o aplicación que soporte el protocolo MCP puede conectarse a Ref MCP utilizando los modos HTTP o stdio.

Q5: ¿Cuál es la diferencia entre ref_search_documentation y ref_read_url?
A5: ref_search_documentation encuentra enlaces de documentación relevantes y contexto mediante consulta; ref_read_url obtiene y transforma la página objetivo en un resumen en markdown para un consumo fácil por parte del agente.