Topolograph MCP

Um servidor MCP que permite que LLMs interajam com os protocolos OSPF e IS-IS e analisem topologias de rede, consultem eventos de rede e realizem cálculos de caminho para os protocolos OSPF e IS-IS.

GitHub
6
Experimente este MCPPatrocinado

Documentação

Servidor Topolograph MCP

Um servidor Model Context Protocol (MCP) que fornece acesso à API Topolograph para análise de redes OSPF/IS-IS.

Visão Geral

Este servidor MCP permite que agentes de IA interajam com a API Topolograph para analisar topologias de rede, monitorar eventos e realizar cálculos de caminho para protocolos OSPF e IS-IS. O MCP (Model Context Protocol) é essencial para conectar Modelos de Linguagem de Grande Porte (LLMs) à infraestrutura de rede, permitindo que agentes de IA consultem e analisem dados de rede em tempo real.

Este servidor MCP está incluído no repositório topolograph-docker e está disponível através do arquivo docker-compose.yml fornecido.

Recursos

  • Gerenciamento de Grafos: Recuperar e enviar grafos de rede
  • Análise de Rede: Consultar informações de rede por IP, ID de nó ou máscara de rede
  • Monitoramento de Eventos: Acompanhar eventos de rede e adjacência com filtragem por tempo
  • Cálculo de Caminho: Calcular caminhos mais curtos entre nós com suporte a caminhos de backup
  • Monitoramento de Status: Verificar conectividade e status de saúde do grafo
  • Consultas de Nó/Aresta: Recuperar informações detalhadas de nós e arestas dos diagramas

Instalação

pip install -r requirements.txt

Configuração

Defina a variável de ambiente necessária:

export TOPOLOGRAPH_API_BASE="https://your-topolograph-api-url"

Autenticação opcional:

export TOPOLOGRAPH_API_TOKEN="your-api-token"

Modo somente leitura opcional (padrão é true, recomendado para implantações voltadas a agentes):

export TOPOLOGRAPH_MCP_READ_ONLY="true"

Quando habilitado, as ferramentas de mutação (upload_graph, add_lsp, update_lsp, delete_lsp) são removidas da superfície de ferramentas anunciada (tools/list) e não podem ser chamadas, mesmo por um cliente que já conheça seus nomes. Defina como false apenas para implantações confiáveis/de administração que precisam de acesso de escrita.

Uso

Inicie o servidor MCP:

python mcp-server.py

O servidor roda em http://0.0.0.0:8000/mcp por padrão.

Integração com Docker Compose

Este servidor MCP está incluído no repositório topolograph-docker. Para usá-lo como parte da stack completa do Topolograph:

git clone https://github.com/Vadims06/topolograph-docker.git
cd topolograph-docker
docker-compose pull
docker-compose up -d

O servidor MCP estará disponível em http://localhost:8000/mcp e se conecta automaticamente à API Flask.

Ferramentas Disponíveis

Ferramentas de leitura (sempre disponíveis)

  • get_all_graphs: Listar grafos disponíveis com opções de filtragem
  • get_graph_by_time: Buscar grafo específico por tempo
  • get_network_by_graph_time: Consultar informações de rede
  • get_graph_status: Verificar saúde e conectividade do grafo
  • get_network_events: Recuperar eventos de rede up/down
  • get_adjacency_events: Obter eventos de nós/hosts e links
  • get_events_timeline: Eventos de nós/hosts agrupados em ondas de tempo para narração de incidentes
  • get_nodes: Consultar nós do diagrama (filtrar por flags de função: ABR/ASBR, overload/attached IS-IS); protocol="bgp" com vni, vrf ou rt lista as folhas (VTEPs) que carregam esse VNI, VRF ou route target
  • get_edges: Consultar arestas do diagrama (include=["lsp_left_bw", "lsps", "is_te_link", "edge_key"] para campos MPLS TE; is_te_link=true|false mantém apenas links TE ou apenas o restante)
  • get_lsps: Listar/inspecionar túneis LSP MPLS TE (filtros: status, via_node, via_edge, via_edge_key)
  • get_shortest_path: Calcular o caminho mais curto entre dois nós (with_lsps=true para considerar túneis MPLS-TE com autoroute habilitado); dst_node pode ser uma lista de destinos, como cada VTEP de um VNI, respondido a partir de um único SPF
  • get_cspf_path: Verificação de viabilidade de caminho mais curto com restrições (CSPF) entre dois nós; nunca modifica o grafo; level opcional (1 ou 2) restringe um caminho IS-IS a um nível
  • get_edge_failure_reaction: Prever o impacto em toda a rede se um ou mais links caírem; apenas simulação

Ferramentas de topologia BGP (requerem Topolograph >= 2.69)

  • list_bgp_graphs / get_bgp_graph: Listar/buscar épocas do grafo BGP
  • list_bgp_nodes / list_bgp_sessions: Speakers BGP e sessões de peering de uma época
  • search_bgp_routes: Pesquisar a tabela de rotas BGP, em todo o grafo ou limitada à visão RIB resolvida de um speaker
  • get_bgp_node_route_summary: Totais de rotas por speaker (histograma de tags RIB, contagem Adj-RIB-Out)
  • get_bgp_route_state: Estado de rota BGP em um ponto no tempo
  • compare_bgp_routes: Diff de rotas BGP entre dois instantes
  • get_bgp_events_timeline: Eventos de monitoramento de sessão/rota BGP
  • list_bgp_bindings / get_bgp_binding: Correlação de grafo BGP-para-IGP
  • resolve_route: Resolver um caminho até um destino, incluindo handoffs VPN/MPLS
  • get_vrf_inventory: Inventário de VRFs

Ferramentas BGP VPN e EVPN no grafo IGP (requerem Topolograph >= 2.73)

Consultadas com o graph_time OSPF/IS-IS; a época BGP mais recente de cada fonte vinculada a esse grafo responde.

  • list_vpns: VNIs e VRFs da fabric, ou as VPNs que um roteador (router_id) vê
  • get_routes: Onde um MAC ou IP está (leaf, VNI, VRF, ESI), o que um VRF ou VNI contém, e rotas atrás de um VTEP. Filtros: mac, prefix, vni, vrf, rt, rd, vtep, at; router_id limita a visão RIB de um roteador
  • get_route_events: Histórico de rotas; a chegada de um MAC em um novo VTEP carrega moved_from_vtep

Os tipos de rota EVPN 1 a 5 são cobertos (RFC 7432, RFC 9136); os campos são descritos no guia BMP Watcher.

Ferramentas de mutação (ocultas e desabilitadas quando TOPOLOGRAPH_MCP_READ_ONLY=true)

  • upload_graph: Enviar novos grafos para a API
  • add_lsp / update_lsp / delete_lsp: Criar, atualizar e excluir túneis LSP MPLS TE (delete_lsp também é marcado como destrutivo)

As ferramentas são marcadas com read, write e/ou destructive no código-fonte, e carregam anotações MCP padrão (readOnlyHint, destructiveHint, idempotentHint) para clientes que as utilizam para seleção de ferramentas. Anotações são metadados para clientes, não uma fronteira de segurança: a fronteira real é TOPOLOGRAPH_MCP_READ_ONLY ocultando ferramentas de mutação de tools/list, respaldada por uma proteção no lado do servidor que também rejeita chamadas diretas a elas em modo somente leitura.

Padrões de onda (get_events_timeline)

get_events_timeline agrupa eventos de nós/hosts up/down em ondas cronológicas, cada uma rotulada com um pattern (outage / flap / up). Para a referência completa de campos e o mapeamento pattern ↔ status do grafo, consulte a documentação:

➡️ Linha do Tempo de Eventos (Ondas)

Licença

Consulte o arquivo LICENSE para detalhes.