# bell-mcp

A local [MCP](https://modelcontextprotocol.io) server that **rings a bell through your speakers** — so you get an audible nudge when your AI assistant finishes a task or needs your attention.

Four built-in sounds, synthesized from scratch with the Python standard library (no audio assets to download):

| id          | name          | sound                                   |
|-------------|---------------|-----------------------------------------|
| `beep`      | Retro Beep    | harsh 90s PC-speaker square-wave beep   |
| `ding`      | Ding          | single soft struck-bell tone            |
| `ding-ding` | Double Ding   | two struck-bell tones in a row          |
| `warning`   | Warning Alarm | urgent alternating two-tone alarm       |

You can **preset a default** sound and/or **pick a sound per call**.

## Requirements

- Python ≥ 3.11 and [`uv`](https://docs.astral.sh/uv/)
- An audio player on PATH:
  - **macOS**: `afplay` (built in)
  - **Linux**: `paplay`, `aplay`, or `ffplay`
  - **Windows**: PowerShell (built in)

## Tools

- **`ring_bell(sound?, message?)`** — ring a bell. `sound` is one of `beep` / `ding` / `ding-ding` / `warning`; if omitted, the preset default is used. `message` is an optional note (e.g. `"build finished"`) echoed back in the confirmation.
- **`list_bells()`** — list available sounds (id, name, description) and show the current default.

## Configuration

The default bell (used when `ring_bell` is called without `sound`) is set via the
`BELL_DEFAULT_SOUND` environment variable. Valid values: `beep`, `ding`, `ding-ding`,
`warning`. If unset or invalid, it falls back to `ding`.

## Install

Clone the repository, then register the server with your MCP client.

```bash
git clone git@github.com:taylor224/bell-mcp.git
cd bell-mcp
uv sync
```

### Claude Code

Run this from the cloned project directory:

```bash
claude mcp add bell -e BELL_DEFAULT_SOUND=ding -- uv run --directory "$(pwd)" bell-mcp
```

Add `--scope user` to make it available in every project (instead of just the current one).

Verify it connected:

```bash
claude mcp list
```

### Other MCP clients (Claude Desktop, etc.)

Add an entry to your client's MCP config. Replace `/absolute/path/to/bell-mcp`
with the path where you cloned this repo:

```json
{
  "mcpServers": {
    "bell": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/bell-mcp", "bell-mcp"],
      "env": { "BELL_DEFAULT_SOUND": "ding" }
    }
  }
}
```

Once registered, ask your assistant to ring the bell — e.g. *"ring `ding-ding` whenever you finish a task"* or *"ring the `warning` alarm if you need my input."*

## Development

```bash
uv sync                          # install dependencies
uv run bell-mcp                  # run the server over stdio
uv run python -m bell_mcp.sounds # (re)generate the WAV files
```

The WAV files live in `bell_mcp/assets/` and are generated automatically on first run.
To tweak the timbres, edit the frequency / decay / partial values in
`bell_mcp/sounds.py` and regenerate.

## Project layout

```
bell_mcp/
  server.py     # FastMCP server + tools, cross-platform playback
  sounds.py     # WAV synthesis (stdlib only); auto-generated on first run
  assets/       # generated *.wav files
pyproject.toml  # bell-mcp entry point
```

## License

MIT