# MCP Servers

[![CI](https://github.com/drewrad8/mcps/actions/workflows/ci.yml/badge.svg)](https://github.com/drewrad8/mcps/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/drewrad8/mcps/graph/badge.svg)](https://codecov.io/gh/drewrad8/mcps)

A collection of Model Context Protocol (MCP) servers for network security and monitoring.

## Servers

### Firewalla MCP Server

A comprehensive MCP server for interacting with [Firewalla](https://firewalla.com) network security devices. Provides network monitoring, device management, and security rule configuration through MCP tools.

#### Features

- **Network Monitoring**: Query network flows, analyze traffic patterns, detect security events
- **Device Management**: List, search, and get details for all network devices
- **Security Rules**: Allow/block/deny categories, apps, or specific targets per device
- **Traffic Analysis**: Top talkers, blocked traffic, protocol distribution, country stats
- **Trend Data**: 24h/7d/30d traffic trends with peak detection

#### Installation

```bash
cd firewalla
npm install
npm run build
```

#### Configuration

**Option 1: Environment Variables (Recommended)**
```bash
export FIREWALLA_URL="https://my.firewalla.com"
export FIREWALLA_TOKEN="your-bearer-token"
export FIREWALLA_ID="your-firewalla-device-id"
export LOG_LEVEL="info"  # debug, info, warn, error
```

**Option 2: Runtime Configuration**
Use the `configure_firewalla` MCP tool after connecting.

#### Usage

```bash
# Start the server
npm run start

# Development mode (build + run)
npm run dev
```

#### Available MCP Tools

| Tool | Description |
|------|-------------|
| `configure_firewalla` | Set API credentials (or use env vars) |
| `get_config_status` | Check configuration status and source |
| `query_network_flows` | Query network flows with time filters |
| `list_devices` | List all network devices |
| `get_device_details` | Get device info by MAC address |
| `analyze_network_traffic` | Traffic analysis (summary, top talkers, blocked, security) |
| `get_device_traffic` | Per-device traffic analysis |
| `get_network_overview` | Comprehensive network overview |
| `get_cloud_rules` | Active cloud security rules |
| `get_traffic_trends` | Traffic trends (24h/7d/30d) |
| `get_firewalla_status` | Firewalla device status |
| `search_devices` | Search devices by name/IP/MAC |
| `update_device_rules` | Modify device security rules |

## Development

### Commands

```bash
npm run build          # Compile TypeScript
npm run start          # Run the server
npm run dev            # Build and run
npm test               # Run tests
npm run test:watch     # Run tests in watch mode
npm run test:coverage  # Run tests with coverage
```

### Testing

The project uses [Vitest](https://vitest.dev/) for testing with 32 tests covering:
- API client functionality
- Error recovery and retry logic
- Environment variable configuration
- Structured logging
- Custom error classes

### Architecture

```
firewalla/
├── server.ts          # Main server implementation
├── server.test.ts     # Test suite
├── vitest.config.ts   # Test configuration
├── package.json       # Dependencies
└── api_samples/       # Reference API responses
```

### Key Components

- **Logger**: Structured JSON logging to stderr with configurable levels
- **FirewallaAPI**: HTTP client with retry logic and exponential backoff
- **FirewallaMCPServer**: MCP server with 13 tools for Firewalla interaction
- **Error Classes**: `FirewallaAPIError`, `FirewallaAuthError`, `FirewallaNetworkError`, `FirewallaRateLimitError`

### Error Recovery

The API client includes robust error handling:
- Automatic retry on 5xx errors and network failures
- Exponential backoff with jitter
- Rate limit handling with Retry-After support
- Request timeouts (30s default)
- Configurable retry settings

### Logging

Structured JSON logs to stderr (stdout reserved for MCP):

```json
{"service":"firewalla-mcp","timestamp":"...","level":"info","message":"Server started","context":{"transport":"stdio"}}
```

## License

MIT