# Network Device Assistant — MCP Server for Claude Code

A local MCP server that gives Claude Code direct access to network devices via
serial console and SSH, with a built-in safety layer and persistent knowledge base.

## What it does

- Connect to devices over serial (COM ports) or SSH
- Send CLI commands with automatic safety classification
- Build a growing knowledge base from every session (device profiles, known issues, command library)
- Search scripts, manuals, and customer configs from a shared folder

## Safety model

| Risk level | Example commands | Behaviour |
|------------|-----------------|-----------|
| Safe | show, ping, display, traceroute | Executes immediately |
| Dangerous | configure, reload, write, delete | Requires `confirmed=true` |
| Blocked | format flash, erase startup-config, factory-default | Always blocked |

## Quick start

**1. Install dependencies**
```
pip install -r requirements.txt
```

**2. Configure paths**
```
cp mcp-server/config.example.yaml mcp-server/config.yaml
```
Edit `config.yaml` and set `onedrive_root` to your shared folder path.

**3. Register with Claude Code**
```
cp mcp_config.example.json mcp_config.json
```
Edit `mcp_config.json` with the full path to `mcp-server/server.py`, then:
```
claude mcp add network-assistant --config mcp_config.json
```

**4. Create your context folder**
```
cp -r context.example context
```
Fill in `context/device_profiles.md` with your devices.

## Project structure

```
SSH Plugin/
  mcp-server/
    server.py              MCP entry point
    safety.py              Command risk classifier
    config.example.yaml    Config template (copy to config.yaml)
  local-api/
    session_manager.py     Session tracking
    serial_service.py      pyserial serial console
    ssh_service.py         paramiko SSH
    file_service.py        Context file search and read/write
  context.example/         Safe template context files
  context/                 Your knowledge base (gitignored)
  sessions/                Session logs (gitignored)
  requirements.txt
```

## Knowledge base

Operational knowledge lives in `context/` as plain markdown files:

| File | Contents |
|------|----------|
| `device_profiles.md` | Per-device connection details, baud rates, interface maps |
| `known_issues.md` | Documented symptoms and resolutions |
| `command_library.md` | CLI command reference by device family |
| `troubleshooting_history.md` | Log of past sessions |

Claude writes to these automatically during sessions — baud rates, working commands,
resolved issues — so every session is smarter than the last.

## Device notes

### RAD ETX
- Use `info` for running config (not `show running-config` — that is Cisco syntax)
- To check router interfaces: `configure router 1` → `info` → `exit`
- ETX devices often use non-standard baud rates — confirm before connecting

## Requirements

- Python 3.11+
- Claude Code with MCP support
- Windows (serial port access via pyserial)