Servidor MCP de Onyx

Un servidor de Protocolo de Contexto de Modelo (MCP) para una integración perfecta con las bases de conocimiento de Onyx AI.

Este servidor MCP conecta cualquier cliente compatible con MCP a su base de conocimientos de Onyx, lo que le permite buscar y recuperar contexto relevante de sus documentos. Proporciona un puente entre los clientes MCP y la API de Onyx, lo que permite potentes funciones de búsqueda semántica y chat.

Características

• Búsqueda mejorada : Búsqueda semántica en sus conjuntos de documentos Onyx con filtrado de relevancia LLM

• Recuperación de ventana de contexto : recupera fragmentos por encima y por debajo del fragmento coincidente para un mejor contexto

• Recuperación completa de documentos : opción para recuperar documentos completos en lugar de solo fragmentos

• Integración de chat : utilice la potente API de chat de Onyx con LLM + RAG para obtener respuestas completas

• Filtrado de conjuntos de documentos configurables : seleccione conjuntos de documentos específicos para obtener resultados más relevantes

Related MCP server: atlas_mcp

Instalación

Instalación mediante herrería

Para instalar Onyx MCP Server para Claude Desktop automáticamente a través de Smithery :

npx -y @smithery/cli install @lupuletic/onyx-mcp-server --client claude

Prerrequisitos

• Node.js (v16 o superior)

• Una instancia de Onyx con acceso a API

• Un token API de Onyx

Configuración

1. Clonar el repositorio:

   git clone https://github.com/lupuletic/onyx-mcp-server.git
   cd onyx-mcp-server

2. Instalar dependencias:

   npm install

3. Construir el servidor:

   npm run build

4. Configura tu token API de Onyx:

   export ONYX_API_TOKEN="your-api-token-here"
   export ONYX_API_URL="http://localhost:8080/api"  # Adjust as needed

5. Iniciar el servidor:

   npm start

Configuración de clientes MCP

Para la aplicación de escritorio de Claude

Agregar a ~/Library/Application Support/Claude/claude_desktop_config.json :

{
  "mcpServers": {
    "onyx-search": {
      "command": "node",
      "args": ["/path/to/onyx-mcp-server/build/index.js"],
      "env": {
        "ONYX_API_TOKEN": "your-api-token-here",
        "ONYX_API_URL": "http://localhost:8080/api"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Para Claude en VSCode (Cline)

Agregue a su archivo de configuración de Cline MCP:

{
  "mcpServers": {
    "onyx-search": {
      "command": "node",
      "args": ["/path/to/onyx-mcp-server/build/index.js"],
      "env": {
        "ONYX_API_TOKEN": "your-api-token-here",
        "ONYX_API_URL": "http://localhost:8080/api"
      },
      "disabled": false, 
      "alwaysAllow": []
    }
  }
}

Para otros clientes de MCP

Consulta la documentación de tu cliente MCP para saber cómo agregar un servidor MCP personalizado. Necesitarás proporcionar:

• El comando para ejecutar el servidor ( node )

• La ruta al archivo del servidor creado ( /path/to/onyx-mcp-server/build/index.js )

• Variables de entorno para ONYX_API_TOKEN y ONYX_API_URL

Herramientas disponibles

Una vez configurado, su cliente MCP tendrá acceso a dos potentes herramientas:

1. Herramienta de búsqueda

La herramienta search_onyx proporciona acceso directo a las capacidades de búsqueda de Onyx con recuperación de contexto mejorada:

<use_mcp_tool>
<server_name>onyx-search</server_name>
<tool_name>search_onyx</tool_name>
<arguments>
{
  "query": "customer onboarding process",
  "documentSets": ["Company Policies", "Training Materials"],
  "maxResults": 3,
  "chunksAbove": 1,
  "chunksBelow": 1,
  "retrieveFullDocuments": true
}
</arguments>
</use_mcp_tool>

Parámetros:

• query (obligatoria): El tema a buscar

• documentSets (opcional): lista de nombres de conjuntos de documentos para buscar (vacío para todos)

• maxResults (opcional): Número máximo de resultados a devolver (predeterminado: 5, máximo: 10)

• chunksAbove (opcional): Número de fragmentos a incluir encima del fragmento correspondiente (predeterminado: 1)

• chunksBelow (opcional): Número de fragmentos a incluir debajo del fragmento correspondiente (predeterminado: 1)

• retrieveFullDocuments (opcional): si se deben recuperar documentos completos en lugar de solo fragmentos (valor predeterminado: falso)

2. Herramienta de chat

La herramienta chat_with_onyx aprovecha la potente API de chat de Onyx con LLM + RAG para obtener respuestas completas:

<use_mcp_tool>
<server_name>onyx-search</server_name>
<tool_name>chat_with_onyx</tool_name>
<arguments>
{
  "query": "What is our company's policy on remote work?",
  "personaId": 15,
  "documentSets": ["Company Policies", "HR Documents"],
  "chatSessionId": "optional-existing-session-id"
}
</arguments>
</use_mcp_tool>

Parámetros:

• query (obligatoria): La pregunta que debes hacerle a Onyx

• personaId (opcional): El ID de la persona a utilizar (predeterminado: 15)

• documentSets (opcional): lista de nombres de conjuntos de documentos para buscar (vacío para todos)

• chatSessionId (opcional): ID de sesión de chat existente para continuar una conversación

Sesiones de chat

La herramienta de chat permite mantener el contexto de la conversación en múltiples interacciones. Tras la primera llamada, la respuesta incluirá un chat_session_id en los metadatos. Puedes pasar este ID en llamadas posteriores para mantener el contexto.

Elegir entre búsqueda y chat

• Utilice la búsqueda cuando : necesite información específica y dirigida de los documentos y desee controlar exactamente cuánto contexto se recupera.

• Utilice el chat cuando : necesite respuestas completas que combinen información de múltiples fuentes o cuando desee que el LLM sintetice la información para usted.

Para obtener mejores resultados, puede utilizar ambas herramientas en combinación: buscar detalles específicos y chatear para obtener una comprensión completa.

Casos de uso

• Gestión del conocimiento : acceda a la base de conocimientos de su organización a través de cualquier interfaz compatible con MCP

• Atención al cliente : Ayude a los agentes de soporte a encontrar rápidamente información relevante

• Investigación : Realice una investigación profunda de los documentos de su organización.

• Capacitación : Proporcionar acceso a materiales de capacitación y documentación.

• Cumplimiento de políticas : garantizar que los equipos tengan acceso a las políticas y procedimientos más recientes

Desarrollo

Ejecutando en modo de desarrollo

npm run dev

Confirmando cambios

Este proyecto aplica la especificación de confirmaciones convencionales a todos los mensajes de confirmación. Para facilitarlo, ofrecemos una herramienta interactiva de confirmación:

npm run commit

Esto te guiará en la creación de un mensaje de confirmación con el formato correcto. Como alternativa, puedes escribir tus propios mensajes de confirmación siguiendo el formato convencional:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Donde type es uno de los siguientes: hazaña, corrección, documentación, estilo, refactorización, rendimiento, prueba, compilación, ci, tarea, reversión

Edificio para la producción

npm run build

Pruebas

Ejecute el conjunto de pruebas:

npm test

Ejecutar pruebas con cobertura:

npm run test:coverage

Pelusa

npm run lint

Solucionar problemas de pelusa:

npm run lint:fix

Integración continua

Este proyecto utiliza GitHub Actions para la integración y el despliegue continuos. La canalización de CI se ejecuta con cada envío a la rama principal y con las solicitudes de extracción. Realiza las siguientes comprobaciones:

• Pelusa

• Edificio

• Pruebas

• Informes de cobertura de código

Aumento y publicación de versiones automatizadas

Cuando un PR se fusiona con la rama principal, el proyecto determina automáticamente el tipo de actualización de versión adecuado y lo publica en npm. El sistema analiza tanto los títulos del PR como los mensajes de confirmación para determinar el tipo de actualización de versión.

1. Validación del título de PR : todos los títulos de PR se validan según la especificación de confirmaciones convencionales :

   • Los títulos de PR deben comenzar con un tipo (por ejemplo, feat: , fix: , docs: )

   • Esta validación ocurre automáticamente cuando se crea o actualiza un PR

   • Las solicitudes de relaciones públicas con títulos no válidos no pasarán la comprobación de validación

2. Validación de mensajes de confirmación : todos los mensajes de confirmación también se validan con el formato de confirmación convencional:

   • Los mensajes de confirmación deben comenzar con un tipo (por ejemplo, feat: , fix: , docs: )

   • Esto se aplica mediante ganchos git que se ejecutan cuando se confirma.

   • Las confirmaciones con mensajes no válidos serán rechazadas.

   • Utilice npm run commit para una herramienta interactiva de creación de mensajes de confirmación

3. Determinación de aumento de versión : el sistema analiza tanto el título de la PR como los mensajes de confirmación para determinar el aumento de versión adecuado:

   • Títulos de relaciones públicas que comienzan con feat o que contienen nuevas características → aumento de versión menor

   • Títulos de relaciones públicas que comienzan con fix o que contienen correcciones de errores → actualización de la versión del parche

   • Títulos de relaciones públicas que contienen BREAKING CHANGE o con un signo de exclamación → aumento de versión principal

   • Si el título de PR no indica un tipo de confirmación específico, el sistema analiza los mensajes de confirmación.

   • Se utiliza el tipo de actualización con mayor prioridad que se encuentre en cualquier mensaje de confirmación (mayor > menor > parche)

   • Si no se encuentran prefijos de confirmación convencionales, el sistema pasa automáticamente a una actualización de la versión del parche sin fallar.

4. Actualización y publicación de la versión :

   • Aumenta la versión en package.json según el control de versiones semántico

   • Confirma y envía el cambio de versión

   • Publica la nueva versión en npm

Este proceso automatizado garantiza un control de versiones consistente según la naturaleza de los cambios, siguiendo los principios de control de versiones semántico y elimina la gestión manual de versiones.

Contribuyendo

¡Agradecemos sus contribuciones! Consulte nuestra Guía de Contribución para más detalles.

Seguridad

Si descubre una vulnerabilidad de seguridad, siga nuestra Política de seguridad .

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.