pi-discord-server

A Pi extension for designing and administering Discord servers through Discord's official REST API. It manages server layouts, roles, channel permissions, messages, and member roles.

Important: write tools execute immediately. Use a test server first and grant the bot only the permissions it needs. Never use a Discord user token or self-bot.

Install

From the Git repository

pi install git:https://git.otmatas.com/pi-extensions/pi-discord-server.git

Restart Pi after installation. The package is then discovered automatically.

Local development

git clone https://git.otmatas.com/pi-extensions/pi-discord-server.git
cd pi-discord-server
npm install
npm run typecheck
pi -e ./extensions/discord-server.ts

For automatic discovery during local development, copy/link the package to Pi's extension location, or install the local package:

pi install ./pi-discord-server

Configure a Discord bot

1. Start Pi with the extension installed.
2. Run /discord-login.
3. Approve opening the Discord Developer Portal.
4. In the portal, create a New Application.
5. Open Bot and click Add Bot.
6. Copy the bot token and Application ID when prompted by Pi.
7. Let /discord-login open the generated invite link, select your server, and authorize it.
8. Run /discord-status to verify the connection.

The setup command stores credentials in ~/.pi/agent/pi-discord-server/config.json, using private file permissions where supported.

Bot permissions

The generated invite asks for:

• View Channels
• Read Message History
• Send Messages
• Manage Channels
• Manage Roles

Do not give the bot Administrator unless you fully understand the risk. Discord role hierarchy still applies: the bot's highest role must be above roles it needs to change or assign.

For member listing, enable Server Members Intent in Discord Developer Portal → Application → Bot → Privileged Gateway Intents. Larger verified bots may require Discord approval for this intent.

Treat the bot token like a password. Do not commit it, share it, or paste it into chat. Reset it in the Developer Portal if it is exposed.

Environment variable option

DISCORD_BOT_TOKEN overrides the token stored by /discord-login:

$env:DISCORD_BOT_TOKEN = "your-bot-token"
pi

Tools

Server inspection

• discord_list_servers
• discord_inspect_server
• discord_list_members
• discord_read_messages

Roles and members

• discord_create_role
• discord_update_role
• discord_delete_role
• discord_add_member_role
• discord_remove_member_role

Role updates, deletion, and member role assignment validate role hierarchy first.

Channels and permissions

• discord_create_category
• discord_create_channel — text, voice, announcement, stage, and forum channels; supports topic, NSFW, slowmode, bitrate, user limits, ordering, and archive settings.
• discord_update_channel
• discord_create_thread
• discord_delete_channel
• discord_set_channel_permissions
• discord_audit_category_permissions
• discord_sync_category_permissions

Layout management

• discord_plan_layout — preview missing categories/channels.
• discord_apply_layout — create missing categories/channels only; it never edits or deletes existing ones.

Messages

• discord_send_message — text, embeds, and buttons.
• discord_update_message / discord_delete_message — bot-authored messages only.
• discord_pin_message / discord_unpin_message.

Custom buttons can be displayed but this REST-only extension cannot receive button-click interactions. A long-running Gateway bot is needed to handle them.

Example prompts

List my Discord servers, then inspect the one named Community.

Create a START HERE category with rules, announcements, and introductions channels.

Create a private STAFF category, deny View Channel to @everyone, allow the Owners role, then audit and synchronize every child channel.

Send a polished onboarding embed to the rules channel and pin it.

Private-category checklist

To avoid staff channels leaking into the public server view:

1. Set category overwrites first: deny View Channel for @everyone; allow the appropriate staff role.
2. Create child channels inside that category.
3. Run discord_audit_category_permissions.
4. Run discord_sync_category_permissions for any channel that differs from the category.
5. Avoid independent @everyone allow overwrites on staff channels.

Limitations

• Discord user profile descriptions are not available through the normal bot API.
• This extension cannot run another bot's slash commands or configure third-party bot dashboards (for example, Ticket Tool). Configure those through their official commands/dashboard; this extension can create the related structure and publish instructions.
• All destructive actions are immediate. Inspect the server and IDs before using delete/update tools.

Development

npm install
npm run typecheck
npm pack