Privacy-safe soundboard inventory and reviewed changes

list_default_soundboard_sounds exposes Discord's bounded default inventory, while list_guild_soundboard_sounds and get_guild_soundboard_sound expose a complete guild inventory or one exact inventory member. Set capabilities.soundboardAudit: true and list every eligible guild in scopes.soundboardGuildIds. The guild allowlist must be a subset of readScope.guildIds when the outer read allowlist exists. The equivalent discord://soundboard/defaults, discord://guilds/{guildId}/soundboard, and discord://guilds/{guildId}/soundboard/{soundId} resources apply the same gate, scope, projection, and evidence checks.

Reads return only exact sound, guild, and creator IDs, bounded names, volume, availability, a tagged custom, Unicode, or absent emoji selection, unknown-field count, complete ownership-aware permission evidence for guild sounds, and explicit privacy metadata. Audio bytes, CDN URLs, creator profiles, embedded raw objects, and unknown raw values are projected out before return. Results are never cached, journaled, or persisted. Guild and sound names and Unicode emoji remain untrusted Discord data.

Guarded exact-scope soundboard playback

Playback is independent of soundboard inventory administration. Select the soundboard toolset, set capabilities.soundboardPlayback: true, and list every eligible ordinary voice channel in scopes.soundboardPlaybackChannelIds. The target list must remain inside readScope.channelIds when the outer channel boundary exists. Custom sounds additionally require their exact source guild in scopes.soundboardPlaybackSourceGuildIds, which must remain inside readScope.guildIds when the outer guild boundary exists. An empty source-guild list deliberately permits only Discord's default sounds, selected with sourceGuildId: null. Inventory audit, sound creation, and sound administration do not grant playback authority.

The connector does not join or maintain a Discord voice session. Before either playback tool can succeed, the same verified bot must already be connected through an independently managed voice client to the exact target channel. check_soundboard_playback then proves the pinned application and bot, exact ordinary voice channel and guild, complete connector membership, roles, and overwrites, exact sound availability, VIEW_CHANNEL, CONNECT, SPEAK, USE_SOUNDBOARD, conditional cross-guild USE_EXTERNAL_SOUNDS, and a current bot voice state that is not server-muted, server-deafened, self-deafened, or suppressed. Self-mute is reported but is not one of Discord's documented playback blockers. The check returns transient sound and voice evidence and writes no activity or receipt.

play_soundboard_sound accepts the same exact channel, sound, and nullable source plus one unique one-shot operationKey. It repeats every readiness check itself, so a prior check is operator guidance rather than reusable authorization. The write requires MCP host approval, acquires a durable exact-channel claim shared by connector processes, consumes the shared interaction rate and interval budget, atomically reserves a request-bound digest, and appends pending content-free activity before one exact non-retried POST. A completed matching key replays from the durable receipt without Discord reads or another sound; any mismatched, nonterminal, failed, uncertain, or malformed receipt conflicts.

Enabling playback starts the minimal Gateway projection with the standard GUILDS and GUILD_VOICE_STATES intents even when the general event feed is disabled. The connector begins an exact waiter before the REST request and accepts only VOICE_CHANNEL_EFFECT_SEND for the same guild, channel, verified bot, and sound. Every other effect is discarded, raw payloads never enter the event feed or storage, and a matching event upgrades successful verification from response-only to gateway-match. Discord's strict empty 204 remains sufficient for completion when the exact event is not observed. A Gateway event never repairs a failed or ambiguous REST result.

A deterministic Discord 4xx other than request timeout or rate limiting is failed. Request timeout, rate limiting, transport failure, Discord 5xx, malformed success, failed durable completion, or any otherwise ambiguous result is uncertain; the key remains spent and the exact channel claim remains quarantined for operator review. Do not issue another key to repeat an uncertain playback. Durable activity and receipt evidence contains only exact guild, channel, sound, and optional source-guild IDs, request and operation-key hashes, timestamps, activity ID, fixed outcomes and verification, and sanitized error category. Sound and channel names, voice state and profiles, roles, overwrites, permissions, Gateway payloads, raw keys, and transport causes are never persisted. Online doctor and smoke do not play a sound.

Reviewed soundboard creation and administration

Changes have no immediate-call path. Set capabilities.soundboardChanges: true in addition to audit scope. Creation also requires storage.soundboardRoots to contain one absolute canonical owned directory or a JSON array of such directories. Creation accepts one normalized name, volume from zero through one, a tagged custom, Unicode, or absent emoji selection, and one exact local MP3 or Ogg file. Ogg is limited to one valid Opus or Vorbis logical stream. Audio must be non-empty, no larger than 512 KiB, and no longer than 5.2 seconds. URLs, data URLs, base64 payloads, transported bytes, arbitrary streams, and playback fields are not accepted.

The narrow action union supports creation, metadata-only update, and exact-ID deletion. Updates may change name, volume, or emoji and never accept a file. A tagged none emoji deliberately clears the association. Custom emoji are resolved by exact ID in the target guild and must remain structurally valid and available. Normalized name collisions, local safety capacity, an absent update target, incomplete permission evidence, missing creator evidence, unknown target fields, malformed inventory state, or invalid audio blocks planning. Deleting an already absent target and requesting metadata that is already current are true no-ops without confirmation, reservation, activity, or mutation.

1. Call plan_guild_soundboard_change with the exact guild, action-specific fields, Discord audit-log reason, and unique one-shot operation key.
2. Review the verified application and bot IDs, exact guild and optional sound ID, current and desired privacy-safe metadata, ownership-aware permissions, custom emoji evidence, visible inventory, local audio provenance when present, privacy omissions, warnings, operation-key hash, and keyed digest.
3. If an update or deletion reports already-current, no confirmation, reservation, activity record, or Discord write is needed.
4. Call execute_guild_soundboard_change with identical inputs plus the digest.
5. Approve the signed MCP confirmation only if every exact identity, metadata field, file property, permission, warning, audit reason, operation-key hash, and digest remains intended.
6. Review the returned exact sound ID, privacy-safe observed metadata or verified absence, activity ID, verification, and outcome before any follow-up.

Discord requires CREATE_GUILD_EXPRESSIONS for sound creation. That permission also lets the bot update or delete a sound whose creator is that exact bot, while a sound owned by another user requires MANAGE_GUILD_EXPRESSIONS; guild ownership supplies both. Grant MANAGE_GUILD_EXPRESSIONS only when cross-owner administration is intentional. Discord's tier-specific soundboard capacity remains server-enforced after the connector's bounded inventory check.

For creation, planning opens the file without following the final symlink, verifies canonical containment, numeric process ownership, one hard link, regular-file type, exact bounded bytes, and stable metadata before and after the read. The parser verifies MP3 frame structure or complete Ogg pages, checks Ogg checksums and sequence continuity, rejects chained or multiplexed streams, derives codec and duration from the media structure, and does not trust the filename extension or caller-supplied media type. A process-keyed HMAC binds the byte digest and stable file properties into the plan. The full digest also binds the normalized request, verified identities, exact guild and complete inventory, relevant roles, permission and ownership evidence, current and desired metadata, custom emoji evidence, privacy projection, and warnings. A connector restart invalidates outstanding digests.

The MCP adapter rebuilds the plan before approval, and the service rebuilds it immediately before mutation. Execution atomically reserves the operation-key hash and appends a pending content-free activity record before exactly one non-retried POST, PATCH, or DELETE. Creation and update require an exact sound GET for readback; deletion requires exact 404 absence from that route. Matching metadata or absence is completed, valid server-adjusted state is completed-with-drift, a known pre-write Discord 4xx is failed, and transport failure, Discord 5xx, malformed success, failed post-write verification, or failed receipt finalization is uncertain. Audio bytes cannot be read back, so verification covers exact identity and stable metadata rather than claiming byte equality with Discord's stored sound.

All soundboard changes in one guild serialize inside one process because creation capacity, names, ownership, roles, and permission evidence are shared. The production facade additionally acquires a durable exact guild soundboard-collection claim, so connector processes sharing the activity-state root exclude overlapping changes. An uncertain result retains that claim for operator review before another key can be reserved. Activity and operation records contain only exact guild and optional sound IDs, action, plan digest, operation-key hash, timestamps, fixed verification and outcome values, activity ID, and sanitized error category. Names, emoji, local paths, byte digests, audio content, creator profiles, role names, audit reasons, raw operation keys, permission evidence, and raw Discord responses never enter durable records, diagnostics, or telemetry. See Discord's soundboard reference and permission flags.

Canonical source: docs/reference.md