# waqasdaar/cisco-catalyst-sdwan-mcp architecture

> Architecture diagram of the GitHub repository waqasdaar/cisco-catalyst-sdwan-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/waqasdaar/cisco-catalyst-sdwan-mcp
- Repository: https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp
- Video tour (about a minute): https://gitdiagram.com/waqasdaar/cisco-catalyst-sdwan-mcp/video

## Overview

This repository is an MCP server that lets AI clients query and, when explicitly enabled and confirmed, change Cisco Catalyst SD-WAN through vManage’s REST API; it does not connect to routers directly. The main flow is client request → tool dispatch and safeguards → API validation and vManage request → shaped response. The server also exposes dedicated fabric-health, routing, multicast, IPv6, CLI add-on, and configuration workflows. Source excerpts show the core service wiring and template-migration helpers; README statements support the broader tool capabilities.

Main entry points: [`src/server.ts`](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/server.ts) (MCP tool server), [`src/services/templateMigration.ts`](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/templateMigration.ts) (Template migration), [`src/services/vmanageApi.ts`](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/vmanageApi.ts) (vManage API client), [`src/services/apiCatalog.ts`](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/apiCatalog.ts) (API catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP entry"]
  node_entrypoint["Process entry<br/>[index.ts]"]
  node_server["MCP tool server<br/>[server.ts]"]
end

subgraph group_tools["SD-WAN tools"]
  node_fabric["Fabric health<br/>[server.ts]"]
  node_routing["Routing protocols<br/>[server.ts]"]
  node_multicast["Multicast tools<br/>[server.ts]"]
  node_ipv6["IPv6 tools<br/>[server.ts]"]
  node_cli["CLI add-ons<br/>[server.ts]"]
  node_uxconfig["UX configuration<br/>[server.ts]"]
  node_apiops["General API tools<br/>[apiCatalog.ts]"]
  node_migration["Template migration"]
end

subgraph group_services["Core services"]
  node_variables["Variable mapping<br/>[configVariables.ts]"]
  node_configreview["Config review<br/>[configReview.ts]"]
  node_defects["Conversion fixes<br/>[configDefects.ts]"]
  node_migrationstore[("Migration state<br/>[migrationStore.ts]")]
  node_catalog["API catalog<br/>[apiCatalog.ts]"]
  node_vmanage["vManage API client<br/>[vmanageApi.ts]"]
  node_config["Runtime config<br/>[config.ts]"]
end

subgraph group_platform["External systems"]
  node_manager[("SD-WAN Manager")]
end

node_client(("AI MCP client"))

node_client -->|"sends tool calls"| node_server
node_entrypoint -->|"starts"| node_server
node_server -->|"loads settings"| node_config
node_server -->|"creates client"| node_vmanage
node_server -->|"creates catalog"| node_catalog
node_server -->|"plans migration"| node_migration
node_migration -->|"maps values"| node_variables
node_migration -->|"masks config"| node_configreview
node_migration -->|"loads and saves"| node_migrationstore
node_catalog -->|"validates against spec"| node_vmanage
node_vmanage -->|"sends REST requests"| node_manager
node_manager -->|"returns JSON"| node_vmanage
node_server -->|"returns shaped results"| node_client
node_client -->|"requests health"| node_fabric
node_client -->|"requests routing"| node_routing
node_client -->|"requests multicast"| node_multicast
node_client -->|"requests IPv6"| node_ipv6
node_client -->|"requests CLI config"| node_cli
node_client -->|"requests configuration"| node_uxconfig
node_client -->|"requests API operation"| node_apiops

click node_entrypoint "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/index.ts"
click node_server "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/server.ts"
click node_fabric "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/server.ts"
click node_routing "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/server.ts"
click node_multicast "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/server.ts"
click node_ipv6 "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/server.ts"
click node_cli "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/server.ts"
click node_uxconfig "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/server.ts"
click node_apiops "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/apiCatalog.ts"
click node_migration "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/templateMigration.ts"
click node_variables "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/configVariables.ts"
click node_configreview "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/configReview.ts"
click node_defects "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/configDefects.ts"
click node_migrationstore "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/migrationStore.ts"
click node_catalog "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/apiCatalog.ts"
click node_vmanage "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/vmanageApi.ts"
click node_config "https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/utils/config.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entrypoint,node_server,node_client toneBlue
class node_fabric,node_routing,node_multicast,node_ipv6,node_cli,node_uxconfig,node_apiops,node_migration toneAmber
class node_variables,node_configreview,node_defects,node_migrationstore,node_catalog,node_vmanage,node_config toneMint
class node_manager toneRose
```

## Components

### MCP entry

- [Process entry](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/index.ts): `src/index.ts`
- [MCP tool server](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/server.ts): `src/server.ts`

### SD-WAN tools

- [Fabric health](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/server.ts): `src/server.ts`
- [Routing protocols](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/server.ts): `src/server.ts`
- [Multicast tools](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/server.ts): `src/server.ts`
- [IPv6 tools](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/server.ts): `src/server.ts`
- [CLI add-ons](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/server.ts): `src/server.ts`
- [UX configuration](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/server.ts): `src/server.ts`
- [General API tools](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/apiCatalog.ts): `src/services/apiCatalog.ts`
- [Template migration](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/templateMigration.ts): `src/services/templateMigration.ts`

### Core services

- [Variable mapping](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/configVariables.ts): `src/services/configVariables.ts`
- [Config review](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/configReview.ts): `src/services/configReview.ts`
- [Conversion fixes](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/configDefects.ts): `src/services/configDefects.ts`
- [Migration state](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/migrationStore.ts): `src/services/migrationStore.ts`
- [API catalog](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/apiCatalog.ts): `src/services/apiCatalog.ts`
- [vManage API client](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/services/vmanageApi.ts): `src/services/vmanageApi.ts`
- [Runtime config](https://github.com/waqasdaar/cisco-catalyst-sdwan-mcp/blob/main/src/utils/config.ts): `src/utils/config.ts`

### External systems

- **SD-WAN Manager**

### Other components

- **AI MCP client**

## Connections

- AI MCP client → MCP tool server: sends tool calls (evidence: `README.md`)
- Process entry → MCP tool server: starts (evidence: `src/index.ts`)
- MCP tool server → Runtime config: loads settings (evidence: `src/server.ts`)
- MCP tool server → vManage API client: creates client (evidence: `src/server.ts`)
- MCP tool server → API catalog: creates catalog (evidence: `src/server.ts`)
- MCP tool server → Template migration: plans migration (evidence: `src/server.ts`)
- Template migration → Variable mapping: maps values (evidence: `src/services/templateMigration.ts`)
- Template migration → Config review: masks config (evidence: `src/services/templateMigration.ts`)
- Template migration → Migration state: loads and saves (evidence: `src/services/templateMigration.ts`)
- API catalog → vManage API client: validates against spec (evidence: `README.md`)
- vManage API client → SD-WAN Manager: sends REST requests (evidence: `README.md`)
- SD-WAN Manager → vManage API client: returns JSON (evidence: `README.md`)
- MCP tool server → AI MCP client: returns shaped results (evidence: `README.md`)
- AI MCP client → Fabric health: requests health (evidence: `README.md`)
- AI MCP client → Routing protocols: requests routing (evidence: `README.md`)
- AI MCP client → Multicast tools: requests multicast (evidence: `README.md`)
- AI MCP client → IPv6 tools: requests IPv6 (evidence: `README.md`)
- AI MCP client → CLI add-ons: requests CLI config (evidence: `README.md`)
- AI MCP client → UX configuration: requests configuration (evidence: `README.md`)
- AI MCP client → General API tools: requests API operation (evidence: `README.md`)