Content
# Discord Server Builder MCP
Safe, self-hosted Discord server builder for AI coding agents. The project no longer runs a Discord AI bot or calls OpenAI, Claude, Gemini, Groq or OpenRouter. Agents create or edit JSON/YAML blueprints; this tool validates them, shows a preview/diff, writes backups and applies changes only after explicit confirmation.
## What This Tool Does
- Validates Discord server blueprints before any Discord API call.
- Previews create/update/delete operations as a dry run.
- Applies roles, categories, channels and permission overwrites after confirmation.
- Writes a backup before every apply and supports rollback from backups.
- Blocks Administrator roles and privileged permissions unless explicitly allowed.
- Blocks deletion unless both the blueprint and command line explicitly allow it.
- Exposes a CLI and an optional MCP server for Codex, Claude Code or other agents.
## Install
```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```
Create a Discord bot, invite it to the target server and grant only the permissions needed for the actions you plan to run. For live preview, export, backup and apply, set:
```bash
set DISCORD_BOT_TOKEN=your-discord-bot-token
```
Never commit `.env` files or real tokens. `.gitignore` excludes them by default.
## Blueprint Workflow
1. Ask the agent to create or edit a blueprint in `examples/` or another local file.
2. Validate it locally.
3. Preview the plan against an empty state, a backup file or a live guild.
4. Review the diff manually.
5. Apply only with the exact confirmation string.
```bash
python -m discord_builder validate examples/community-blueprint.yaml
python -m discord_builder preview examples/community-blueprint.yaml
python -m discord_builder preview examples/community-blueprint.yaml --guild-id 123456789012345678
python -m discord_builder apply examples/community-blueprint.yaml --guild-id 123456789012345678 --confirm APPLY:123456789012345678
```
Deletion is always opt-in twice:
```bash
python -m discord_builder apply blueprint.yaml --guild-id 123456789012345678 --allow-delete --confirm APPLY:123456789012345678
```
Administrator and privileged permissions are also opt-in:
```bash
python -m discord_builder apply team-blueprint.json --guild-id 123456789012345678 --allow-privileged --confirm APPLY:123456789012345678
```
## Commands
```bash
python -m discord_builder validate <blueprint>
python -m discord_builder preview <blueprint> [--state backup.json] [--guild-id GUILD_ID] [--json]
python -m discord_builder export --guild-id GUILD_ID --out current.json
python -m discord_builder backup --guild-id GUILD_ID --out-dir backups
python -m discord_builder apply <blueprint> --guild-id GUILD_ID --confirm APPLY:GUILD_ID
python -m discord_builder rollback <backup.json> --guild-id GUILD_ID --allow-delete --confirm ROLLBACK:GUILD_ID
python -m discord_builder mcp-server
```
## Blueprint Format
Blueprints are JSON or YAML objects:
```yaml
version: 1
safety:
delete_unknown_channels: false
delete_unknown_roles: false
allow_admin_roles: false
allow_privileged_permissions: false
roles:
- name: Member
color: "#57F287"
permissions: [view_channel, send_messages, read_message_history]
categories:
- name: Community
overwrites:
- target: "@everyone"
allow: [view_channel]
deny: []
channels:
- name: general
type: text
topic: Main chat
```
Supported channel types are `text`, `voice`, `forum` and `stage`. Text and forum channel names must be lowercase and use only letters, numbers, hyphens or underscores.
## Safety Model
The tool assumes an AI agent may make mistakes. Because of that:
- `preview` is read-only and is the normal agent planning step.
- `apply` requires `--confirm APPLY:<guild-id>`.
- `rollback` requires `--confirm ROLLBACK:<guild-id>` and `--allow-delete`.
- Unknown channels/roles are never deleted unless the blueprint sets `delete_unknown_*: true` and the command includes `--allow-delete`.
- `administrator` is rejected unless the blueprint sets `allow_admin_roles: true` and the command includes `--allow-admin`.
- Management/moderation permissions such as `manage_roles`, `manage_channels`, `ban_members`, `kick_members`, `manage_messages` and `mention_everyone` require `allow_privileged_permissions: true` plus `--allow-privileged`.
- A backup is written before every apply.
## MCP Usage
Run the MCP server over stdio:
```bash
python -m discord_builder mcp-server
```
Example MCP configuration:
```json
{
"mcpServers": {
"discord-server-builder": {
"command": "python",
"args": ["-m", "discord_builder", "mcp-server"],
"env": {
"DISCORD_BOT_TOKEN": "your-discord-bot-token",
"DISCORD_BUILDER_ENABLE_APPLY": "0"
}
}
}
}
```
MCP apply is disabled unless `DISCORD_BUILDER_ENABLE_APPLY=1`. Even then, the MCP tool requires the exact confirmation string `APPLY:<guild-id>`.
Recommended agent instruction:
> Create or update blueprint files only. Always run validation and preview first. Do not call apply until the human has reviewed the diff and provided the exact confirmation string.
## Backups And Rollback
Create a backup:
```bash
python -m discord_builder backup --guild-id 123456789012345678
```
Rollback from a backup:
```bash
python -m discord_builder rollback backups/123456789012345678-20260608T120000Z.json --guild-id 123456789012345678 --allow-delete --confirm ROLLBACK:123456789012345678
```
Rollback applies the backup as the desired state and can delete resources created after the backup, so it always requires `--allow-delete`.
## Development
Run local checks:
```bash
python -m unittest discover -s tests
python -m compileall discord_builder tests
```
