Cisco NSO MCP Server

Cisco NSO MCP Server

Uma implementação de servidor Model Context Protocol (MCP) para Cisco NSO (Network Services Orchestrator) que expõe dados e operações do NSO como primitivas MCP (Ferramentas, Recursos, etc.) que podem ser consumidas por um cliente compatível com MCP, permitindo automação de rede com IA por meio de interações em linguagem natural.

Exemplo de Cliente Personalizado

O que é MCP?

Model Context Protocol (MCP) é um protocolo aberto que padroniza como modelos de IA interagem com ferramentas e serviços externos. O MCP permite:

• Definição de Ferramentas: Forma estruturada de definir ferramentas que modelos de IA podem usar
• Descoberta de Ferramentas: Mecanismo para modelos descobrirem ferramentas disponíveis
• Execução de Ferramentas: Método padronizado para modelos chamarem ferramentas e receberem resultados
• Gerenciamento de Contexto: Passagem eficiente de contexto entre ferramentas e modelos
• Agnóstico de Framework: Funciona em vários frameworks de IA, incluindo OpenAI, Anthropic, Google Gemini e outros
• Interoperabilidade: Fornece uma linguagem comum para sistemas de IA se comunicarem com ferramentas externas

Recursos

• Transporte Stdio: Por padrão, este servidor MCP usa transporte stdio para comunicação vinculada a processos
• Design Focado em Ferramentas: Operações de rede são definidas como ferramentas discretas com interfaces claras
• Processamento Assíncrono: Todas as operações de rede são implementadas de forma assíncrona para melhor desempenho
• Respostas Estruturadas: Formato de resposta consistente com seções de status, dados e metadados
• Recursos de Ambiente: Fornece informações contextuais sobre o ambiente NSO
• Integração NSO: Usa a biblioteca cisco-nso-restconf para uma interface limpa e Pythonic com a API RESTCONF do NSO
• Registro Flexível: Registro configurável para stdout e/ou arquivo por meio de variáveis de ambiente. Quando a variável de ambiente LOG_FILE é definida, os registros são enviados tanto para stdout quanto para o arquivo especificado. Se o arquivo de registro não puder ser criado ou gravado, o servidor volta para registro somente em stdout com uma mensagem de erro
• Suporte a Múltiplos Clientes: Funciona com qualquer cliente compatível com MCP, incluindo Windsurf Cascade e aplicações Python personalizadas

Ferramentas e Recursos Disponíveis

Ferramentas

Nome da Ferramenta	Descrição	Entradas	Retornos
get_device_ned_ids	Recupera IDs de Network Element Driver (NED) do Cisco NSO		Um dicionário com uma lista de IDs de NED
get_device_groups	Recupera grupos de dispositivos do Cisco NSO		Um dicionário com uma lista de grupos de dispositivos
get_device_platform	Obtém informações de plataforma para um dispositivo específico no Cisco NSO	'device_name' (string)	Um dicionário com informações de plataforma para o dispositivo especificado
get_device_config	Obtém a configuração completa para um dispositivo específico no Cisco NSO	'device_name' (string)	Um dicionário com a configuração para o dispositivo especificado
get_device_state	Obtém o estado de um dispositivo específico no Cisco NSO	'device_name' (string)	Um dicionário com o estado do dispositivo especificado
check_device_sync	Verifica o status de sincronização de um dispositivo específico no Cisco NSO	'device_name' (string)	Um dicionário com o status de sincronização do dispositivo especificado
sync_from_device	Sincroniza a partir de um dispositivo específico no Cisco NSO	'device_name' (string)	Um dicionário com o status de sincronização do dispositivo especificado
get_service_types	Obtém tipos de serviço no Cisco NSO		Um dicionário com tipos de serviço
get_services	Obtém serviços para um tipo de serviço específico no Cisco NSO	'service_type' (string)	Um dicionário com serviços para o tipo de serviço especificado

Recursos

• https://resources.cisco-nso-mcp.io/environment: Fornece um resumo selecionado do ambiente NSO:
  • Contagem de dispositivos, Distribuição do sistema operacional, Contagem de sistemas operacionais únicos, Contagem de modelos únicos, Distribuição de modelos, Distribuição de séries de dispositivos, Grupos de dispositivos e membros

Requisitos

• Python 3.12+
• Cisco NSO com API RESTCONF habilitada
• Conectividade de rede com a API RESTCONF do NSO

Opções de Configuração

Você pode configurar o servidor usando argumentos de linha de comando ou variáveis de ambiente:

Parâmetros de Conexão NSO

Argumento de Linha de Comando	Variável de Ambiente	Padrão	Descrição
--nso-scheme	NSO_SCHEME	http	Esquema de conexão NSO (http/https)
--nso-address	NSO_ADDRESS	localhost	Endereço do servidor NSO
--nso-port	NSO_PORT	8080	Porta do servidor NSO
--nso-timeout	NSO_TIMEOUT	10	Tempo limite de conexão em segundos
--nso-username	NSO_USERNAME	admin	Nome de usuário NSO
--nso-password	NSO_PASSWORD	admin	Senha NSO
--nso-verify	NSO_VERIFY	True	Verificar certificado HTTPS do NSO (padrão: True). Use --no-nso-verify para certificados autoassinados (somente desenvolvimento).
--nso-ca-bundle	NSO_CA_BUNDLE	None	Caminho para um arquivo de pacote de CA para confiar no HTTPS do NSO. Aplicável quando -nso-verify é True.

Parâmetros do Servidor MCP

Argumento de Linha de Comando	Variável de Ambiente	Padrão	Descrição
--transport	MCP_TRANSPORT	stdio	Tipo de transporte MCP (stdio/http)

Opções de Transporte HTTP (usadas apenas quando --transport=http)

FastMCP HTTP Server reference: https://gofastmcp.com/deployment/http#http-deployment

Command-line Argument	Environment Variable	Default	Description
--host	MCP_HOST	0.0.0.0	Host to bind to when using HTTP transport
--port	MCP_PORT	8000	Port to bind to when using HTTP transport

Logging Configuration

Environment Variable	Default	Description
LOG_FILE	None	Path to log file. If not set, logs will be sent to stdout only

Environment variables take precedence over default values but are overridden by command-line arguments.

Connecting to the Server with MCP Clients

You can connect to the server using any MCP client that supports the selected transport type. A few options are:

Windsurf Cascade

Windsurf Cascade supports MCP servers through a configuration file. To use the Cisco NSO MCP server with Windsurf, add it to your mcp_config.json file.

Using uv (recommended)

When using uv, no specific installation is needed. You can use uvx to directly run the package:

{
  "mcpServers": {
    "nso": {
      "command": "uvx",
      "args": [
        "cisco-nso-mcp-server",
        "--nso-address=127.0.0.1",
        "--nso-port=8080",
        "--nso-username=admin",
        "--nso-password=admin"
      ],
      "env": {
        "LOG_FILE": "/path/to/your/logs/nso-mcp.log"
      }
    }
  }
}

Usando com instalação via pip

Alternativamente, você pode instalar cisco-nso-mcp-server via pip:

pip install cisco-nso-mcp-server

Agora você pode usar o caminho direto para o executável:

{
  "mcpServers": {
    "nso": {
      "command": "/path/to/your/env/bin/cisco-nso-mcp-server",
      "args": [
        "--nso-address=127.0.0.1",
        "--nso-port=8080",
        "--nso-username=admin",
        "--nso-password=admin"
      ],
      "env": {
        "LOG_FILE": "/path/to/your/logs/nso-mcp.log"
      }
    }
  }
}

Substitua /path/to/your/env/bin/cisco-nso-mcp-server pelo caminho real onde você instalou o pacote com pip. Você pode encontrar isso executando which cisco-nso-mcp-server se o instalou em seu ambiente principal, ou localizando-o no diretório bin do seu ambiente virtual.

Em ambos os casos, a seção env é opcional. Se você a incluir, pode especificar a variável de ambiente LOG_FILE para habilitar o registro em arquivo.

Usando em uma aplicação Python de cliente MCP personalizada com transporte stdio

Uma aplicação Python de exemplo é fornecida em sample_stdio_client.py que demonstra como conectar-se ao servidor MCP localmente e executar uma ferramenta.

Executando o Servidor como Autônomo

Embora o servidor seja normalmente usado com um cliente MCP, você também pode executá-lo diretamente como um processo autônomo:

# Run with default NSO connection and MCP settings (see Configuration Options above for details)
cisco-nso-mcp-server

# Run with custom NSO connection parameters
cisco-nso-mcp-server --nso-scheme=http --nso-address=127.0.0.1 --nso-port=8080 --nso-username=admin --nso-password=admin

Ao executar como um processo autônomo com transporte stdio, você precisará canalizar entrada/saída para o processo ou usá-lo com um cliente MCP que suporte transporte stdio.

Licença

Este projeto é licenciado sob a Licença MIT. Isso significa que você pode usar, modificar e distribuir o código, sujeito aos termos e condições da Licença MIT.