Nexus

---

¿Qué es Nexus?

Nexus es un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona funcionalidad de búsqueda impulsada por IA a través de la API de OpenRouter. Se integra con clientes compatibles con MCP, incluidos Claude Desktop y Cursor, proporcionando capacidades de búsqueda mediante múltiples familias de modelos, incluyendo Perplexity Sonar (búsqueda web en tiempo real) y Grok 4 (conocimiento de datos de entrenamiento).

Características clave

• Implementación sin instalación: Ejecutable mediante bunx (o npx) sin requisitos de compilación
• Integración con OpenRouter: Múltiples modelos de IA, incluyendo Perplexity Sonar (búsqueda web) y Grok 4 (datos de entrenamiento)
• Cumplimiento del protocolo MCP: Implementa interfaces estándar de herramientas y recursos MCP
• Arquitectura de producción: Incluye caché de solicitudes, deduplicación, lógica de reintentos y manejo de errores
• Implementación con seguridad de tipos: Cobertura completa de TypeScript con verificación estricta de tipos

Características

Implementación

• Ejecución basada en Bunx/NPX con instalación local cero
• Compatibilidad multiplataforma (macOS, Linux, Windows)
• Requisito de runtime Bun 1.0+ o Node.js 18+
• Actualizaciones automáticas de versión a través del registro npm

Capacidades de búsqueda

• Múltiples niveles de modelos con diferentes capacidades:
  • sonar - Preguntas y respuestas rápidas, búsqueda web en tiempo real (tiempo de espera de 30s, nivel estándar)
  • sonar-pro - Consultas de múltiples pasos, búsqueda web en tiempo real (tiempo de espera de 60s, nivel premium)
  • sonar-reasoning-pro - Razonamiento de cadena de pensamiento, búsqueda web en tiempo real (tiempo de espera de 120s, nivel premium)
  • sonar-deep-research - Informes de investigación exhaustivos, búsqueda web en tiempo real (tiempo de espera de 300s, nivel premium)
  • grok-4 - Conocimiento de datos de entrenamiento, sin búsqueda en tiempo real (tiempo de espera de 60s, nivel premium)
• Búsqueda web en tiempo real con información actual (modelos Perplexity)
• Respuestas de conocimiento de datos de entrenamiento (Grok 4)
• Extracción estructurada de citas de las respuestas
• Parámetros de modelo configurables (temperatura, tokens máximos, anulación de tiempo de espera)

Arquitectura

• Manejo integral de errores con clases de error tipadas
• Caché de solicitudes con TTL configurable
• Deduplicación de solicitudes para consultas idénticas concurrentes
• Lógica automática de reintentos con retroceso exponencial
• Registro estructurado basado en Winston
• Implementación en modo estricto de TypeScript con cobertura completa de tipos

Inicio rápido

Requisitos previos

• Bun 1.0+ (recomendado) o Node.js 18+
• Clave de API de OpenRouter (regístrese en openrouter.ai)

Instalación rápida

Ejecute el servidor sin instalación local:

# Set your OpenRouter API key
export OPENROUTER_API_KEY=your-api-key-here

# Run the server via bunx (recommended)
bunx nexus-mcp

# Or via npx
npx nexus-mcp

El servidor se inicia y escucha conexiones de clientes MCP a través del transporte STDIO.

Prueba de la instalación

# Test the CLI help
bunx nexus-mcp --help

# Test the version
bunx nexus-mcp --version

# Run with your API key
OPENROUTER_API_KEY=your-key bunx nexus-mcp

Alternativa: Instalación local para desarrollo

Para desarrollo local o personalización:

1. Clone el repositorio:

git clone https://github.com/adawalli/nexus.git
cd nexus

2. Instale las dependencias:

bun install

3. Compile el servidor:

bun run build

4. Configure su clave de API de OpenRouter:

# Copy the example environment file
cp .env.example .env

# Edit .env and add your actual API key
# OPENROUTER_API_KEY=your-api-key-here

5. Pruebe el servidor:

bun run start

Integración con clientes MCP

Integración basada en Bunx (recomendada)

Configure los clientes MCP para ejecutar el servidor mediante bunx:

Claude Code

Configuración en ~/.claude/mcp_settings.json:

{
  "mcpServers": {
    "nexus": {
      "command": "bunx",
      "args": ["nexus-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Reinicie Claude Code después de los cambios de configuración.

Cursor

Agregue la configuración del servidor en la configuración MCP de Cursor:

• Nombre: nexus
• Comando: bunx
• Argumentos: ["nexus-mcp"]
• Variables de entorno: OPENROUTER_API_KEY=your-api-key-here

Reinicie Cursor después de los cambios de configuración.

Configuración genérica de clientes MCP

Parámetros estándar de conexión para clientes MCP:

• Transporte: stdio
• Comando: bunx
• Argumentos: ["nexus-mcp"]
• Entorno: OPENROUTER_API_KEY=your-api-key-here

Alternativa: npx o instalación local

Si no tiene Bun instalado, use npx en lugar de bunx en cualquiera de las configuraciones anteriores.

Para una instalación local (después de seguir la configuración de desarrollo local):

{
  "mcpServers": {
    "nexus": {
      "command": "bun",
      "args": ["run", "/path/to/nexus-mcp/dist/cli.js"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Uso

Una vez integrado, puede usar la herramienta de búsqueda en su cliente MCP:

Búsqueda básica

Use the search tool to find information about "latest developments in AI"

Búsqueda avanzada con parámetros

Search for "climate change solutions" using:
- Model: sonar-pro
- Max tokens: 2000
- Temperature: 0.3

Uso de diferentes modelos

# Fast Q&A with real-time web search (default)
Search for "latest news" with model: sonar

# Deep research with comprehensive analysis
Search for "AI safety research" with model: sonar-deep-research

# Knowledge from training data (no web search)
Search for "explain quantum computing" with model: grok-4

Herramientas disponibles

search

La herramienta de búsqueda principal que proporciona capacidades de búsqueda impulsadas por IA.

Parámetros:

• query (obligatorio): Consulta de búsqueda (1-2000 caracteres)
• model (opcional): Modelo a utilizar (predeterminado: sonar)
  • sonar - Preguntas y respuestas rápidas con búsqueda web en tiempo real (tiempo de espera de 30s)
  • sonar-pro - Consultas de múltiples pasos con búsqueda web en tiempo real (tiempo de espera de 60s, premium)
  • sonar-reasoning-pro - Razonamiento de cadena de pensamiento con búsqueda web en tiempo real (tiempo de espera de 120s, premium)
  • sonar-deep-research - Informes de investigación exhaustivos con búsqueda web en tiempo real (tiempo de espera de 300s, premium)
  • grok-4 - Conocimiento de datos de entrenamiento, sin búsqueda en tiempo real (tiempo de espera de 60s, premium)
• maxTokens (opcional): Tokens máximos de respuesta (1-4000, predeterminado: 1000)
• temperature (opcional): Aleatoriedad de respuesta (0-2, predeterminado: 0.3)
• timeout (opcional): Anular el tiempo de espera predeterminado en milisegundos (5000-600000)

Ejemplo de respuesta (modelo Perplexity):

Based on current information, here are the latest developments in AI...

[Detailed AI-generated response with current information]

---
**Search Metadata:**
- Model: perplexity/sonar
- Response time: 1250ms
- Tokens used: 850
- Timeout: 30000ms
- Search type: realtime
- Sources: 5 found

Ejemplo de respuesta (modelo Grok 4):

Quantum computing is a type of computation that harnesses quantum mechanics...

[Response based on training data knowledge]

---
**Search Metadata:**
- Model: x-ai/grok-4
- Response time: 3500ms
- Tokens used: 650
- Timeout: 60000ms
- Search type: training-data
- Cost tier: premium

Configuración

Variables de entorno

• OPENROUTER_API_KEY (obligatorio): Su clave de API de OpenRouter
• NODE_ENV (opcional): Configuración del entorno (development, production, test)
• LOG_LEVEL (opcional): Nivel de registro (debug, info, warn, error)

Configuración avanzada

El servidor admite configuración adicional a través de variables de entorno:

• OPENROUTER_TIMEOUT_MS: Tiempo de espera de solicitud en milisegundos (predeterminado: 30000)
• OPENROUTER_MAX_RETRIES: Intentos máximos de reintento (predeterminado: 3)
• OPENROUTER_BASE_URL: URL base personalizada de la API de OpenRouter

Recursos

El servidor proporciona un recurso de estado de configuración en config://status que muestra:

• Estado de salud del servidor
• Información de configuración (con clave de API enmascarada)
• Disponibilidad de la herramienta de búsqueda
• Tiempo de actividad y versión del servidor

Solución de problemas

Problemas específicos de Bunx/NPX

"bunx: command not found"

• Instale Bun: curl -fsSL https://bun.sh/install | bash
• O use npx si tiene Node.js 18+ instalado

"npx: command not found"

• Asegúrese de que Node.js 18+ esté instalado: node --version
• Actualice npm: npm install -g npm@latest

"Cannot find package 'nexus-mcp'"

• El paquete puede no estar publicado aún. Use la instalación local en su lugar
• Verifique la conectividad de red para el acceso al registro npm

Inicio lento en la primera ejecución

• Esto es normal en la primera ejecución, ya que el paquete se descarga
• Las ejecuciones posteriores serán más rápidas debido al caché
• Para un inicio más rápido, use la instalación local

Errores de "Permission denied" con npx

• Intente: npx --yes nexus-mcp --stdio
• O configure los permisos de npm: npm config set user 0 && npm config set unsafe-perm true

Problemas comunes

"Search functionality is not available"

• Asegúrese de que la variable de entorno OPENROUTER_API_KEY esté configurada
• Verifique que su clave de API sea válida en OpenRouter
• Revise los registros del servidor para detectar errores de inicialización

"Authentication failed: Invalid API key"

• Verifique el formato y la validez de su clave de API
• Asegúrese de que la clave tenga créditos/permisos suficientes
• Pruebe la clave directamente en el panel de OpenRouter

"Rate limit exceeded"

• Espere a que se restablezca el límite de velocidad (generalmente 1 minuto)
• Considere actualizar su plan de OpenRouter para límites más altos
• Supervise el uso en su panel de OpenRouter

Tiempos de espera de conexión

• Verifique su conexión a internet
• El servidor reintentará automáticamente las solicitudes fallidas
• Aumente el tiempo de espera si es necesario: OPENROUTER_TIMEOUT_MS=60000

El cliente MCP no puede conectarse al servidor

• Verifique que su configuración MCP use el comando y los argumentos correctos
• Compruebe que Bun 1.0+ o Node.js 18+ esté disponible en el entorno de su cliente MCP
• Asegúrese de que la clave de API esté configurada correctamente en las variables de entorno

Registro de depuración

Habilite el registro de depuración:

Para desarrollo local: Agregue LOG_LEVEL=debug a su archivo .env

Para clientes MCP: Agregue LOG_LEVEL: "debug" a la sección env de su configuración MCP

Esto proporcionará información detallada sobre:

• Carga de configuración
• Solicitudes y respuestas de API
• Detalles de errores y seguimientos de pila
• Métricas de rendimiento

Prueba de conexión

Puede probar si el servidor funciona verificando el recurso de estado de configuración en su cliente MCP, o ejecutando una consulta de búsqueda simple.

Desarrollo

Para desarrolladores que trabajan en este servidor:

# Development with hot reload
bun run dev

# Run tests
bun run test

# Run tests with coverage
bun run test:coverage

# Lint code
bun run lint

# Format code
bun run format

Costos de API

OpenRouter cobra por el uso de la API según el consumo de tokens:

• Precios: Consulte las tarifas actuales en Modelos de OpenRouter
• Monitoreo: Seguimiento de uso disponible en el panel de OpenRouter
• Límites: Configure límites de gasto en la configuración de su cuenta de OpenRouter
• Optimización: El servidor implementa caché de respuestas y deduplicación de solicitudes para minimizar llamadas API redundantes

📚 Documentación

🤝 Contribuciones

¡Damos la bienvenida a contribuciones de desarrolladores de todos los niveles de experiencia!

🚀 Cómo comenzar Haga un fork del repositorio Lea nuestra Guía de contribución Consulte los primeros problemas

🐛 Reportar problemas Informes de errores Solicitudes de funciones Hacer preguntas

💬 Únase a la comunidad Discusiones de GitHub Código de conducta Hoja de ruta y tablero del proyecto

🌟 Reconocimiento

Los contribuyentes son reconocidos en:

• Lista de contribuyentes
• Notas de versión para contribuciones significativas
• Destacados de la comunidad y testimonios

🔗 Proyectos relacionados

• Protocolo de Contexto de Modelo - El estándar que implementamos
• OpenRouter - Nuestro proveedor de modelos de IA
• Claude Desktop - Cliente MCP principal
• Cursor - Editor de código con IA con soporte MCP

📞 Soporte y comunidad

📄 Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

---