# Desktop Notification MCP Server

A Model Context Protocol (MCP) server that enables AI agents to send cross-platform desktop notifications with priority levels, categories, and duration control.

## Features

- Cross-platform support (macOS, Windows, Linux)
- Priority levels for urgency control
- Category-based visual distinction
- Configurable display duration
- Optional notification sounds
- Success/error status reporting

## Installation

```bash
npm install
npm run build
```

## Usage

### With Claude Desktop

Add to your Claude Desktop configuration file:

**macOS/Linux**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "desktop-notifications": {
      "command": "node",
      "args": [
        "/absolute/path/to/desktop-notification-mcp/dist/index.js"
      ]
    }
  }
}
```

## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `title` | string | *required* | Notification title |
| `message` | string | *required* | Notification message body |
| `sound` | boolean | `false` | Enable notification sound |
| `priority` | string | `"normal"` | Priority level: `"low"`, `"normal"`, `"high"`, `"critical"` |
| `category` | string | `"task"` | Category: `"task"`, `"error"`, `"success"`, `"progress"`, `"question"`, `"reminder"` |
| `duration` | number | *auto* | Display duration in milliseconds (0 = persistent) |

### Priority Levels

- `low` - Quick updates, 5 second timeout
- `normal` - Standard notifications, 10 second timeout (default)
- `high` - Important updates, 15 second timeout
- `critical` - Critical alerts, persistent until dismissed

### Categories

- `task` - General task notifications
- `error` - Error and failure notifications
- `success` - Success and completion notifications
- `progress` - Progress updates
- `question` - Questions requiring user attention
- `reminder` - Reminders and scheduled notifications

## Examples

### Basic Notification
```typescript
{
  "title": "Task Complete",
  "message": "Your analysis has finished"
}
```

### High Priority Error
```typescript
{
  "title": "Build Failed",
  "message": "Tests failed - review errors in output",
  "priority": "high",
  "category": "error",
  "sound": true
}
```

### Critical Alert (Persistent)
```typescript
{
  "title": "User Input Required",
  "message": "Please review the following options",
  "priority": "critical",
  "category": "question",
  "sound": true
}
```

### Progress Update
```typescript
{
  "title": "Processing...",
  "message": "Step 3 of 10 complete",
  "priority": "low",
  "category": "progress",
  "duration": 3000
}
```

### Success Notification
```typescript
{
  "title": "Deployment Complete",
  "message": "Successfully deployed to production",
  "priority": "normal",
  "category": "success",
  "sound": true
}
```

## Platform Support

The server automatically detects and uses the appropriate notification system:

- **macOS 10.8+**: Notification Center
- **Windows 8+**: Toast Notifications
- **Windows < 8**: Taskbar Balloons
- **Linux**: notify-send (requires `libnotify-bin`)

### Platform-Specific Behavior

**Linux**: Priority maps to `urgency` parameter (low/normal/critical), duration controls timeout precisely

**Windows/macOS**: Priority and category shown via visual indicators, timeout behavior varies by OS version

## Linux Requirements

Install notification support:

```bash
# Ubuntu/Debian
sudo apt-get install libnotify-bin

# Fedora
sudo dnf install libnotify

# Arch
sudo pacman -S libnotify
```