# SSR/128T MCP Server

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.10+-green.svg)](https://www.python.org/)

A Model Context Protocol (MCP) server for the **Juniper SSR/128T Networking Platform**, enabling AI-powered AIOps management through LLM clients like **Claude Desktop** and **VSCode**.

This server provides a bridge between MCP-compatible clients and the SSR Conductor REST API, allowing natural language driven monitoring, visualization, and troubleshooting of your SSR network.

## Features

- 🔌 **22 MCP Tools** covering router management, alarms, traffic analysis, routing tables, interfaces, metrics, and audit logs
- 🔐 **Automatic Authentication** with token management and auto-refresh
- 🚀 **Dual Transport** — stdio (local) and streamable-http (remote/deployment)
- 🐳 **Docker Support** — ready for containerized deployment on any Linux platform
- ⚡ **Async HTTP** client based on `httpx` for high-performance concurrent requests
- 🛡️ **Self-Signed Certificate Support** for lab and testing environments

## Quick Start

### Prerequisites

- Python 3.10+ and pip
- Access to an SSR Conductor (v6.x+)

### Installation

```bash
git clone https://github.com/lotsonlu/ssr-mcp-server.git
cd ssr-mcp-server
pip install -r requirements.txt
```

### Configuration

Set environment variables:

```bash
export SSR_BASE_URL="https://<your-conductor-ip>"
export SSR_USERNAME="admin"
export SSR_PASSWORD="your-password"
```

Or create a `config.json` file (copy from `config-template.json`):

```json
{
    "conductor": {
        "base_url": "https://172.27.69.57",
        "username": "admin",
        "password": "your-password",
        "timeout": 120,
        "verify_ssl": false
    }
}
```

### Run with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ssr-mcp": {
      "type": "stdio",
      "command": "python3",
      "args": ["/path/to/ssr_mcp.py", "-f", "/path/to/config.json", "-t", "stdio"]
    }
  }
}
```

### Run with VSCode

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "ssr-mcp": {
      "command": "python3",
      "args": ["/path/to/ssr_mcp.py", "-f", "/path/to/config.json", "-t", "stdio"]
    }
  }
}
```

### Run Standalone (HTTP mode)

```bash
python ssr_mcp.py -H 0.0.0.0 -p 8080 -t streamable-http
```

### Docker

```bash
docker build -t ssr-mcp-server .
docker run --rm -i \
  -e SSR_BASE_URL="https://<conductor-ip>" \
  -e SSR_USERNAME="admin" \
  -e SSR_PASSWORD="your-password" \
  ssr-mcp-server -t stdio
```

## Available Tools

### Router & System (4)
| Tool | Description |
|------|-------------|
| `get_router_list` | List all routers, status, and basic info |
| `get_router_info` | Detailed info for a specific router |
| `get_nodes` | List all nodes for a router |
| `get_system_info` | Conductor system info, version, uptime |

### Alarms & Status (4)
| Tool | Description |
|------|-------------|
| `get_alarms` | All current alarms (with filters) |
| `get_router_alarms` | Router-specific alarms |
| `get_node_alarms` | Node-specific alarms |
| `get_node_status` | Node operational status & process health |

### Traffic & Routing (7)
| Tool | Description |
|------|-------------|
| `get_traffic_flows` | Active flow/session table |
| `get_traffic_fib` | Forwarding Information Base (FIB) |
| `get_traffic_rib` | Routing Information Base (RIB) |
| `get_top_sessions` | Top N sessions by bandwidth |
| `get_top_sources` | Top N traffic sources |
| `get_adjacencies` | Network adjacencies/peers |
| `fib_lookup` | FIB lookup by packet headers |

### Interfaces & Services (3)
| Tool | Description |
|------|-------------|
| `get_device_interfaces` | Physical device interfaces |
| `get_network_interfaces` | Logical/L3 network interfaces |
| `get_services` | Configured services & service classes |

### Metrics & Analytics (3)
| Tool | Description |
|------|-------------|
| `get_router_metrics` | Timeseries performance metrics |
| `get_analytics` | Aggregated analytics queries |
| `get_audit_logs` | Historical audit & configuration logs |

### Version (1)
| Tool | Description |
|------|-------------|
| `get_software_version` | SSR software version per node |

## Architecture

```
┌──────────────────────────────────────────────┐
│  Claude Desktop / VSCode / Other MCP Clients │
└──────────────────┬───────────────────────────┘
                   │ stdio / streamable-http
┌──────────────────▼───────────────────────────┐
│  SSR MCP Server (ssr_mcp_server)             │
│  ├── server.py     MCP Server & Tool Defs    │
│  ├── ssr_client.py REST API Client           │
│  ├── tools/        22 Tool Handlers          │
│  └── utils/        Config Management         │
└──────────────────┬───────────────────────────┘
                   │ REST API (HTTPS)
┌──────────────────▼───────────────────────────┐
│  SSR Conductor                               │
│  /router, /alarm, /traffic, /stats, etc.     │
└──────────────────────────────────────────────┘
```

## Project Structure

```
ssr-mcp-server/
├── ssr_mcp.py                    # CLI entry point
├── ssr_mcp_server/               # Core package
│   ├── server.py                 # MCP server & 22 tool definitions
│   ├── ssr_client.py             # REST API client (auth, HTTP, retry)
│   ├── tools/                    # Tool handler modules
│   │   ├── router_tools.py       # Router & system tools
│   │   ├── alarm_tools.py        # Alarm & status tools
│   │   ├── traffic_tools.py      # Traffic & routing tools
│   │   ├── interface_tools.py    # Interface & service tools
│   │   ├── metrics_tools.py      # Metrics & analytics tools
│   │   └── audit_tools.py        # Audit & version tools
│   └── utils/
│       └── config.py             # Configuration management
├── pyproject.toml                # Project metadata & dependencies
├── requirements.txt              # Pip dependencies
├── Dockerfile                    # Docker build
├── Makefile                      # Dev/build helpers
├── config-template.json          # Configuration template
└── LICENSE
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `SSR_BASE_URL` | `https://127.0.0.1` | SSR Conductor URL |
| `SSR_USERNAME` | `admin` | API username |
| `SSR_PASSWORD` | — | API password (required) |
| `SSR_TIMEOUT` | `120` | API timeout in seconds |
| `SSR_VERIFY_SSL` | `false` | Enable SSL verification |

## Development

```bash
# Install dependencies
pip install -r requirements.txt

# Run with stdio transport
python ssr_mcp.py -t stdio

# Run tests
python -m pytest tests/

# Build Docker image
docker build -t ssr-mcp-server .
```

## License

[Apache License 2.0](LICENSE)

## Acknowledgments

This project is inspired by and follows patterns from the official Juniper [Junos MCP Server](https://github.com/Juniper/junos-mcp-server).