Cisco Support MCP Server

Accede a las APIs de Soporte de Cisco para búsquedas de errores y otras tareas relacionadas con el soporte.

GitHub
33
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Soporte Cisco

npm version License: MIT TypeScript MCP Glama Cisco Code Exchange Docker CI/CD

Un servidor MCP (Protocolo de Contexto de Modelo) TypeScript listo para producción para las APIs de Soporte Cisco, con seguridad integral y soporte de transporte dual. Este servidor extensible proporciona acceso a múltiples APIs de Soporte Cisco, incluyendo Búsqueda de Errores, Gestión de Casos e información de Fin de Vida.

🚀 Características Actuales

  • Soporte Multi-API: 8 APIs de Soporte Cisco completamente implementadas (46 herramientas en total)
  • Servidor OAuth 2.1: ✨ Autenticación de grado de producción con control de acceso basado en alcances detallados
  • Soporte de Solicitud de Elucidación: Interacción dinámica con el usuario para recopilar parámetros faltantes
  • Modos de Autenticación Triple: stdio (sin autenticación), token Bearer (simple), OAuth 2.1 (producción)
  • Acceso a API Configurable: Habilite solo las APIs de Soporte Cisco a las que tenga acceso
  • Indicaciones Especializadas: 9 indicaciones de flujo de trabajo para escenarios guiados de soporte Cisco
  • Transporte Dual: stdio (clientes MCP locales) y HTTP (servidor remoto con autenticación)
  • Autenticación OAuth2: Gestión automática de tokens con la API de Cisco
  • Actualizaciones en Tiempo Real: Eventos enviados por el servidor para el modo HTTP
  • TypeScript: Seguridad de tipos completa e integración con el SDK de MCP
  • Seguridad de Producción: Helmet, CORS, validación de entrada, PKCE, validación de alcance
  • Soporte Docker: Implementación contenerizada con montajes de volumen de configuración OAuth
  • Registro Integral: Registro estructurado con marcas de tiempo

📊 APIs de Cisco Compatibles

El servidor admite las siguientes APIs de Soporte Cisco (configurables mediante la variable de entorno SUPPORT_API):

APIEstadoHerramientasDescripción
Análisis Mejorado (enhanced_analysis)⭐ RECOMENDADO6 herramientasHerramientas de análisis avanzado para una evaluación integral del producto
Errores (bug)✅ Completo14 herramientasBúsqueda de errores, detalles, búsquedas específicas por producto + herramientas mejoradas
Casos (case)✅ Completo4 herramientasGestión y operaciones de casos de soporte
EoX (eox)✅ Completo4 herramientasInformación de Fin de Vida/Venta y planificación del ciclo de vida
PSIRT (psirt)✅ Completo8 herramientasDatos de vulnerabilidades del Equipo de Respuesta a Incidentes de Seguridad de Productos
Producto (product)✅ Completo3 herramientasDetalles del producto, especificaciones e información técnica
Software (software)✅ Completo6 herramientasSugerencias de software, versiones y recomendaciones de actualización
Serial (serial)✅ Completo3 herramientasNúmero de serie para cobertura, garantía e información del producto
RMA (rma)✅ Completo3 herramientasSeguimiento y gestión de Autorización de Devolución de Mercancía
Smart Bonding (smart_bonding)⚠️ EXPERIMENTAL8 herramientasGestión completa del ciclo de vida de tickets y códigos TSP (NO PROBADO - requiere credenciales especiales)

Estado de Implementación: 8/8 APIs principales completas (100%) con 46 herramientas en total + 1 API experimental (8 herramientas)

Ejemplos de Configuración:

  • SUPPORT_API=enhanced_analysis - Solo herramientas de análisis mejorado (6 herramientas) ← RECOMENDADO para la mayoría de los usuarios
  • SUPPORT_API=bug - Todas las herramientas de la API de Errores, incluido el análisis mejorado (14 herramientas)
  • SUPPORT_API=bug,case,eox,psirt - APIs de soporte principales (28 herramientas)
  • SUPPORT_API=bug,case,eox,psirt,product,software - Todas las APIs implementadas (39 herramientas)
  • SUPPORT_API=all - Todas las APIs disponibles (incluye 2 APIs de marcador de posición)

Inicio Rápido

Instalación NPX (Recomendada)

Inicie en modo stdio para Claude Desktop:

npx mcp-cisco-support

Inicie el servidor HTTP con autenticación:

npx mcp-cisco-support --http
# Token displayed in console for authentication

Genere un token Bearer para el modo HTTP:

npx mcp-cisco-support --generate-token

Obtenga ayuda y vea todas las opciones:

npx mcp-cisco-support --help

Configuración del Entorno

  1. Genere el token de autenticación (para el modo HTTP):

    npx mcp-cisco-support --generate-token
export MCP_BEARER_TOKEN=<generated_token>

  2. Establezca las credenciales de la API de Cisco:

    export CISCO_CLIENT_ID=your_client_id_here
export CISCO_CLIENT_SECRET=your_client_secret_here
export SUPPORT_API=bug,case,eox,psirt,product,software  # All implemented APIs (recommended)

  3. Inicie el servidor:

    # For Claude Desktop (stdio mode)
npx mcp-cisco-support

# For HTTP access (with authentication)
npx mcp-cisco-support --http

Desarrollo Local

git clone https://github.com/sieteunoseis/mcp-cisco-support.git
cd mcp-cisco-support
npm install
npm run build
npm start

Integración con Claude Desktop

Requisitos Previos

  1. Obtenga las Credenciales de la API de Cisco:

    • Visite la Consola de API de Cisco
    • Cree una aplicación y obtenga su ID de Cliente y Secreto
    • Asegúrese de que la aplicación tenga acceso a la API de Errores

  2. Instale Claude Desktop:

    • Descárguelo desde Claude.ai
    • Asegúrese de estar usando una versión reciente que admita MCP

Configuración Paso a Paso

  1. Localice el Archivo de Configuración de Claude Desktop:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Cree o Edite el Archivo de Configuración:

    {
  "mcpServers": {
    "cisco-support": {
      "command": "npx",
      "args": ["-y", "mcp-cisco-support"],
      "env": {
        "CISCO_CLIENT_ID": "your_client_id_here",
        "CISCO_CLIENT_SECRET": "your_client_secret_here",
        "SUPPORT_API": "bug,product"
      }
    }
  }
}

    Nota: El indicador -y acepta automáticamente la instalación del paquete, lo cual es necesario para Claude Desktop, ya que se ejecuta en segundo plano sin interacción del usuario.

    Variables de Entorno Opcionales:

    Configure qué APIs habilitar con SUPPORT_API:

    • "enhanced_analysis" - Solo herramientas de análisis mejorado (recomendado para la mayoría de los usuarios)
    • "bug" - Solo la API de Errores (predeterminado)
    • "bug,product" - APIs de Errores + Producto (habilita el autocompletado de productos)
    • "all" - Todas las APIs disponibles
    • "bug,case,eox" - Múltiples APIs específicas

    Autocompletado de Productos (opcional, requiere que SUPPORT_API incluya product):

    "env": {
  "CISCO_CLIENT_ID": "your_client_id_here",
  "CISCO_CLIENT_SECRET": "your_client_secret_here",
  "SUPPORT_API": "bug,product",
  "CISCO_WEB_COOKIE": "JSESSIONID=...; OptanonConsent=..."
}

    Consulte la sección Autocompletado de Productos para obtener instrucciones de configuración.

  3. Reemplace Sus Credenciales:

    • Reemplace your_client_id_here con su ID de Cliente de Cisco real
    • Reemplace your_client_secret_here con su Secreto de Cliente de Cisco real

  4. Reinicie Claude Desktop:

    • Cierre Claude Desktop por completo
    • Vuelva a abrir la aplicación
    • El servidor MCP se cargará automáticamente

Verificación

Después de la configuración, debería poder:

  1. Preguntarle a Claude sobre errores de Cisco:

    "Search for bugs related to memory leaks in Cisco switches"

  2. Obtener detalles específicos de errores:

    "Get details for Cisco bug CSCab12345"

  3. Buscar por producto:

    "Find bugs affecting Cisco Catalyst 3560 switches"

Ejemplo de Uso en Claude Desktop

Una vez configurado, puede hacerle preguntas a Claude como:

  • Búsqueda Básica de Errores:

    • "Busca errores recientes relacionados con 'fallo' en productos de Cisco"
    • "Encuentra errores abiertos con severidad 1 o 2"
    • "Muéstrame errores modificados en los últimos 30 días"

  • Búsquedas Específicas por Producto:

    • "Encuentra errores para el ID de producto C9200-24P"
    • "Busca errores en Cisco Catalyst 9200 Series que afecten la versión 17.5.1"
    • "Muestra errores corregidos en la versión de software 17.5.2"

  • Detalles de Errores:

    • "Obtén detalles completos del error CSCab12345"
    • "Muéstrame información sobre los errores CSCab12345,CSCcd67890"

  • Filtrado Avanzado:

    • "Encuentra errores resueltos con severidad 3 modificados después del 2023-01-01"
    • "Busca errores en 'Cisco ASR 9000 Series' ordenados por severidad"
    • "¿Puedes mostrarme todos los errores de Cisco en los últimos 30 días para el producto Cisco Unified Communications Manager (CallManager)?" (usa búsqueda por palabras clave)
    • "Encuentra errores para Cisco Unified Communications Manager que afecten las versiones 14.0 y 15.0" (usa búsqueda por serie de producto)

Claude utilizará las herramientas MCP apropiadas para obtener datos en tiempo real de la API de Errores de Cisco y proporcionará respuestas completas con la información más reciente.

Indicaciones MCP

El servidor incluye más de 10 indicaciones especializadas para flujos de trabajo guiados de soporte Cisco:

  • 🔍 cisco-high-severity-search - Busca errores de alta severidad por producto o número de serie
  • 🚨 cisco-incident-investigation - Investiga síntomas y errores
  • 🔄 cisco-upgrade-planning - Investiga problemas antes de las actualizaciones
  • 🔧 cisco-maintenance-prep - Prepárese para ventanas de mantenimiento
  • 🔒 cisco-security-advisory - Investiga vulnerabilidades de seguridad
  • ⚠️ cisco-known-issues - Verifica problemas de versiones de software
  • 📋 cisco-case-investigation - Investiga casos de soporte
  • ⏰ cisco-lifecycle-planning - Planificación de fin de vida
  • 🎯 cisco-smart-search - Búsqueda inteligente con refinamiento automático
  • ✨ cisco-interactive-search - Búsqueda interactiva con elucidación

Soporte de Número de Serie: La mayoría de las indicaciones ahora aceptan un nombre de producto O un número de serie. Cuando proporcione un número de serie (por ejemplo, "SAL09232Q0Z"), el servidor busca automáticamente los detalles del producto y los utiliza para la búsqueda. Esto facilita la investigación de problemas cuando tiene un número de serie del dispositivo pero no conoce el modelo exacto del producto.

Cada indicación proporciona planes de investigación estructurados y recomendaciones de expertos.

Búsqueda Interactiva con Elucidación

La indicación cisco-interactive-search demuestra la función de elucidación de MCP, que permite al servidor solicitar dinámicamente información adicional a los usuarios durante la ejecución de herramientas. Esto hace que las búsquedas sean más naturales y ayuda a recopilar parámetros faltantes sin reiniciar solicitudes.

Ejemplo de Uso:

Use the "cisco-interactive-search" prompt with:
- initial_query: "memory leak"
- use_elicitation: true

Consulte examples/elicitation-example.md para ver ejemplos de uso detallados y ⚡ Indicaciones MCP para obtener documentación completa de las indicaciones.

🔍 Recursos MCP - Autocompletado de Productos

El servidor expone los datos de Cisco como Recursos MCP para acceso directo del cliente. Esto incluye una nueva función de Autocompletado de Productos que le permite buscar en el catálogo interno de productos de Cisco utilizando la cookie de sesión de su navegador.

Recursos de Producto Disponibles

Cuando SUPPORT_API incluye product, los siguientes recursos están disponibles:

Plantillas de Recursos (URI dinámicos):

  • cisco://products/{product_id} - Obtiene detalles del producto por ID (por ejemplo, C9300-24P, ISR4431)
  • cisco://products/autocomplete/{search_term} - ✨ NUEVO: Busca en el catálogo de productos por nombre o modelo

Recursos Estáticos:

  • cisco://products/catalog - Descripción general del catálogo de productos
  • cisco://products/autocomplete-help - ✨ NUEVO: Instrucciones de configuración para el autocompletado de productos

Configuración del Autocompletado de Productos

La función de autocompletado de productos requiere la cookie de sesión de Cisco.com para acceder a la API interna de Cisco.

Configuración Rápida:

  1. Inicie sesión en Cisco:

  2. Extraiga Su Cookie:

    • Abra las Herramientas de Desarrollo del navegador (F12)
    • Vaya a Aplicación/Almacenamiento > Cookies
    • Seleccione https://bst.cloudapps.cisco.com
    • Copie todos los valores de las cookies

  3. Establezca la Variable de Entorno:

    export CISCO_WEB_COOKIE="JSESSIONID=...; OptanonConsent=...; ..."

  4. Consulte los Productos:

    cisco://products/autocomplete/4431
cisco://products/autocomplete/catalyst
cisco://products/autocomplete/ASA

Ciclo de Vida de la Cookie:

  • Validez Típica: 24 horas
  • Actualización Recomendada: Diariamente antes de un uso intensivo
  • Señales de Expiración: Errores 401/403, mensajes de "Cookie expirada"

Para obtener instrucciones de configuración detalladas, consulte el recurso de ayuda:

cisco://products/autocomplete-help

Ejemplo de Respuesta

Consulta: cisco://products/autocomplete/4431

{
  "autoPopulateHMPProductDetails": [{
    "parentMdfConceptId": 286281708,
    "parentMdfConceptName": "Cisco 4000 Series Integrated Services Routers",
    "mdfConceptId": 284358776,
    "mdfConceptName": "Cisco 4431 Integrated Services Router",
    "mdfMetaclass": "Model"
  }]
}

Mejores Prácticas de Seguridad

  • ✅ Nunca confirme cookies - son como contraseñas
  • ✅ Use el archivo .env - ya está en .gitignore
  • ✅ Actualice regularmente - las cookies expiran después de ~24 horas
  • ✅ Supervise la actividad - verifique su cuenta de Cisco
  • ✅ Use una cuenta dedicada - no su inicio de sesión principal

Uso en Claude Desktop

Pregúntele a Claude:

  • "Muéstrame la ayuda para el autocompletado de productos"
  • "Busca el producto Cisco 4431 usando autocompletado"
  • "¿Cuál es el nombre completo del producto ISR4431?"
  • "Encuentra productos que coincidan con 'catalyst switch'"

Consulte docs/PRODUCT_AUTOCOMPLETE_SOLUTIONS.md para obtener detalles de implementación y docs/CISCO_COOKIE_ANALYSIS.md para obtener información sobre el ciclo de vida de las cookies.

⚠️ API de Cliente Smart Bonding (EXPERIMENTAL/SIN PROBAR)

El servidor incluye soporte experimental para la API de Cliente Smart Bonding de Cisco para la gestión de tickets y la clasificación de códigos de problemas. Esta función NO ESTÁ PROBADA y requiere credenciales especiales obtenidas a través de su Gerente de Cuenta de Cisco.

Características de Smart Bonding

Herramientas Disponibles (8 en total):

  • get_smart_bonding_tsp_codes - Recuperar detalles de TSP (Tecnología, Sub-Tecnología, Código de Problema) para la clasificación de tickets
  • pull_smart_bonding_tickets - Recuperar actualizaciones de tickets de Cisco que aún no se han obtenido
  • create_smart_bonding_ticket - Crear un nuevo ticket de soporte (devuelve credenciales de carga en la respuesta)
  • update_smart_bonding_ticket - Agregar notas de trabajo y actualizar el estado del ticket
  • upload_file_to_smart_bonding_ticket - Subir archivos usando las credenciales de la creación del ticket (PUT HTTPS a cxd.cisco.com)
  • escalate_smart_bonding_ticket - Escalar problemas críticos a Cisco
  • resolve_smart_bonding_ticket - Marcar tickets como resueltos con notas de resolución
  • close_smart_bonding_ticket - Cerrar tickets completados con diagnóstico y solución

Proceso de Carga de Archivos

Smart Bonding utiliza un mecanismo de carga separado de la API REST:

  1. Crear ticket → La respuesta incluye credenciales de carga (Campo80-82)
  2. Guardar credenciales → ¡No se pueden recuperar más tarde!
  3. Subir archivos → Usar la herramienta upload_file_to_smart_bonding_ticket o curl
  4. Expiración de 72 días → El token expira 72 días después de la creación

Credenciales de carga proporcionadas en la respuesta de creación del ticket:

  • Campo80: Dominio de carga (ej., cxd.cisco.com)
  • Campo81: Token de autenticación (contraseña)
  • Campo82: Marca de tiempo de expiración del token

Los archivos no se pueden modificar después de la carga: envíe nuevos archivos para correcciones.

Diferencias de Autenticación

La API de Smart Bonding utiliza un sistema de autenticación diferente al de las API estándar de Soporte de Cisco:

CaracterísticaAPI de Soporte EstándarAPI de Smart Bonding
Endpoint OAuth2https://id.cisco.com/oauth2/default/v1/tokenhttps://cloudsso.cisco.com/as/token.oauth2
Validez del Token12 horas1 hora
CredencialesAutoservicio a través del Portal de Desarrolladores de CiscoContactar al Gerente de Cuenta de Cisco
Variables de EntornoCISCO_CLIENT_ID, CISCO_CLIENT_SECRETSMART_BONDING_CLIENT_ID, SMART_BONDING_CLIENT_SECRET

Configuración

  1. Obtener Credenciales - Contacte a su Gerente de Cuenta de Cisco para solicitar acceso a la API de Smart Bonding

  2. Establecer Variables de Entorno:

    export SMART_BONDING_CLIENT_ID=your_smart_bonding_client_id
export SMART_BONDING_CLIENT_SECRET=your_smart_bonding_client_secret
export SMART_BONDING_ENV=production  # or 'staging' for test environment
export SUPPORT_API=smart_bonding     # Enable Smart Bonding API

  3. Usar Herramientas de Smart Bonding:

    • Obtener códigos TSP para la clasificación de tickets
    • Obtener nuevas actualizaciones de tickets
    • Crear/actualizar tickets con categorización de problemas estandarizada

Notas Importantes

  • ⚠️ EXPERIMENTAL/NO PROBADO - Esta implementación no se ha probado con credenciales reales de Smart Bonding
  • ⚠️ Se Requieren Credenciales Separadas - Smart Bonding utiliza credenciales OAuth2 diferentes a las API de Soporte estándar
  • ⚠️ No Incluido en SUPPORT_API=all - Debe habilitarse explícitamente con SUPPORT_API=smart_bonding
  • ⚠️ Se Requiere Acceso Especial - Contacte al Gerente de Cuenta de Cisco para el aprovisionamiento de credenciales
  • Las URL base difieren entre los entornos de staging y producción
  • Admite IDs de correlación para el rastreo de solicitudes de extremo a extremo

Ejemplo de Uso

# With Claude Desktop - add to claude_desktop_config.json
{
  "mcpServers": {
    "cisco-smart-bonding": {
      "command": "npx",
      "args": ["-y", "mcp-cisco-support"],
      "env": {
        "SMART_BONDING_CLIENT_ID": "your_id",
        "SMART_BONDING_CLIENT_SECRET": "your_secret",
        "SMART_BONDING_ENV": "production",
        "SUPPORT_API": "smart_bonding"
      }
    }
  }
}

Para detalles completos de implementación y arquitectura de API, consulte SMART_BONDING_IMPLEMENTATION.md.

Capturas de Pantalla

Integración con Claude Desktop

Claude Desktop Integration

Claude Desktop se conectó exitosamente al servidor MCP de Soporte de Cisco, demostrando la funcionalidad de búsqueda de bugs con respuestas en tiempo real de la API de Bugs de Cisco.

MCP Inspector

MCP Inspector Integration

MCP Inspector v0.14.0+ mostrando las herramientas disponibles y las capacidades de prueba de conectividad del servidor.

Métodos de Instalación Alternativos

Instalación Global

Si prefiere instalar globalmente en lugar de usar npx:

npm install -g mcp-cisco-support

Luego use esta configuración:

{
  "mcpServers": {
    "cisco-support": {
      "command": "mcp-cisco-support",
      "env": {
        "CISCO_CLIENT_ID": "your_client_id_here",
        "CISCO_CLIENT_SECRET": "your_client_secret_here",
        "SUPPORT_API": "bug"
      }
    }
  }
}

Instalación Local

Para desarrollo o configuraciones personalizadas:

git clone https://github.com/sieteunoseis/mcp-cisco-support.git
cd mcp-cisco-support
npm install
npm run build

Luego use esta configuración:

{
  "mcpServers": {
    "cisco-support": {
      "command": "node",
      "args": ["/path/to/mcp-cisco-support/dist/index.js"],
      "env": {
        "CISCO_CLIENT_ID": "your_client_id_here",
        "CISCO_CLIENT_SECRET": "your_client_secret_here",
        "SUPPORT_API": "bug"
      }
    }
  }
}

Solución de Problemas

Problemas Comunes

  1. Errores de "Comando no encontrado":

    • Asegúrese de que Node.js 18+ esté instalado
    • Pruebe la instalación global: npm install -g mcp-cisco-support
    • Verifique la ruta en su archivo de configuración

  2. Fallos de autenticación:

    • Verifique su ID de Cliente y Secreto
    • Asegúrese de que su aplicación de API de Cisco tenga acceso a la API de Bugs
    • Revise si hay errores tipográficos en el archivo de configuración

  3. El servidor MCP no carga:

    • Reinicie Claude Desktop por completo
    • Verifique la sintaxis del archivo de configuración con un validador JSON
    • Busque registros/mensajes de error de Claude Desktop

  4. Errores de permisos:

    • Asegúrese de que el archivo de configuración sea legible
    • En macOS/Linux, verifique los permisos de archivo: chmod 644 claude_desktop_config.json

Depuración

  1. Pruebe el servidor manualmente:

    npx mcp-cisco-support

    Esto debería iniciar el servidor en modo stdio sin errores.

  2. Valide su configuración: Use un validador JSON para asegurarse de que su archivo de configuración esté correctamente formateado.

  3. Revise los registros de Claude Desktop:

    • Busque mensajes de error relacionados con MCP en Claude Desktop
    • La aplicación generalmente muestra el estado de conexión de los servidores MCP

    Monitoree los registros en tiempo real (macOS):

    # Follow logs in real-time
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

    En Windows:

    # Check logs directory
%APPDATA%\Claude\logs\

Obtener Ayuda

Implementación con Docker

# Use pre-built image
docker pull ghcr.io/sieteunoseis/mcp-cisco-support:latest
docker run -p 3000:3000 \
  -e CISCO_CLIENT_ID=your_id \
  -e CISCO_CLIENT_SECRET=your_secret \
  -e SUPPORT_API=bug \
  ghcr.io/sieteunoseis/mcp-cisco-support:latest --http

# Or build locally
docker-compose up -d

🔐 Seguridad

  • Modo stdio: Sin autenticación (Claude Desktop, clientes locales)
  • Modo HTTP: Se requiere autenticación con token Bearer
# Generate secure token
npx mcp-cisco-support --generate-token

# Use token for HTTP mode
export MCP_BEARER_TOKEN=your_token
npx mcp-cisco-support --http

Consulte 🔒 Guía de Seguridad para la documentación completa de seguridad.

Configuración

Variables de Entorno

Cree un archivo .env con su configuración:

# 🔑 Cisco API OAuth2 Configuration (REQUIRED)
CISCO_CLIENT_ID=your_client_id_here
CISCO_CLIENT_SECRET=your_client_secret_here

# 🌐 Server Configuration
PORT=3000
NODE_ENV=development

# 🚀 API Support Configuration
# Enable specific Cisco Support APIs you have access to
# Options: bug, case, eox (plus planned: product, serial, rma, software, asd)
SUPPORT_API=bug,case,eox              # Multiple APIs
# SUPPORT_API=all                     # All available APIs  
# SUPPORT_API=bug                     # Single API (default)

# 🔐 HTTP Authentication Configuration (HTTP mode only)
# Custom Bearer token for HTTP authentication (optional - generates random if not set)
MCP_BEARER_TOKEN=your_custom_secure_token_here

# ⚠️ SECURITY WARNING: Only use in development/testing
# DANGEROUSLY_OMIT_AUTH=true          # Disables HTTP authentication entirely

Autenticación OAuth 2.1 (Avanzada)

Para autenticación de nivel de producción con control de acceso detallado, use el modo OAuth 2.1:

Inicio Rápido

# 1. Copy example configuration files
cp config/oauth-clients.example.json config/oauth-clients.json
cp config/oauth-secrets.example.json config/oauth-secrets.json

# 2. Edit config/oauth-clients.json to configure your clients
# 3. Add client secrets to config/oauth-secrets.json (optional, for confidential clients)

# 4. Start server in OAuth 2.1 mode
AUTH_TYPE=oauth2.1 npm run oauth:start
# or for development with hot reload:
npm run oauth:dev

Archivos de Configuración

config/oauth-clients.json - Configuración de clientes (puede controlarse por versiones):

{
  "clients": [
    {
      "client_id": "mcp_inspector_dev",
      "client_uri": "http://localhost:6274",
      "redirect_uris": ["http://localhost:6274/oauth/callback"],
      "scopes": ["mcp:bug", "mcp:psirt"],
      "grant_types": ["authorization_code"],
      "description": "MCP Inspector - Limited to Bug + Security APIs",
      "enabled": true
    }
  ],
  "settings": {
    "allow_dynamic_registration": true,
    "token_expiry_seconds": 3600
  }
}

config/oauth-secrets.json - Secretos de clientes (gitignored, nunca commitear):

{
  "secrets": {
    "mcp_inspector_prod": "your_production_secret_here"
  }
}

Ámbitos OAuth

Controle el acceso a la API con ámbitos detallados:

ÁmbitoAcceso a APIDescripción
mcpTodas las APIAcceso completo a todas las herramientas MCP
mcp:bugAPI de BugsBúsqueda de bugs y detalles solamente
mcp:caseAPI de CasosGestión de casos de soporte solamente
mcp:eoxAPI de EoXInformación de fin de vida solamente
mcp:psirtAPI de SeguridadAvisos de seguridad solamente
mcp:productAPI de ProductosInformación de productos solamente
mcp:softwareAPI de SoftwareSugerencias de software solamente
mcp:serialAPI de SerialBúsquedas de número de serie solamente
mcp:rmaAPI de RMAAutorización de devolución solamente

Mejor Práctica: Otorgue solo los ámbitos que cada aplicación necesita (principio de privilegio mínimo).

Variables de Entorno

Apunte a ubicaciones de archivos de configuración personalizados:

# OAuth 2.1 Configuration
AUTH_TYPE=oauth2.1

# Optional: Custom config paths (defaults shown)
OAUTH_CLIENTS_CONFIG=config/oauth-clients.json
OAUTH_SECRETS_CONFIG=config/oauth-secrets.json

# Optional: Custom issuer URL (defaults to http://localhost:PORT)
OAUTH2_ISSUER_URL=https://your-server.com

Endpoints OAuth

Cuando se ejecuta en modo OAuth 2.1, el servidor proporciona:

  • GET /.well-known/oauth-authorization-server - Metadatos de descubrimiento OAuth
  • GET /authorize - Endpoint de autorización (muestra página de consentimiento)
  • POST /authorize/approve - Aprobación de autorización
  • POST /token - Endpoint de token (PKCE requerido)
  • POST /register - Registro dinámico de clientes (si está habilitado)

Consulte docs/OAUTH_CLIENTS_CONFIG.md para la documentación completa de OAuth 2.1.

Integración con Claude Desktop

Configuración completa para Claude Desktop:

{
  "mcpServers": {
    "cisco-support": {
      "command": "npx",
      "args": ["-y", "mcp-cisco-support"],
      "env": {
        "CISCO_CLIENT_ID": "your_client_id_here",
        "CISCO_CLIENT_SECRET": "your_client_secret_here",
        "SUPPORT_API": "bug,case,eox"
      }
    }
  }
}

Configuración de Docker

Opción 1: Autenticación con Token Bearer

docker run -p 3000:3000 \
  -e CISCO_CLIENT_ID=your_client_id \
  -e CISCO_CLIENT_SECRET=your_client_secret \
  -e SUPPORT_API=bug,case,eox \
  -e MCP_BEARER_TOKEN=your_secure_token \
  ghcr.io/sieteunoseis/mcp-cisco-support:latest --http

Opción 2: Autenticación OAuth 2.1 (Producción)

# 1. Create local OAuth config directory
mkdir -p ./oauth-config
cp config/oauth-clients.example.json ./oauth-config/oauth-clients.json
cp config/oauth-secrets.example.json ./oauth-config/oauth-secrets.json

# 2. Edit ./oauth-config/oauth-clients.json and oauth-secrets.json

# 3. Run with volume mount
docker run -p 3000:3000 \
  -e CISCO_CLIENT_ID=your_client_id \
  -e CISCO_CLIENT_SECRET=your_client_secret \
  -e AUTH_TYPE=oauth2.1 \
  -e OAUTH_CLIENTS_CONFIG=/oauth-config/oauth-clients.json \
  -e OAUTH_SECRETS_CONFIG=/oauth-config/oauth-secrets.json \
  -v $(pwd)/oauth-config:/oauth-config:ro \
  ghcr.io/sieteunoseis/mcp-cisco-support:latest --http

Opción 3: Sin Autenticación (Solo Desarrollo)

docker run -p 3000:3000 \
  -e CISCO_CLIENT_ID=your_client_id \
  -e CISCO_CLIENT_SECRET=your_client_secret \
  -e DANGEROUSLY_OMIT_AUTH=true \
  ghcr.io/sieteunoseis/mcp-cisco-support:latest --http

Docker Compose con OAuth 2.1:

version: '3.8'
services:
  mcp-cisco-support:
    image: ghcr.io/sieteunoseis/mcp-cisco-support:latest
    ports:
      - "3000:3000"
    environment:
      - CISCO_CLIENT_ID=your_client_id
      - CISCO_CLIENT_SECRET=your_client_secret
      - AUTH_TYPE=oauth2.1
      - OAUTH_CLIENTS_CONFIG=/oauth-config/oauth-clients.json
      - OAUTH_SECRETS_CONFIG=/oauth-config/oauth-secrets.json
    volumes:
      - ./oauth-config:/oauth-config:ro
    command: ["node", "dist/index.js", "--http"]
    restart: unless-stopped

Endpoints de API

EndpointMétodoDescripción
/GETInformación del servidor y endpoints disponibles
/mcpPOSTEndpoint MCP principal (JSON-RPC sobre HTTP)
/messagesPOSTEndpoint MCP alternativo para compatibilidad con N8N
/sseGETConexión SSE con gestión de sesiones
/ssePOSTEndpoint de mensajes SSE heredado (obsoleto)
/sse/session/{sessionId}POSTEndpoint de mensajes MCP específico de sesión
/pingGETEndpoint de ping simple para pruebas de conectividad
/healthGETVerificación de salud con estado detallado

📚 Documentación

Para información detallada, consulte nuestra completa Wiki de GitHub:

Ejemplos de Uso

Ejemplos con cURL

# Test server connectivity
curl http://localhost:3000/ping

# Check health status
curl http://localhost:3000/health

# List available tools (main MCP endpoint)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/list"
  }'

# List available tools (alternative endpoint for N8N)
curl -X POST http://localhost:3000/messages \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/list"
  }'

# Test SSE connection (will show endpoint event)
curl -N http://localhost:3000/sse

# Search for bugs by keyword
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/call",
    "params": {
      "name": "search_bugs_by_keyword",
      "arguments": {
        "keyword": "crash",
        "severity": "1",
        "status": "open"
      }
    }
  }'

# Get specific bug details
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "tools/call",
    "params": {
      "name": "get_bug_details",
      "arguments": {
        "bug_ids": "CSCab12345"
      }
    }
  }'

Ejemplo de Cliente JavaScript

async function searchBugs(keyword) {
  const response = await fetch('http://localhost:3000/mcp', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: Date.now(),
      method: 'tools/call',
      params: {
        name: 'search_bugs_by_keyword',
        arguments: {
          keyword: keyword,
          page_index: 1,
          status: 'open'
        }
      }
    })
  });
  
  const result = await response.json();
  return result;
}

Monitoreo de Salud

El servidor proporciona un endpoint integral de verificación de salud:

curl http://localhost:3000/health

La respuesta incluye:

  • Estado del servidor
  • Estado del token OAuth2
  • Uso de memoria
  • Tiempo de actividad
  • Conexiones SSE activas

Características de Seguridad

  • Helmet: Cabeceras de seguridad
  • CORS: Intercambio de recursos entre orígenes
  • Validación de Entrada: Validación basada en esquemas
  • Ejecución sin Root: Seguridad de Docker
  • Variables de Entorno: Almacenamiento seguro de credenciales

Solución de Problemas

Problemas Comunes

  1. Falló la Autenticación OAuth2

    • Verifique CISCO_CLIENT_ID y CISCO_CLIENT_SECRET
    • Revise la conectividad de red a https://id.cisco.com

  2. Llamadas a API Fallando

    • Verifique la validez del token en /health
    • Verifique el acceso de red a https://apix.cisco.com

  3. Problemas con Docker

    • Asegúrese de que las variables de entorno estén configuradas
    • Revise los registros de Docker: docker-compose logs

Registros

Los registros JSON estructurados incluyen:

  • Marca de tiempo
  • Nivel de registro (info, error, warn)
  • Mensaje
  • Datos de contexto adicionales

Pruebas

Ejecutar Pruebas

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run specific test suite
npx jest tests/auth.test.js
npx jest tests/mcp-tools.test.js

Estructura de Pruebas

El conjunto de pruebas incluye:

  • Pruebas de Autenticación (tests/auth.test.js): Autenticación OAuth2, gestión de tokens, manejo de errores
  • Pruebas de Herramientas MCP (tests/mcp-tools.test.js): Las 8 herramientas MCP, manejo de errores, paginación
  • Configuración (tests/setup.js): Configuración del entorno de pruebas

Correcciones Recientes de Pruebas

Los siguientes problemas fueron identificados y resueltos en el conjunto de pruebas:

✅ Problemas Corregidos

  1. Lógica de Refresco de Token

    • Problema: El cálculo de expiración del token era incorrecto en getValidToken()
    • Solución: Se corrigió la condición para verificar adecuadamente si el token está dentro del margen de refresco
    • Impacto: Comportamiento adecuado de caché y refresco de tokens

  2. Manejo de Múltiples IDs de Bugs

    • Problema: Fuga de estado entre pruebas que causaba desajustes en las secuencias simuladas
    • Solución: Se implementó la función resetServerState() para una limpieza adecuada
    • Impacto: Resultados de prueba consistentes en múltiples ejecuciones

  3. Implementación de Herramientas de Búsqueda

    • Problema: El mismo problema de gestión de estado que afectaba la búsqueda por palabras clave y otras herramientas
    • Solución: Reinicio adecuado del estado del servidor entre pruebas
    • Impacto: Las 8 herramientas MCP ahora funcionan correctamente

  4. Manejo de Errores

    • Problema: Los errores de API y los tiempos de espera de red no se convertían adecuadamente en respuestas de error MCP
    • Solución: Manejo de errores mejorado en la función handleMCPMessage()
    • Impacto: Respuestas de error adecuadas para aplicaciones cliente

  5. Escenarios de Fallo de Autenticación

    • Problema: El endpoint de salud devolvía 200 en lugar de 503 en fallos de autenticación
    • Solución: Limpieza de caché de módulos y aislamiento adecuado del estado
    • Impacto: Reporte correcto del estado de salud

  6. Gestión del Estado de Pruebas

    • Problema: Variables a nivel de módulo que persisten entre pruebas
    • Solución: Se añadió la exportación resetServerState() y la limpieza adecuada de la caché de módulos
    • Impacto: Verdadero aislamiento de pruebas y resultados de prueba confiables

Configuración de Pruebas

  • Jest: Uso de Jest con la bandera --forceExit para ejecuciones de prueba principales
  • Restablecimiento de Estado: Cada prueba obtiene una instancia de servidor nueva con estado limpio
  • Gestión de Mocks: Mocking de fetch adecuado con manejo correcto de secuencias
  • Aislamiento de Pruebas: La limpieza de la caché de módulos evita fugas de estado

Detalles Clave de Implementación

  • Fetch nativo: Usa el fetch nativo de Node.js en lugar de bibliotecas externas
  • Gestión de Tokens: Validez del token de 12 horas con margen de actualización de 30 minutos
  • Manejo de Errores: Manejo integral de errores con respuestas de error MCP adecuadas
  • Seguridad: Cabeceras de seguridad Helmet, soporte CORS, validación de entrada
  • Registro: Registro JSON estructurado con marcas de tiempo

Desarrollo

Estructura del Proyecto

mcp-cisco-support/
├── src/
│   └── index.ts        # Main TypeScript server implementation
├── dist/               # Compiled JavaScript (generated by build)
├── package.json        # Dependencies and scripts
├── tsconfig.json       # TypeScript configuration
├── .env.example       # Environment variables template
├── .env               # Actual environment variables (create from example)
├── .gitignore         # Git ignore rules
├── Dockerfile         # Docker configuration
├── docker-compose.yml # Docker Compose setup
├── screenshots/        # Documentation screenshots
│   └── mcp-inspector-screenshot.png
├── CLAUDE.md          # Project instructions and architecture
└── README.md          # Project documentation

Comandos de Desarrollo

# Install dependencies
npm install

# Start development server with auto-reload
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build Docker image
docker build -t mcp-cisco-support .

# View logs in development
npm run dev 2>&1 | jq '.'  # Pretty print JSON logs

Consideraciones de Rendimiento

  • El almacenamiento en caché de tokens reduce las llamadas a la API
  • La paginación limita los resultados a 10 por página
  • El latido SSE cada 30 segundos mantiene las conexiones activas
  • El tiempo de espera de solicitud se establece en 30 segundos

Notas de Seguridad

  • Nunca confirme el archivo .env en el control de versiones
  • Use variables de entorno para todos los secretos
  • Revise los límites de uso y los términos de la API de Cisco
  • Supervise los registros para detectar actividad sospechosa

Referencia de la API

Autenticación

  • URL de OAuth2: https://id.cisco.com/oauth2/default/v1/token
  • Tipo de Concesión: client_credentials
  • Validez del Token: 12 horas
  • Actualización Automática: 30 minutos antes de la expiración

URL Base de la API de Bugs

  • URL Base: https://apix.cisco.com/bug/v2.0

Protocolo MCP

El servidor implementa el Protocolo de Contexto de Modelo con estos métodos:

  • initialize: Inicializar conexión MCP
  • tools/list: Listar herramientas disponibles
  • tools/call: Ejecutar una herramienta

Ejemplo de mensaje MCP:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "search_bugs_by_keyword",
    "arguments": {
      "keyword": "memory leak",
      "status": "open"
    }
  }
}

Monitoreo de Salud

El servidor proporciona un endpoint integral de verificación de salud:

curl http://localhost:3000/health

La respuesta incluye estado del servidor, estado del token OAuth2, uso de memoria, tiempo de actividad y conexiones activas.

Pruebas

Marco de pruebas integral basado en Jest con:

  • ✅ 46/46 herramientas probadas - Todas las herramientas MCP en 8 APIs
  • ✅ Pruebas con Mocks y API Real - Pruebas unitarias con mocks + pruebas de integración con APIs en vivo
  • ✅ Pruebas de herramientas individuales - Ejecutor de pruebas independiente para desarrollo
# Run all tests
npm test

# Test with real API credentials
CISCO_CLIENT_ID=your_id CISCO_CLIENT_SECRET=your_secret npm test

# Test individual tools
npm run test:tool search_bugs_by_keyword

Consulte 🧪 Marco de Pruebas para obtener documentación completa de pruebas.

Licencia

Licencia MIT - consulte el archivo LICENSE para obtener detalles.

Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Realice sus cambios
  4. Añada pruebas para la nueva funcionalidad
  5. Asegúrese de que todas las pruebas pasen: npm test
  6. Envíe una solicitud de extracción

Soporte

Recursos

Recursos Externos