npm package: @progden/beep-mcp
Description: MCP server that plays beep sounds for Claude Code hooks
Author: progden
Latest version: 1.0.0

# Beep MCP Server

A Model Context Protocol (MCP) server that provides beep sound playback functionality for Claude Code hooks.

## Features

- 🔊 **Headphone-friendly**: Plays sounds through system audio devices (headphones/speakers)
- ⚡ **Fast preset mode**: Uses pre-generated WAV file (800Hz, 300ms) for instant playback
- 🎛️ **Customizable**: Supports custom frequency and duration parameters
- 🔌 **MCP-compatible**: Works seamlessly with Claude Code hooks
- 🖥️ **Cross-platform**: Supports Windows, macOS, and Linux

## Installation

### From npm (Recommended)

```bash
npm install -g @progden/beep-mcp
```

### From Source

```bash
git clone https://github.com/progden/beep-mcp.git
cd beep-mcp
npm install
```

The installation will automatically:
1. Compile TypeScript source files
2. Generate the default `beep.wav` file (800Hz, 300ms, 80% volume)

## Usage

### As MCP Server (Claude Code Hook)

After installing globally, add to your `.claude/settings.json`:

```json
{
  "hooks": {
    "userPromptSubmitTool": {
      "command": "beep-mcp"
    }
  }
}
```

Now Claude Code will play a beep sound when the Stop hook event is triggered.

### Standalone Test

Test the beep functionality directly:

```bash
# If installed globally
beep-mcp --test

# If installed from source
npm run test
# Or manually
node dist/index.js --test
```

## MCP Tool API

### `play_beep`

Plays a beep sound through system audio.

**Parameters:**

| Parameter   | Type   | Required | Default | Description                              |
| ----------- | ------ | -------- | ------- | ---------------------------------------- |
| `frequency` | number | No       | 800     | Frequency in Hz (20-20000)               |
| `duration`  | number | No       | 300     | Duration in milliseconds (10-5000)       |

**Behavior:**

- **No parameters**: Uses pre-generated `beep.wav` (800Hz, 300ms, 80% volume) - fastest option
- **With parameters**: Dynamically generates WAV with specified frequency/duration

**Examples:**

```javascript
// Preset beep (fastest)
await playBeep();

// Custom frequency
await playBeep(800);

// Custom frequency and duration
await playBeep(1000, 300);
```

## Project Structure

```
beep-mcp/
├── package.json              # Project configuration
├── tsconfig.json             # TypeScript configuration
├── sounds/
│   └── beep.wav             # Pre-generated beep (800Hz, 300ms, 80% volume)
├── src/
│   ├── index.ts             # MCP server main entry point
│   ├── audio.ts             # WAV generation logic
│   ├── player.ts            # Audio playback module
│   └── generate-beep.ts     # Preset beep generator script
└── dist/                    # Compiled JavaScript (auto-generated)
```

## Technical Details

### Audio Generation

- **Format**: WAV (PCM 16-bit mono)
- **Sample Rate**: 44.1 kHz (CD quality)
- **Waveform**: Sine wave with fade in/out envelope (prevents clicks)
- **Volume**: 80% of max amplitude (adjustable)

### Audio Playback

- **Library**: `node-wav-player` (background playback using PowerShell SoundPlayer on Windows)
- **Background Mode**: No visible windows, plays directly through system audio
- **Temp Files**: Custom beeps use temporary files (auto-cleanup)
- **Error Handling**: Graceful fallback with detailed error messages

### MCP Integration

- **Protocol**: Model Context Protocol (stdio transport)
- **SDK**: `@modelcontextprotocol/sdk`
- **Tool Definition**: Single `play_beep` tool with optional parameters

## Development

### Build

```bash
npm run build
```

### Watch Mode

```bash
npm run dev
```

### Regenerate Preset Beep

```bash
npm run generate-beep
```

## Troubleshooting

### No sound in headphones

1. Check system audio settings
2. Verify default playback device is set correctly
3. Test with `npm run test` to ensure audio works standalone

### "Preset beep.wav not found" error

Run the generator script:

```bash
npm run generate-beep
```

### MCP server not responding

1. Check that the path in `.claude/settings.json` is correct
2. Ensure TypeScript has been compiled (`npm run build`)
3. Test MCP server manually: `node dist/index.js`

## Dependencies

- **Runtime**:
  - `@modelcontextprotocol/sdk`: MCP protocol implementation
  - `node-wav-player`: Cross-platform background audio playback

- **Development**:
  - `typescript`: TypeScript compiler
  - `@types/node`: Node.js type definitions

## License

MIT

## Author

Created for Claude Code integration