Cisco Support MCP Server

Acesse as APIs de Suporte Cisco para pesquisas de bugs e outras tarefas relacionadas ao suporte.

GitHub
32

Documentação

Cisco Support MCP Server

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

Um servidor MCP (Model Context Protocol) TypeScript pronto para produção para as APIs de Suporte da Cisco, com segurança abrangente e suporte a transporte duplo. Este servidor extensível fornece acesso a múltiplas APIs de Suporte da Cisco, incluindo Busca de Bugs, Gerenciamento de Casos e informações de Fim de Vida.

🚀 Recursos Atuais

  • Suporte Multi-API: 8 APIs de Suporte da Cisco totalmente implementadas (46 ferramentas no total)
  • Servidor OAuth 2.1: ✨ Autenticação de nível de produção com controle de acesso baseado em escopos granulares
  • Suporte a ElicitationRequest: Interação dinâmica com o usuário para coletar parâmetros ausentes
  • Três Modos de Autenticação: stdio (sem autenticação), token Bearer (simples), OAuth 2.1 (produção)
  • Acesso a API Configurável: Habilite apenas as APIs de Suporte da Cisco às quais você tem acesso
  • Prompts Especializados: 9 prompts de fluxo de trabalho para cenários guiados de suporte Cisco
  • Transporte Duplo: stdio (clientes MCP locais) e HTTP (servidor remoto com autenticação)
  • Autenticação OAuth2: Gerenciamento automático de tokens com a API da Cisco
  • Atualizações em Tempo Real: Server-Sent Events para o modo HTTP
  • TypeScript: Segurança total de tipos e integração com o SDK MCP
  • Segurança de Produção: Helmet, CORS, validação de entrada, PKCE, validação de escopo
  • Suporte a Docker: Implantação em contêiner com montagens de volume de configuração OAuth
  • Registro Abrangente: Logs estruturados com carimbos de data/hora

📊 APIs da Cisco Suportadas

O servidor suporta as seguintes APIs de Suporte da Cisco (configuráveis via variável de ambiente SUPPORT_API):

APIStatusFerramentasDescrição
Enhanced Analysis (enhanced_analysis)⭐ RECOMENDADA6 ferramentasFerramentas avançadas de análise para avaliação abrangente de produtos
Bug (bug)✅ Completa14 ferramentasBusca de Bugs, Detalhes, buscas específicas por produto + ferramentas aprimoradas
Case (case)✅ Completa4 ferramentasGerenciamento e operações de casos de suporte
EoX (eox)✅ Completa4 ferramentasInformações de Fim de Vida/Fim de Venda e planejamento de ciclo de vida
PSIRT (psirt)✅ Completa8 ferramentasDados de vulnerabilidades do Product Security Incident Response Team
Product (product)✅ Completa3 ferramentasDetalhes de produtos, especificações e informações técnicas
Software (software)✅ Completa6 ferramentasSugestões de software, versões e recomendações de atualização
Serial (serial)✅ Completa3 ferramentasNúmero de série para cobertura, garantia e informações do produto
RMA (rma)✅ Completa3 ferramentasRastreamento e gerenciamento de Autorização de Devolução de Mercadoria
Smart Bonding (smart_bonding)⚠️ EXPERIMENTAL8 ferramentasGerenciamento completo do ciclo de vida de tickets e códigos TSP (NÃO TESTADA - requer credenciais especiais)

Status de Implementação: 8/8 APIs principais completas (100%) com 46 ferramentas no total + 1 API experimental (8 ferramentas)

Exemplos de Configuração:

  • SUPPORT_API=enhanced_analysis - Somente ferramentas de análise aprimorada (6 ferramentas) ← RECOMENDADA para a maioria dos usuários
  • SUPPORT_API=bug - Todas as ferramentas da API Bug, incluindo análise aprimorada (14 ferramentas)
  • SUPPORT_API=bug,case,eox,psirt - APIs de suporte principais (28 ferramentas)
  • SUPPORT_API=bug,case,eox,psirt,product,software - Todas as APIs implementadas (39 ferramentas)
  • SUPPORT_API=all - Todas as APIs disponíveis (inclui 2 APIs placeholder)

Início Rápido

Instalação via NPX (Recomendada)

Inicie no modo stdio para Claude Desktop:

npx mcp-cisco-support

Inicie o servidor HTTP com autenticação:

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

Gere token Bearer para o modo HTTP:

npx mcp-cisco-support --generate-token

Obtenha ajuda e veja todas as opções:

npx mcp-cisco-support --help

Configuração do Ambiente

  1. Gere o token de autenticação (para o modo HTTP):

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

  2. Defina as credenciais da API da 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 o servidor:

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

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

Desenvolvimento Local

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

Integração com Claude Desktop

Pré-requisitos

  1. Obtenha as Credenciais da API da Cisco:

    • Visite o Console de API da Cisco
    • Crie um aplicativo e obtenha seu Client ID e Secret
    • Garanta que o aplicativo tenha acesso à API Bug

  2. Instale o Claude Desktop:

    • Baixe em Claude.ai
    • Certifique-se de estar usando uma versão recente que suporte MCP

Configuração Passo a Passo

  1. Localize o Arquivo de Configuração do Claude Desktop:

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

  2. Crie ou Edite o Arquivo de Configuração:

    {
  "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: O sinalizador -y aceita automaticamente a instalação do pacote, o que é necessário para o Claude Desktop, pois ele é executado em segundo plano sem interação do usuário.

    Variáveis de Ambiente Opcionais:

    Configure quais APIs habilitar com SUPPORT_API:

    • "enhanced_analysis" - Somente ferramentas de análise aprimorada (recomendado para a maioria dos usuários)
    • "bug" - Somente API Bug (padrão)
    • "bug,product" - APIs Bug + Product (habilita o preenchimento automático de produtos)
    • "all" - Todas as APIs disponíveis
    • "bug,case,eox" - Múltiplas APIs específicas

    Preenchimento Automático de Produtos (opcional, requer que SUPPORT_API inclua 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 a seção Preenchimento Automático de Produtos para instruções de configuração.

  3. Substitua Suas Credenciais:

    • Substitua your_client_id_here pelo seu Client ID real da Cisco
    • Substitua your_client_secret_here pelo seu Client Secret real da Cisco

  4. Reinicie o Claude Desktop:

    • Feche o Claude Desktop completamente
    • Reabra o aplicativo
    • O servidor MCP será carregado automaticamente

Verificação

Após a configuração, você deve ser capaz de:

  1. Perguntar ao Claude sobre bugs da Cisco:

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

  2. Obter detalhes específicos de bugs:

    "Get details for Cisco bug CSCab12345"

  3. Pesquisar por produto:

    "Find bugs affecting Cisco Catalyst 3560 switches"

Exemplo de Uso no Claude Desktop

Uma vez configurado, você pode fazer perguntas ao Claude como:

  • Busca Básica de Bugs:

    • "Pesquise bugs recentes relacionados a 'crash' em produtos Cisco"
    • "Encontre bugs abertos com severidade 1 ou 2"
    • "Mostre-me bugs modificados nos últimos 30 dias"

  • Buscas Específicas por Produto:

    • "Encontre bugs para o ID de produto C9200-24P"
    • "Pesquise bugs no Cisco Catalyst 9200 Series que afetam a versão 17.5.1"
    • "Mostre bugs corrigidos na versão de software 17.5.2"

  • Detalhes de Bugs:

    • "Obtenha detalhes completos do bug CSCab12345"
    • "Mostre-me informações sobre os bugs CSCab12345,CSCcd67890"

  • Filtragem Avançada:

    • "Encontre bugs resolvidos com severidade 3 modificados após 01/01/2023"
    • "Pesquise bugs no 'Cisco ASR 9000 Series' ordenados por severidade"
    • "Você pode me mostrar todos os bugs da Cisco nos últimos 30 dias para o produto Cisco Unified Communications Manager (CallManager)?" (usa busca por palavra-chave)
    • "Encontre bugs para o Cisco Unified Communications Manager que afetam as versões 14.0 e 15.0" (usa busca por série de produto)

O Claude usará as ferramentas MCP apropriadas para buscar dados em tempo real da API Bug da Cisco e fornecer respostas abrangentes com as informações mais recentes.

Prompts MCP

O servidor inclui 10+ prompts especializados para fluxos de trabalho guiados de suporte Cisco:

  • 🔍 cisco-high-severity-search - Pesquise bugs de alta severidade por produto ou número de série
  • 🚨 cisco-incident-investigation - Investigue sintomas e erros
  • 🔄 cisco-upgrade-planning - Pesquise problemas antes de atualizações
  • 🔧 cisco-maintenance-prep - Prepare-se para janelas de manutenção
  • 🔒 cisco-security-advisory - Pesquise vulnerabilidades de segurança
  • ⚠️ cisco-known-issues - Verifique problemas de versões de software
  • 📋 cisco-case-investigation - Investigue casos de suporte
  • ⏰ cisco-lifecycle-planning - Planejamento de fim de vida
  • 🎯 cisco-smart-search - Busca inteligente com refinamento automático
  • ✨ cisco-interactive-search - Busca interativa com elicitação

Suporte a Número de Série: A maioria dos prompts agora aceita um nome de produto OU um número de série. Quando você fornece um número de série (por exemplo, "SAL09232Q0Z"), o servidor automaticamente consulta os detalhes do produto e os utiliza na busca. Isso facilita a investigação de problemas quando você tem o número de série do dispositivo, mas não sabe o modelo exato do produto.

Cada prompt fornece planos de investigação estruturados e recomendações de especialistas.

Busca Interativa com Elicitação

O prompt cisco-interactive-search demonstra o recurso de elicitação do MCP, permitindo que o servidor solicite dinamicamente informações adicionais dos usuários durante a execução das ferramentas. Isso torna as buscas mais naturais e ajuda a coletar parâmetros ausentes sem reiniciar as solicitações.

Exemplo de Uso:

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

Consulte examples/elicitation-example.md para exemplos detalhados de uso e ⚡ Prompts MCP para documentação completa dos prompts.

🔍 Recursos MCP - Preenchimento Automático de Produtos

O servidor expõe dados da Cisco como Recursos MCP para acesso direto pelo cliente. Isso inclui um novo recurso de Preenchimento Automático de Produtos que permite pesquisar o catálogo interno de produtos da Cisco usando o cookie de sessão do seu navegador.

Recursos de Produtos Disponíveis

Quando SUPPORT_API inclui product, os seguintes recursos estão disponíveis:

Modelos de Recursos (URIs dinâmicos):

  • cisco://products/{product_id} - Obtenha detalhes do produto por ID (por exemplo, C9300-24P, ISR4431)
  • cisco://products/autocomplete/{search_term} - ✨ NOVO: Pesquise o catálogo de produtos por nome ou modelo

Recursos Estáticos:

  • cisco://products/catalog - Visão geral do catálogo de produtos
  • cisco://products/autocomplete-help - ✨ NOVO: Instruções de configuração para preenchimento automático de produtos

Configuração do Preenchimento Automático de Produtos

O recurso de preenchimento automático de produtos requer o cookie de sessão do seu Cisco.com para acessar a API interna da Cisco.

Configuração Rápida:

  1. Faça login na Cisco:

  2. Extraia Seu Cookie:

    • Abra o DevTools do navegador (F12)
    • Vá para Application/Storage > Cookies
    • Selecione https://bst.cloudapps.cisco.com
    • Copie todos os valores dos cookies

  3. Defina a Variável de Ambiente:

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

  4. Consulte Produtos:

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

Ciclo de Vida do Cookie:

  • Validade Típica: 24 horas
  • Atualização Recomendada: Diariamente antes de uso intenso
  • Sinais de Expiração: Erros 401/403, mensagens de "Cookie expirado"

Para instruções detalhadas de configuração, consulte o recurso de ajuda:

cisco://products/autocomplete-help

Exemplo de Resposta

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"
  }]
}

Boas Práticas de Segurança

  • ✅ Nunca faça commit de cookies - eles são como senhas
  • ✅ Use arquivo .env - já está no .gitignore
  • ✅ Atualize regularmente - cookies expiram após ~24 horas
  • ✅ Monitore a atividade - verifique sua conta Cisco
  • ✅ Use uma conta dedicada - não seu login principal

Uso no Claude Desktop

Pergunte ao Claude:

  • "Mostre-me a ajuda para preenchimento automático de produtos"
  • "Pesquise o produto Cisco 4431 usando preenchimento automático"
  • "Qual é o nome completo do produto ISR4431?"
  • "Encontre produtos que correspondam a 'catalyst switch'"

Consulte docs/PRODUCT_AUTOCOMPLETE_SOLUTIONS.md para detalhes de implementação e docs/CISCO_COOKIE_ANALYSIS.md para informações sobre o ciclo de vida do cookie.

⚠️ API Smart Bonding Customer (EXPERIMENTAL/NÃO TESTADA)

O servidor inclui suporte experimental para a API Smart Bonding Customer da Cisco para gerenciamento de tickets e classificação de códigos de problema. Este recurso NÃO FOI TESTADO e requer credenciais especiais obtidas através do seu Gerente de Conta Cisco.

Recursos do Smart Bonding

Continuação da tradução de Markdown (2/3) para Português (BR), preservando todos os tokens e marcadores.

Ferramentas disponíveis (8 no total):

  • get_smart_bonding_tsp_codes - Recuperar detalhes de TSP (Tecnologia, Subtecnologia, Código do Problema) para classificação de ticket
  • pull_smart_bonding_tickets - Recuperar atualizações de ticket da Cisco que ainda não foram baixadas
  • create_smart_bonding_ticket - Criar um novo ticket de suporte (retorna credenciais de upload na resposta)
  • update_smart_bonding_ticket - Adicionar notas de trabalho e atualizar o status do ticket
  • upload_file_to_smart_bonding_ticket - Enviar arquivos usando as credenciais da criação do ticket (HTTP PUT para cxd.cisco.com)
  • escalate_smart_bonding_ticket - Escalar problemas críticos para a Cisco
  • resolve_smart_bonding_ticket - Marcar tickets como resolvidos com notas de resolução
  • close_smart_bonding_ticket - Fechar tickets concluídos com diagnóstico e solução

Processo de Upload de Arquivos

O Smart Bonding usa um mecanismo de upload separado da API REST:

  1. Criar ticket → A resposta inclui as credenciais de upload (Campos 80-82)
  2. Salvar credenciais → Não podem ser recuperadas depois!
  3. Enviar arquivos → Use a ferramenta upload_file_to_smart_bonding_ticket ou curl
  4. Expiração em 72 dias → O token expira 72 dias após a criação

Credenciais de upload fornecidas na resposta de criação do ticket:

  • Campo 80: Domínio de upload (ex.: cxd.cisco.com)
  • Campo 81: Token de autenticação (senha)
  • Campo 82: Timestamp de expiração do token

Arquivos não podem ser modificados após o upload — envie novos arquivos para correções.

Diferenças de Autenticação

A API do Smart Bonding usa um sistema de autenticação diferente das APIs padrão de suporte da Cisco:

RecursoAPIs de Suporte PadrãoAPI Smart Bonding
Endpoint OAuth2https://id.cisco.com/oauth2/default/v1/tokenhttps://cloudsso.cisco.com/as/token.oauth2
Validade do Token12 horas1 hora
CredenciaisAutoatendimento via Portal do Desenvolvedor CiscoContato com o Gerente de Conta Cisco
Variáveis de AmbienteCISCO_CLIENT_ID, CISCO_CLIENT_SECRETSMART_BONDING_CLIENT_ID, SMART_BONDING_CLIENT_SECRET

Configuração

  1. Obter Credenciais — Contate seu Gerente de Conta Cisco para solicitar acesso à API Smart Bonding

  2. Defina as Variáveis de Ambiente:

    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. Use as Ferramentas Smart Bonding:

    • Obtenha códigos TSP para classificação de tickets
    • Baixe novas atualizações de tickets
    • Crie/atualize tickets com categorização padronizada de problemas

Notas Importantes

  • ⚠️ EXPERIMENTAL/NÃO TESTADO — Esta implementação não foi testada com credenciais reais do Smart Bonding
  • ⚠️ Credenciais Separadas Necessárias — O Smart Bonding usa credenciais OAuth2 diferentes das APIs de suporte padrão
  • ⚠️ Não Incluído em SUPPORT_API=all — Deve ser explicitamente habilitado com SUPPORT_API=smart_bonding
  • ⚠️ Acesso Especial Requerido — Contate o Gerente de Conta Cisco para provisionamento de credenciais
  • URLs base diferem entre ambientes de homologação e produção
  • Suporta IDs de correlação para rastreabilidade de ponta a ponta de requisições

Exemplo 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 detalhes completos de implementação e arquitetura da API, veja SMART_BONDING_IMPLEMENTATION.md.

Capturas de Tela

Integração com Claude Desktop

Claude Desktop Integration

O Claude Desktop conectou-se com sucesso ao servidor MCP Cisco Support, demonstrando a funcionalidade de busca de bugs com respostas em tempo real da API de Bugs da Cisco.

MCP Inspector

MCP Inspector Integration

MCP Inspector v0.14.0+ mostrando as ferramentas disponíveis e os recursos de teste de conectividade do servidor.

Métodos Alternativos de Instalação

Instalação Global

Se você preferir instalar globalmente em vez de usar o npx:

npm install -g mcp-cisco-support

Em seguida, use esta configuração:

{
  "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"
      }
    }
  }
}

Instalação Local

Para desenvolvimento ou configurações personalizadas:

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

Em seguida, use esta configuração:

{
  "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"
      }
    }
  }
}

Solução de Problemas

Problemas Comuns

  1. Erros de "comando não encontrado":

    • Certifique-se de que o Node.js 18+ esteja instalado
    • Tente a instalação global: npm install -g mcp-cisco-support
    • Verifique o caminho no arquivo de configuração

  2. Falhas de autenticação:

    • Verifique novamente seu Client ID e Secret
    • Certifique-se de que seu aplicativo API Cisco tenha acesso à API de Bugs
    • Verifique erros de digitação no arquivo de configuração

  3. Servidor MCP não carregando:

    • Reinicie o Claude Desktop completamente
    • Valide a sintaxe do arquivo de configuração com um validador JSON
    • Verifique os logs/mensagens de erro do Claude Desktop

  4. Erros de permissão:

    • Garanta que o arquivo de configuração seja legível
    • No macOS/Linux, verifique as permissões do arquivo: chmod 644 claude_desktop_config.json

Depuração

  1. Teste o servidor manualmente:

    npx mcp-cisco-support

    Isso deve iniciar o servidor no modo stdio sem erros.

  2. Valide sua configuração: Use um validador JSON para garantir que o arquivo de configuração esteja formatado corretamente.

  3. Verifique os logs do Claude Desktop:

    • Procure mensagens de erro relacionadas a MCP no Claude Desktop
    • O aplicativo geralmente mostra o status de conexão dos servidores MCP

    Monitore logs em tempo real (macOS):

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

    No Windows:

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

Obtendo Ajuda

Implantação com 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

🔐 Segurança

  • Modo stdio: Sem autenticação (Claude Desktop, clientes locais)
  • Modo HTTP: Requer autenticação via Bearer token
# 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 o 🔒 Guia de Segurança para documentação completa de segurança.

Configuração

Variáveis de Ambiente

Crie um arquivo .env com sua configuração:

# 🔑 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

Autenticação OAuth 2.1 (Avançado)

Para autenticação de nível de produção com controle de acesso refinado, use o modo OAuth 2.1:

Início 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

Arquivos de Configuração

config/oauth-clients.json — Configuração de clientes (pode ter controle de versão):

{
  "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 — Segredos dos clientes (ignorado pelo git, nunca versionar):

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

Escopos OAuth

Controle o acesso à API com escopos refinados:

EscopoAcesso à APIDescrição
mcpTodas as APIsAcesso total a todas as ferramentas MCP
mcp:bugAPI de BugsApenas busca e detalhes de bugs
mcp:caseAPI de CasosSomente gerenciamento de casos de suporte
mcp:eoxAPI EoXSomente informações de fim de vida
mcp:psirtAPI de SegurançaSomente alertas de segurança
mcp:productAPI de ProdutosSomente informações de produtos
mcp:softwareAPI de SoftwareSomente sugestões de software
mcp:serialAPI de SeriaisSomente consultas de número de série
mcp:rmaAPI RMASomente autorização de devolução

Melhores Práticas: Conceda apenas os escopos necessários para cada aplicação (princípio do menor privilégio).

Variáveis de Ambiente

Aponte para locais personalizados de arquivos de configuração:

# 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

Ao executar no modo OAuth 2.1, o servidor fornece:

  • GET /.well-known/oauth-authorization-server — Metadados de descoberta OAuth
  • GET /authorize — Endpoint de autorização (exibe página de consentimento)
  • POST /authorize/approve — Aprovação de autorização
  • POST /token — Endpoint de token (PKCE obrigatório)
  • POST /register — Registro dinâmico de clientes (se habilitado)

Consulte docs/OAUTH_CLIENTS_CONFIG.md para documentação completa do OAuth 2.1.

Integração com Claude Desktop

Configuração 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"
      }
    }
  }
}

Configuração Docker

Opção 1: Autenticação via Bearer Token

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

Opção 2: Autenticação OAuth 2.1 (Produção)

# 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

Opção 3: Sem Autenticação (Somente Desenvolvimento)

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 com 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 da API

EndpointMétodoDescrição
/GETInformações do servidor e endpoints disponíveis
/mcpPOSTEndpoint MCP principal (JSON-RPC sobre HTTP)
/messagesPOSTEndpoint MCP alternativo para compatibilidade com N8N
/sseGETConexão SSE com gerenciamento de sessão
/ssePOSTEndpoint SSE de mensagens legado (obsoleto)
/sse/session/{sessionId}POSTEndpoint MCP de mensagens específico para sessão
/pingGETEndpoint simples de ping para teste de conectividade
/healthGETVerificação de saúde com status detalhado

📚 Documentação

Para informações detalhadas, consulte nossa abrangente Wiki no GitHub:

Exemplos de Uso

Exemplos com 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"
      }
    }
  }'

Exemplo 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;
}

Monitoramento de Saúde

O servidor fornece um endpoint abrangente de verificação de saúde:

curl http://localhost:3000/health

A resposta inclui:

  • Status do servidor
  • Status do token OAuth2
  • Uso de memória
  • Tempo de atividade
  • Conexões SSE ativas

Recursos de Segurança

  • Helmet: Cabeçalhos de segurança
  • CORS: Compartilhamento de recursos entre origens
  • Validação de Entrada: Validação baseada em esquemas
  • Execução como Não Root: Segurança em Docker
  • Variáveis de Ambiente: Armazenamento seguro de credenciais

Solução de Problemas

Problemas Comuns

  1. Falha na Autenticação OAuth2

    • Verifique CISCO_CLIENT_ID e CISCO_CLIENT_SECRET
    • Verifique a conectividade de rede com https://id.cisco.com

  2. Chamadas de API Falhando

    • Verifique a validade do token em /health
    • Verifique o acesso de rede a https://apix.cisco.com

  3. Problemas com Docker

    • Certifique-se de que as variáveis de ambiente estão definidas
    • Verifique os logs do Docker: docker-compose logs

Logs

Logs estruturados em JSON incluem:

  • Timestamp
  • Nível de log (info, error, warn)
  • Mensagem
  • Dados de contexto adicionais

Testes

Executando Testes

# 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

Estrutura de Testes

A suíte de testes inclui:

  • Testes de Autenticação (tests/auth.test.js): Autenticação OAuth2, gerenciamento de tokens, tratamento de erros
  • Testes de Ferramentas MCP (tests/mcp-tools.test.js): Todas as 8 ferramentas MCP, tratamento de erros, paginação
  • Configuração (tests/setup.js): Configuração do ambiente de testes

Correções Recentes em Testes

Os seguintes problemas foram identificados e resolvidos na suíte de testes:

✅ Problemas Corrigidos

  1. Lógica de Atualização de Token

    • Problema: O cálculo de expiração do token estava incorreto em getValidToken()
    • Solução: Corrigido a condição para verificar corretamente se o token está dentro da margem de atualização
    • Impacto: Comportamento adequado de cache e atualização de token

  2. Tratamento de Múltiplos IDs de Bug

    • Problema: Vazamento de estado entre testes causando incompatibilidades nas sequências simuladas
    • Solução: Implementada a função resetServerState() para limpeza adequada
    • Impacto: Resultados consistentes entre múltiplas execuções

  3. Implementação das Ferramentas de Busca

    • Problema: Mesmo problema de gerenciamento de estado afetando busca por palavras-chave e outras ferramentas
    • Solução: Reset adequado do estado do servidor entre testes
    • Impacto: Todas as 8 ferramentas MCP agora funcionam corretamente

  4. Tratamento de Erros

    • Problema: Erros de API e timeouts de rede não eram convertidos adequadamente em respostas de erro MCP
    • Solução: Tratamento de erros aprimorado na função handleMCPMessage()
    • Impacto: Respostas de erro adequadas para aplicações clientes

  5. Cenários de Falha de Autenticação

    • Problema: Endpoint de saúde retornando 200 em vez de 503 em falhas de autenticação
    • Solução: Limpeza de cache de módulos e isolamento adequado de estado
    • Impacto: Relatório correto do status de saúde

  6. Gerenciamento de Estado de Teste

    • Problema: Variáveis de nível de módulo persistindo entre testes
    • Solução: Adicionada exportação resetServerState() e limpeza adequada do cache de módulo
    • Impacto: Isolamento real de testes e resultados confiáveis

Configuração de Teste

  • Jest: Usando Jest com a flag --forceExit para execuções principais de teste
  • Redefinição de Estado: Cada teste recebe uma nova instância do servidor com estado limpo
  • Gerenciamento de Mocks: Mocking de fetch adequado com tratamento correto de sequência
  • Isolamento de Teste: A limpeza do cache de módulo evita vazamento de estado

Detalhes de Implementação Principais

  • Fetch nativo: Usa o fetch nativo do Node.js em vez de bibliotecas externas
  • Gerenciamento de Token: Validade de 12 horas para o token com margem de atualização de 30 minutos
  • Tratamento de Erros: Tratamento abrangente de erros com respostas de erro MCP adequadas
  • Segurança: Cabeçalhos de segurança Helmet, suporte a CORS, validação de entrada
  • Registro de Logs: Registro JSON estruturado com carimbos de data/hora

Desenvolvimento

Estrutura do Projeto

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 Desenvolvimento

# 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

Considerações de Performance

  • Cache de token reduz chamadas à API
  • Paginação limita resultados a 10 por página
  • Heartbeat SSE a cada 30 segundos mantém conexões ativas
  • Timeout de requisição definido em 30 segundos

Notas de Segurança

  • Nunca envie o arquivo .env para o controle de versão
  • Use variáveis de ambiente para todos os segredos
  • Revise os limites de uso e os termos da API da Cisco
  • Monitore os logs para atividades suspeitas

Referência da API

Autenticação

  • URL OAuth2: https://id.cisco.com/oauth2/default/v1/token
  • Tipo de Concessão: client_credentials
  • Validade do Token: 12 horas
  • Atualização Automática: 30 minutos antes da expiração

URL Base da API de Bugs

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

Protocolo MCP

O servidor implementa o Model Context Protocol com estes métodos:

  • initialize: Inicializa a conexão MCP
  • tools/list: Lista as ferramentas disponíveis
  • tools/call: Executa uma ferramenta

Exemplo de mensagem MCP:

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

Monitoramento de Saúde

O servidor fornece um endpoint abrangente de verificação de saúde:

curl http://localhost:3000/health

A resposta inclui status do servidor, status do token OAuth2, uso de memória, tempo de atividade e conexões ativas.

Testes

Framework de testes abrangente baseado em Jest com:

  • ✅ 46/46 ferramentas testadas - Todas as ferramentas MCP em 8 APIs
  • ✅ Testes com Mock e API Real - Testes unitários com mocks + testes de integração com APIs ao vivo
  • ✅ Teste individual de ferramentas - Executor de testes independente para desenvolvimento
# 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 🧪 Framework de Testes para documentação completa de testes.

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça suas alterações
  4. Adicione testes para a nova funcionalidade
  5. Garanta que todos os testes passem: npm test
  6. Envie um pull request

Suporte

Recursos

Recursos Externos