# NetPulse 🌐

![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
![License: MIT](https://img.shields.io/badge/license-MIT-green)
![Tests](https://img.shields.io/badge/tests-passing-brightgreen)
![MCP](https://img.shields.io/badge/MCP-compatible-purple)

**An MCP server that exposes live network monitoring data as Resources and diagnostic capabilities as Tools, letting AI assistants query network health conversationally.**

NetPulse bridges the gap between traditional network monitoring and AI-powered operations. It implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) to give AI assistants like Claude real-time access to network telemetry — device status, interface metrics, latency measurements, bandwidth utilization, and active alerts — all through a clean, structured API.

---

## Architecture

```mermaid
graph TB
    subgraph "AI Layer"
        Claude["Claude Desktop / MCP Client"]
    end

    subgraph "NetPulse MCP Server"
        Server["server.py<br/>FastMCP"]
        Resources["Resources<br/>6 data endpoints"]
        Tools["Tools<br/>6 diagnostic actions"]
        Prompts["Prompts<br/>3 workflow templates"]
        Sim["Network Simulator<br/>7 virtual devices"]
        Metrics["Prometheus Exporter<br/>/metrics"]
    end

    subgraph "Observability Stack"
        Prom["Prometheus"]
        Graf["Grafana"]
    end

    Claude <-->|MCP Protocol| Server
    Server --> Resources
    Server --> Tools
    Server --> Prompts
    Resources --> Sim
    Tools --> Sim
    Sim --> Metrics
    Metrics --> Prom
    Prom --> Graf

    style Claude fill:#6B48FF,color:#fff
    style Server fill:#0EA5E9,color:#fff
    style Sim fill:#10B981,color:#fff
    style Graf fill:#F59E0B,color:#fff
```

### Data Flow

1. **Network Simulator** generates realistic, time-varying metrics for 7 virtual devices
2. **MCP Resources** expose read-only telemetry data (device status, interfaces, latency, bandwidth, topology, alerts)
3. **MCP Tools** provide executable diagnostics (ping, traceroute, interface check, config viewer, baseline comparison, interface restart)
4. **MCP Prompts** offer guided workflows (health briefing, troubleshooting, capacity planning)
5. **Prometheus + Grafana** provide visual dashboards alongside the AI interface

---

## Quick Start

### 1. Clone the repository

```bash
git clone https://github.com/yourusername/netpulse.git
cd netpulse
```

### 2. Launch the full stack

```bash
docker compose up -d
```

This starts:
- **NetPulse MCP Server** on port `8080` (SSE transport)
- **Prometheus** on port `9091`
- **Grafana** on port `3000` (login: `admin` / `netpulse`)

### 3. Connect Claude Desktop

Add to your Claude Desktop MCP configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "netpulse": {
      "command": "python",
      "args": ["-m", "netpulse.server"],
      "cwd": "/path/to/netpulse"
    }
  }
}
```

Or for SSE transport:
```json
{
  "mcpServers": {
    "netpulse": {
      "url": "http://localhost:8080/sse"
    }
  }
}
```

Now ask Claude: *"Give me a network health summary"* — and watch it query real telemetry!

---

## MCP Interface Reference

### Resources (Read-Only Data)

| URI | Description |
|-----|-------------|
| `netpulse://devices/status` | Status of all 7 monitored devices with CPU, memory, temperature |
| `netpulse://interfaces/{device}` | Interface metrics for a specific device |
| `netpulse://latency/report` | Latency matrix between all connected endpoints |
| `netpulse://bandwidth/top-talkers` | Top 10 bandwidth consumers |
| `netpulse://topology/map` | Network topology as nodes + edges with health status |
| `netpulse://alerts/active` | Currently firing alerts with severity |

### Tools (Executable Actions)

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `ping_device` | Ping a device and get RTT stats | `target`, `count` |
| `run_traceroute` | Trace network path to destination | `target`, `max_hops` |
| `check_interface` | Detailed interface diagnostics | `device`, `interface` |
| `get_device_config` | View device running configuration | `device`, `section` |
| `compare_baseline` | Compare current vs historical baseline | `device`, `metric`, `window` |
| `restart_interface` | Bounce an interface (requires confirmation) | `device`, `interface`, `confirm` |

### Prompts (Workflow Templates)

| Prompt | Description | Arguments |
|--------|-------------|-----------|
| `network_health_summary` | NOC morning briefing workflow | None |
| `troubleshoot_connectivity` | Guided connectivity diagnosis | `source`, `destination` |
| `capacity_planning` | Bandwidth analysis and projections | None |

---

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `NETPULSE_HOST` | `0.0.0.0` | Server bind address |
| `NETPULSE_PORT` | `8080` | MCP server port |
| `NETPULSE_TRANSPORT` | `stdio` | Transport mode (`stdio` or `sse`) |
| `NETPULSE_LOG_LEVEL` | `INFO` | Logging level |
| `NETPULSE_POLL_INTERVAL` | `30` | Metric polling interval (seconds) |

### Device Inventory

Edit `src/netpulse/config/devices.yaml` to customize the simulated network topology. The default includes 7 devices across 2 data centers and a branch office.

### Thresholds

Edit `src/netpulse/config/thresholds.yaml` to adjust alerting thresholds for CPU, memory, latency, packet loss, bandwidth, and temperature.

---

## Fault Injection (Demo)

Inject faults to demonstrate AI-driven incident detection:

```bash
# Take down the WAN link
python -m netpulse.simulators.fault_injector --scenario link_down

# Spike CPU on the core router
python -m netpulse.simulators.fault_injector --scenario cpu_spike

# Simulate interface flapping
python -m netpulse.simulators.fault_injector --scenario interface_flap

# Take down a device
python -m netpulse.simulators.fault_injector --scenario device_down

# Saturate bandwidth
python -m netpulse.simulators.fault_injector --scenario bandwidth_saturation
```

Then ask Claude: *"Are there any network issues right now?"*

---

## Development

### Local Setup

```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install with dev dependencies
pip install -e ".[dev]"

# Run the server locally (stdio mode)
python -m netpulse.server
```

### Running Tests

```bash
pytest --cov=netpulse --cov-report=term-missing
```

### Code Quality

```bash
# Linting
ruff check src/ tests/

# Type checking
mypy src/netpulse/
```

---

## Simulated Network Topology

```
          ┌─────────────┐          ┌─────────────┐
          │ core-rtr-01  │◄────────►│ core-rtr-02  │
          │  10.0.0.1    │ 10Gbps  │  10.0.0.2    │
          │  Data Ctr A  │backbone │  Data Ctr B  │
          └──┬──────┬────┘          └──────┬───────┘
             │      │                      │
        10G  │      │ 100M            10G  │
             │      │                      │
     ┌───────┴──┐   │              ┌───────┴──┐
     │dist-sw-01│   │              │dist-sw-02│
     │ 10.0.1.1 │   │              │ 10.0.1.2 │
     └─────┬────┘   │              └──────────┘
           │        │
      1G   │        │
           │        │
     ┌─────┴────┐   │         ┌───────────┐
     │edge-fw-01│   └────────►│ wan-rtr-01 │
     │ 10.0.2.1 │     WAN    │  10.0.4.1  │
     └──────────┘             └──────┬─────┘
                                     │ 1G
                              ┌──────┴──────┐
                              │access-sw-01 │
                              │  10.0.3.1   │
                              │ Branch Off 1│
                              └─────────────┘
```

---

## Author

**Hind Boukhairat** — IoT dev specializing in network monitoring and AIOps, transitioning into AI Integration Engineering. Holder of two MCP certifications from Anthropic/Skilljar (Introduction + Advanced Topics).

NetPulse is part of a portfolio showcasing the intersection of telecom/network operations and AI orchestration.

---

## License

MIT — see [LICENSE](LICENSE) for details.