Cognigy.AI Management MCP

Cognigy.AI Management MCP Server

Servidor de Protocolo de Contexto de Modelo (MCP) para gestionar agentes virtuales de Cognigy.AI a través de la API de Management

Este es un servidor MCP independiente y de código abierto que no está afiliado, respaldado ni patrocinado por Cognigy o NiCE. Requiere tu propia cuenta válida de Cognigy.AI y una clave de API, utilizadas de acuerdo con los términos de licencia comercial de Cognigy. "Cognigy" y "Cognigy.AI" son marcas comerciales de sus respectivos propietarios.

¿Qué es esto?

cognigy-ai-mcp-management-server es un servidor MCP local que permite a los asistentes de codificación con IA (Claude, Cursor, etc.) crear, configurar, probar y operar agentes conversacionales de IA de Cognigy.AI de forma programática.

En lugar de navegar por la interfaz de Cognigy, ahora puedes:

• Crear y gestionar flujos, nodos e intenciones mediante lenguaje natural
• Ejecutar entrenamiento de NLU y pruebas de regresión automáticamente
• Desplegar instantáneas y paquetes entre entornos
• Configurar LLMs, Knowledge AI e integraciones

Diseñado para: Desarrolladores, arquitectos de soluciones y socios de integración que construyen sobre Cognigy.AI.

Requisitos

• Node.js 20.0.0 o superior
• Cuenta de Cognigy.AI con acceso a la API (Prueba, SaaS o local)
• Clave de API generada desde la interfaz de Cognigy (Mi Perfil → Claves de API)

Instalación

# 1. Install the Cognigy REST API client (required peer dependency)
npm install @cognigy/rest-api-client

# 2. Install this MCP server
npm install -g cognigy-ai-mcp-management-server

Importante: El paquete @cognigy/rest-api-client está licenciado bajo la "Licencia Propietaria de Cognigy". Al instalarlo, aceptas los términos de licencia de Cognigy.

Configuración

Establece las variables de entorno antes de ejecutar:

# Required: Your Cognigy API endpoint
export COGNIGY_BASE_URL=https://api-trial.cognigy.ai

# Required: Your API key (never commit this!)
export COGNIGY_API_KEY=your-api-key-here

# Optional: Default project for operations
export COGNIGY_DEFAULT_PROJECT_ID=your-project-id

URLs base comunes:

Entorno	URL base
Prueba	https://api-trial.cognigy.ai
SaaS UE	https://api-app.cognigy.ai
SaaS EE. UU.	https://api-app-us.cognigy.ai
Dedicado	https://api-<company>.cognigy.cloud

Configuración del cliente MCP

Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "cognigy": {
      "command": "npx",
      "args": ["cognigy-ai-mcp-management-server"],
      "env": {
        "COGNIGY_BASE_URL": "https://api-trial.cognigy.ai",
        "COGNIGY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code

Añade a .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "cognigy": {
      "command": "npx",
      "args": ["cognigy-ai-mcp-management-server"],
      "env": {
        "COGNIGY_BASE_URL": "https://api-trial.cognigy.ai",
        "COGNIGY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Añade a .cursor/mcp.json:

{
  "mcpServers": {
    "cognigy": {
      "command": "npx",
      "args": ["cognigy-ai-mcp-management-server"],
      "env": {
        "COGNIGY_BASE_URL": "https://api-trial.cognigy.ai",
        "COGNIGY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Herramientas disponibles

Todas las herramientas

Este servidor proporciona 132 herramientas MCP organizadas por dominio:

Categoría	Herramientas	Descripción
Proyectos y flujos	5	Listar proyectos, flujos, configuraciones de flujo, registros
Nodos	9	Operaciones CRUD, búsqueda, mover, generación de salida de IA
Intenciones y NLU	10	Gestión de intenciones, entrenamiento, puntuación, auditoría
Endpoints	2	Listar e inspeccionar configuraciones de endpoints
Sesiones	2	Inyectar/restablecer contexto de conversación
Conversaciones	3	Obtener conversaciones, transcripciones
Playbooks y pruebas	6	Ejecutar playbooks, pruebas de regresión
Instantáneas	9	Crear, restaurar, empaquetar, comparar, promover
Paquetes	7	Crear, fusionar, subir, descargar
Conexiones	5	Gestionar conexiones de API (secretos redactados)
LLMs	7	Configurar proveedores de IA generativa
Conectores NLU	5	NLU externo (Dialogflow, LUIS, etc.)
Knowledge AI	21	Almacenes, fuentes, fragmentos, conectores (RAG)
Funciones	9	Funciones de código personalizadas, instancias
Extensiones	6	Subir, configurar, gestionar extensiones
Perfiles de contacto	11	CRUD de perfiles, fusionar, exportar (RGPD)
Analítica	4	Métricas de conversación, llamadas, conocimiento
Auditoría	2	Registros de eventos de auditoría
Transferencia	7	Proveedores y servicios de agentes en vivo
Búsqueda	1	Búsqueda de recursos en toda la organización
Tareas	2	Seguimiento de estado de tareas asíncronas

Características clave

• Seguro por defecto: Todas las herramientas de mutación usan dryRun: true por defecto
• Consciente de asincronía: Las operaciones de larga duración consultan hasta completarse
• Seguridad: Claves de API solo en memoria, secretos redactados automáticamente
• Paginación: Todas las operaciones de listado admiten limit y skip

Desarrollo y pruebas

Desarrollo con mock primero

Ejecuta contra el servidor mock de Prism (sin necesidad de cuenta de Cognigy):

# Terminal 1: Start mock server
npm run mock

# Terminal 2: Run tests
npm test

Pruebas con API en vivo

# Create .env from template
cp .env.example .env
# Edit .env with your credentials

# Run development server
npm run dev

Compilación

npm run build    # Compile TypeScript
npm test         # Run test suite (49 tests)
npm run lint     # Check code style

Regenerar tipos (opcional)

Si necesitas actualizar los tipos generados desde una API de Cognigy más reciente:

npm run update:spec   # Download latest OpenAPI spec
npm run gen:types     # Regenerate TypeScript types

Importante: Dependencias

Este paquete requiere @cognigy/rest-api-client como dependencia par. Esto significa:

1. Debes instalarlo por separado (ver Instalación arriba)
2. Aceptas los términos de licencia de Cognigy al instalar su paquete
3. No incluimos ni redistribuimos ningún código de Cognigy

Eres responsable de:

• Revisar y aceptar los términos de la licencia propietaria de Cognigy
• Tener los derechos apropiados para usar la API de Cognigy
• Mantener seguras tus credenciales de API

El cliente de API REST de Cognigy es el SDK oficial mantenido por Cognigy GmbH y se publica en npm bajo la "Licencia Propietaria de Cognigy".

Licencia

Este servidor MCP se publica bajo la Licencia MIT. Consulta LICENCIA para más detalles.

Nota: La licencia MIT se aplica solo al código de este servidor MCP. Las dependencias (particularmente @cognigy/rest-api-client) están sujetas a sus propias licencias.

Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

1. Haz un fork del repositorio
2. Crea una rama de características (git checkout -b feature/amazing-feature)
3. Sigue los patrones de código existentes (esquemas Zod, banderas dryRun, etc.)
4. Añade pruebas para nuevas herramientas
5. Ejecuta npm test && npm run build antes de confirmar
6. Envía una solicitud de extracción (Pull Request)

Directrices de desarrollo

• Todas las herramientas deben tener validación de entrada Zod
• Las herramientas de mutación deben admitir la bandera dryRun (por defecto: true)
• Las descripciones de herramientas deben ser amigables para LLM (1-2 frases)
• Nunca registres ni expongas claves de API/secretos
• Prueba contra el servidor mock antes de la API en vivo

Soporte

• Problemas: GitHub Issues
• Documentación de Cognigy: docs.cognigy.com
• Especificación MCP: modelcontextprotocol.io

---

Construido con el SDK de Model Context Protocol