Servidor MCP de agentes de OpenRouter

Una implementación de servidor de Protocolo de Contexto de Modelo (MCP) para OpenRouter que ofrece sofisticadas capacidades de agente de investigación. Este servidor permite que su LLM conversacional delegue la investigación a un orquestador de investigación de Claude que utiliza diferentes agentes especializados basados en diversos modelos de OpenRouter.

🚀 Nueva rama beta (29/03/2025)

Descripción técnica del servidor MCP de OpenRouter Agents

El servidor MCP de OpenRouter Agents implementa un sofisticado sistema de orquestación para la investigación basada en IA. Este resumen destaca los componentes técnicos y las capacidades clave de la última versión beta (29/03/2025).

Arquitectura central

• Protocolo de contexto de modelo (MCP) : implementación completa con transportes STDIO y HTTP/SSE
• Orquestación multiagente : sistema jerárquico con roles de agente de planificación, investigación y contexto
• Base de datos de incrustación de vectores : PGLite con pgvector para el almacenamiento de conocimiento semántico
• Equilibrio de carga round-robin : distribuye las tareas de investigación entre diferentes modelos para obtener resultados óptimos
• Sistema de respaldo adaptativo : degradación del modelo de alto a bajo costo cuando falla la investigación primaria

Capacidades de investigación

• Planificación en varias etapas : Claude 3.7 Sonnet descompone consultas complejas en subpreguntas especializadas
• Ejecución paralela : investigación simultánea en varios LLM para obtener resultados integrales
• Refinamiento consciente del contexto : planificación de segunda etapa que identifica y llena los vacíos en la investigación inicial
• Base de conocimiento semántico : la búsqueda vectorial encuentra investigaciones pasadas relevantes para mejorar nuevas consultas
• Síntesis adaptativa : el agente contextual integra los hallazgos con niveles y formatos de audiencia personalizables

Mejoras recientes

• Resiliencia entre modelos : el manejo integral de errores permite que la investigación siga fluyendo a pesar de las fallas de los modelos individuales
• Almacenamiento en caché dinámico : optimización inteligente de TTL y caché según la complejidad de la consulta
• Resiliencia de base de datos : lógica de reintento con retroceso exponencial para operaciones de base de datos
• Programación defensiva : operaciones seguras contra valores nulos en todo el código base
• Comentarios de usuario mejorados : sistema de calificación con recuperación de errores detallada
• Pruebas integrales : funcionalidad verificada en las cinco herramientas MCP

La versión beta mejora la fiabilidad y la calidad de la investigación mediante mejoras arquitectónicas, manteniendo la simplicidad de la implementación original. El sistema se integra a la perfección con Cline en VS Code y la aplicación de escritorio Claude, ofreciendo capacidades de investigación de nivel empresarial en un paquete completo.

Estas mejoras ofrecen una experiencia de investigación más fiable y potente, a la vez que mantienen la facilidad de uso del servidor. Para probar la versión beta:

🌟Apoya este proyecto

Si este proyecto te resulta útil, ¡considera darle una estrella en GitHub! Tu apoyo nos ayuda a mejorarlo.

¡Sus comentarios y contribuciones son siempre bienvenidos!

Prerrequisitos

• Node.js (se recomienda v18 o posterior) y npm
• Git
• Una clave API de OpenRouter (obtenga una en https://openrouter.ai/ )

Características

• Planificación de la investigación con Claude 3.7 Soneto (modo de pensamiento)
• Múltiples agentes de investigación impulsados por varios LLM de OpenRouter
• Asignación rotatoria de modelos a tareas de investigación
• Opciones de costo configurables (alto/bajo) para diferentes necesidades de investigación
• Autónomo sin dependencias de bases de datos externas
• Almacenamiento en caché en memoria para tiempos de respuesta rápidos
• PGLite con extensión vectorial para almacenamiento persistente y búsqueda de similitud

Cómo funciona

1. Cuando envía una consulta de investigación, el agente de planificación (Claude 3.7 Sonnet) la divide en múltiples preguntas de investigación especializadas.
2. Cada pregunta de investigación se asigna a un agente de investigación diferente utilizando LLM de alto o bajo costo.
3. Los resultados de todos los agentes se sintetizan en un informe de investigación completo.
4. Los resultados se almacenan en caché en la memoria y se almacenan de forma persistente con capacidades de búsqueda vectorial integradas.
5. Se le devuelve el informe final contextualizado.

Instalación (Node.js / Estándar)

Este es el método recomendado para la integración con clientes MCP como Cline en VS Code.

1. Clonar este repositorio:
   git clone https://github.com/wheattoast11/openrouter-deep-research-mcp.git cd openrouter-agents
2. Instalar dependencias:
   npm install
3. Crea tu archivo .env a partir del ejemplo:
   cp .env.example .env
   (En Windows, puedes usar copy .env.example .env )
4. Edite el archivo .env y agregue su clave API de OpenRouter:
   OPENROUTER_API_KEY=your_api_key_here
   (Asegúrese de que este archivo esté guardado en el directorio raíz del proyecto)

Integración MCP de Cline/VS Code (recomendada)

Para utilizar este servidor con Cline en VS Code, debe agregarlo a su archivo de configuración de MCP.

1. Localice su archivo de configuración Cline MCP:
   • Normalmente se encuentra en: c:\Users\YOUR_USERNAME\AppData\Roaming\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json (Windows) o ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (macOS). Reemplace YOUR_USERNAME según corresponda.
2. Edite el archivo cline_mcp_settings.json : Agregue el siguiente objeto de configuración dentro del objeto principal mcpServers . Asegúrese de reemplazar "YOUR_PROJECT_PATH_HERE" con la ruta absoluta donde clonó este repositorio y "YOUR_OPENROUTER_API_KEY_HERE" con su clave API.
   { "mcpServers": { // ... potentially other existing servers ... "openrouter-research-agents": { "command": "cmd.exe", "args": [ "/c", "YOUR_PROJECT_PATH_HERE/start-mcp-server.bat" ], "env": { // IMPORTANT: Replace with your actual OpenRouter API Key "OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY_HERE" }, "disabled": false, // Ensure the server is enabled "autoApprove": [ "conduct_research", "research_follow_up", "get_past_research", "rate_research_report", "list_research_history" ] } // ... potentially other existing servers ... } }
   • ¿Por qué usar el archivo por lotes? Usarlo garantiza que el servidor se inicie con el entorno y el contexto de directorio adecuados.
   • ¿Por qué la clave API en env ? Aunque el servidor usa dotenv para cargar el archivo .env , proporcionar la clave en el bloque env garantiza que el proceso del servidor siempre tenga acceso a él.
3. Guarde el archivo de configuración. Cline debería detectar automáticamente la nueva configuración del servidor. Si no aparece inmediatamente, es posible que deba reiniciar VS Code o la extensión Cline.

Una vez configurado, verás la conduct_research y otras herramientas de investigación disponibles en Cline. Puedes usarlas así:

O especifique una preferencia de costo:

Modelos disponibles

Modelos de alto costo

• perplejidad/sonar-investigación-profunda
• perplejidad/sonar-pro
• perplejidad/sonar-razonamiento-pro
• openai/gpt-4o-search-preview

Modelos de bajo costo

• perplejidad/razonamiento sonar
• openai/gpt-4o-mini-vista previa-de-búsqueda
• google/gemini-2.0-flash-001

Personalización

Puede personalizar los modelos disponibles editando el archivo .env :

También puede personalizar la configuración de la base de datos y del caché en el archivo .env :

Instalación alternativa: HTTP/SSE para la aplicación de escritorio Claude

El servidor también se puede ejecutar como un servicio HTTP/SSE independiente para la integración con la aplicación de escritorio Claude.

Pasos de instalación de HTTP/SSE

1. Clonar este repositorio (si aún no lo ha hecho):
   git clone https://github.com/wheattoast11/openrouter-deep-research-mcp.git cd openrouter-agents
2. Cree y configure su archivo .env como se describe en la instalación estándar (Pasos 3 y 4).
3. Inicie el servidor usando npm:
   npm start
4. El servidor MCP se ejecutará y será accesible a través de HTTP/SSE en http://localhost:3002 (o el puerto especificado en su .env ).

Integración de la aplicación de escritorio Claude (HTTP/SSE)

1. Abra la aplicación de escritorio de Claude.
2. Vaya a Configuración > Desarrollador.
3. Haga clic en "Editar configuración".
4. Agregue lo siguiente a la matriz mcpServers en la configuración:
   { "type": "sse", "name": "OpenRouter Research Agents (HTTP)", // Differentiate if also using STDIO "host": "localhost", "port": 3002, // Or your configured port "streamPath": "/sse", "messagePath": "/messages" }
5. Guarde y reinicie Claude.

Persistencia y almacenamiento de datos

Este servidor utiliza:

• Caché en memoria : para un almacenamiento en caché de respuesta eficiente (usando node-cache)
• PGLite con pgvector : para el almacenamiento persistente de informes de investigación y capacidades de búsqueda de vectores
  • Los informes de investigación se almacenan con incrustaciones vectoriales para la búsqueda de similitud semántica.
  • La búsqueda vectorial se utiliza para encontrar investigaciones pasadas relevantes para nuevas consultas.
  • Todos los datos se almacenan localmente en el directorio de datos especificado (predeterminado: './researchAgentDB')

Solución de problemas

• Problemas de conexión : asegúrese de que la configuración de desarrollador de Claude coincida con la configuración del servidor
• Errores de clave API : Verifique que su clave API de OpenRouter sea correcta
• No se encontraron agentes : si la planificación falla, asegúrese de que Claude esté analizando el XML correctamente
• Errores de modelo : Verifique si los modelos especificados están disponibles en su cuenta de OpenRouter

Configuración avanzada

La configuración del servidor se puede modificar en config.js . Puedes ajustar lo siguiente:

• Modelos disponibles
• Preferencias de costos predeterminadas
• Configuración del agente de planificación
• Puerto y configuración del servidor
• Configuración de base de datos y caché

Seguridad de autenticación

A partir de la última actualización, la autenticación de clave API ahora es obligatoria de forma predeterminada para el transporte HTTP/SSE:

1. Establezca la variable de entorno SERVER_API_KEY en su archivo .env para producción:
   SERVER_API_KEY=your_secure_api_key_here
2. Solo para desarrollo/pruebas, puede deshabilitar la autenticación configurando:
   ALLOW_NO_API_KEY=true

Esto proporciona mayor seguridad para las implementaciones de producción y al mismo tiempo mantiene la flexibilidad para el desarrollo y las pruebas.

Herramientas de prueba

El repositorio incluye varias herramientas de prueba para verificar la implementación:

1. Pruebas básicas de herramientas :
   test-all-tools.bat
   Este script prueba las cinco herramientas MCP de forma aislada para verificar que funcionan correctamente.
2. Prueba del servidor MCP :
   test-mcp-server.js
   Prueba la implementación del servidor MCP, incluidas todas las opciones de transporte.
3. Pruebas de agentes de investigación :
   test-research-agent.js
   Prueba la funcionalidad principal del agente de investigación con llamadas API de OpenRouter reales.

Estas herramientas ayudan a garantizar que todos los componentes funcionen correctamente después de cualquier modificación.

Licencia

Instituto Tecnológico de Massachusetts (MIT)