Metadata-Version: 2.4
Name: nightbot-mcp
Version: 0.1.2
Summary: MCP server for Nightbot: chat commands, timers, regulars, and spam-protection filters (including the banned-phrase blacklist) via the official Nightbot API.
Project-URL: Homepage, https://github.com/aaronckj/nightbot-mcp
Project-URL: Issues, https://github.com/aaronckj/nightbot-mcp/issues
Author: aaronckj
License-Expression: MIT
License-File: LICENSE
Keywords: chatbot,mcp,model-context-protocol,moderation,nightbot,streaming
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: mcp<2,>=1.2
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# nightbot-mcp

An MCP (Model Context Protocol) server for [Nightbot](https://nightbot.tv):
manage custom chat commands, timers, regulars, and spam-protection filters —
including the **blacklist** (banned words/phrases for live chat) — through
the official [Nightbot API](https://api-docs.nightbot.tv).

- Every mutating tool accepts `dry_run=true` and returns a preview.
- `add_banned_phrases` appends to the blacklist without clobbering it
  (fetch → merge → update).
- No secrets in this repo or logged at runtime.

## Quick start

1. Create an app at [nightbot.tv/account/applications](https://nightbot.tv/account/applications)
   and generate an access token (scopes: `channel commands timers regulars
   spam_protection channel_send`).
2. Provide the token:

```bash
export NIGHTBOT_ACCESS_TOKEN=...     # or NIGHTBOT_MCP_SECRETS=vaultproxy
```

3. Add to your MCP client:

```bash
# Claude Code
claude mcp add nightbot -s user -- uvx nightbot-mcp
```

## Tools

| Area | Tools |
|---|---|
| Channel | `channel_info`, `join_channel`, `part_channel`, `send_chat_message` |
| Commands | `list_commands`, `add_command`, `update_command`, `delete_command` |
| Timers | `list_timers`, `add_timer`, `toggle_timer`, `delete_timer` |
| Regulars | `list_regulars`, `add_regular`, `remove_regular` |
| Spam protection | `get_spam_filter`, `update_spam_filter`, `add_banned_phrases` |
| Meta | `health_check` |

Filters: `blacklist`, `links`, `caps`, `symbols`, `repetitions`, `emotes`.
Blacklist entries support Nightbot's `*` wildcards.

## Development

```bash
pip install -e '.[dev]'
ruff check src tests && pytest
```

Tests are fully offline (fake HTTP opener).

## License

MIT
