Skip to main content
Glama
Sign In
Discord MCP - Discord server management MCP for AI agents

Discord MCP - Discord server management MCP for AI agents

by OrygnsCode
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Plan server build

plan_server_build
Read-only

Validates a Discord blueprint and stages an ordered build plan, checking limits, name collisions, role references, features, and bot permissions without changing anything.

Instructions

Validate a blueprint against the live server and stage an ordered build plan. Checks Discord limits, name collisions, role references, feature requirements, and the bot's permissions, and reports every problem at once. Changes nothing on Discord. Use it for any multi-step structure, even a small one: the plan shows the user every step before anything happens. By default existing channels and roles with matching names are reused as they are. With update_existing, existing items are changed to match the blueprint too: renames (items carrying an id from export_server_blueprint), permissions, colors, topics, slowmode, category moves, and who can see or post. An item changes only the settings it lists; list one empty to clear it. To delete roles, categories, or channels, list them in remove; leaving something out of a blueprint never deletes it. Each change shows before and after, each deletion what it loses, with risks flagged. A plan that changes or deletes runs only by its plan_id, exactly as shown, or not at all.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "blueprint": "<blueprint>"
    },
    "name": "plan_server_build"
  }
}

Input Schema

NameRequiredDescriptionDefault
guildNoGuild (server) name or ID. Omit to use the default guild.
removeNoItems to delete, by name or id. Deletions run last. The blueprint may be empty when only deleting.
blueprintYesThe desired structure: roles, categories, channels.
update_existingNoAlso change existing items to match the blueprint. Default false: reuse them as they are.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed28 schema fields changedv1.4.2
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / properties / blueprint / properties / categories / items / properties / channels / items / properties / id
      Added value: +{
+  "description": "Discord id from export_server_blueprint. Matches this exact item, so a new name renames it.",
+  "pattern": "^\\d{17,20}$",
+  "type": "string"
+}
    • addedInput schema / properties / blueprint / properties / categories / items / properties / channels / items / properties / permissions
      Added value: +{
+  "description": "Extra permissions per role here, beyond who can see and post (private_to, read_only, posting_roles). Example: [{\"role\": \"Event Staff\", \"allow\": [\"mention_everyone\", \"embed_links\"]}]. A listed role's extras become exactly these; roles not listed keep theirs.",
+  "items": {
+    "properties": {
+      "allow": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "deny": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "role": {
+        "description": "Role name, or @everyone.",
+        "maxLength": 100,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "role"
+    ],
+    "type": "object"
+  },
+  "maxItems": 50,
+  "type": "array"
+}
    • changedInput schema / properties / blueprint / properties / categories / items / properties / channels / items / properties / posting_roles / description
      Previous value: -"With read_only: role names that may still post."New value: +"With read_only: role names that may still post and start threads."
    • addedInput schema / properties / blueprint / properties / categories / items / properties / channels / items / properties / private_to / anyOf
      Added value: +[
+  {
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]
    • changedInput schema / properties / blueprint / properties / categories / items / properties / channels / items / properties / private_to / description
      Previous value: -"Role names that can see this channel. Everyone else is denied view."New value: +"Role names that can see this channel; everyone else is denied view. [] leaves only admins. null makes it visible to everyone. Omit to follow the category."
    • removedInput schema / properties / blueprint / properties / categories / items / properties / channels / items / properties / private_to / items
      Removed value: -{
-  "type": "string"
-}
    • removedInput schema / properties / blueprint / properties / categories / items / properties / channels / items / properties / private_to / type
      Removed value: -"array"
    • addedInput schema / properties / blueprint / properties / categories / items / properties / id
      Added value: +{
+  "description": "Discord id from export_server_blueprint. Matches this exact item, so a new name renames it.",
+  "pattern": "^\\d{17,20}$",
+  "type": "string"
+}
    • addedInput schema / properties / blueprint / properties / categories / items / properties / permissions
      Added value: +{
+  "description": "Extra permissions per role here, beyond who can see and post (private_to, read_only, posting_roles). Example: [{\"role\": \"Event Staff\", \"allow\": [\"mention_everyone\", \"embed_links\"]}]. A listed role's extras become exactly these; roles not listed keep theirs.",
+  "items": {
+    "properties": {
+      "allow": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "deny": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "role": {
+        "description": "Role name, or @everyone.",
+        "maxLength": 100,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "role"
+    ],
+    "type": "object"
+  },
+  "maxItems": 50,
+  "type": "array"
+}
    • addedInput schema / properties / blueprint / properties / categories / items / properties / private_to / anyOf
      Added value: +[
+  {
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]
    • changedInput schema / properties / blueprint / properties / categories / items / properties / private_to / description
      Previous value: -"Role names that can see the whole category."New value: +"Role names that can see the whole category. [] leaves only admins. null makes it visible to everyone."
    • removedInput schema / properties / blueprint / properties / categories / items / properties / private_to / items
      Removed value: -{
-  "type": "string"
-}
    • removedInput schema / properties / blueprint / properties / categories / items / properties / private_to / type
      Removed value: -"array"
    • addedInput schema / properties / blueprint / properties / channels / items / properties / id
      Added value: +{
+  "description": "Discord id from export_server_blueprint. Matches this exact item, so a new name renames it.",
+  "pattern": "^\\d{17,20}$",
+  "type": "string"
+}
    • addedInput schema / properties / blueprint / properties / channels / items / properties / permissions
      Added value: +{
+  "description": "Extra permissions per role here, beyond who can see and post (private_to, read_only, posting_roles). Example: [{\"role\": \"Event Staff\", \"allow\": [\"mention_everyone\", \"embed_links\"]}]. A listed role's extras become exactly these; roles not listed keep theirs.",
+  "items": {
+    "properties": {
+      "allow": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "deny": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "role": {
+        "description": "Role name, or @everyone.",
+        "maxLength": 100,
+        "minLength": 1,
+        "type": "string"
+      }
+    },
+    "required": [
+      "role"
+    ],
+    "type": "object"
+  },
+  "maxItems": 50,
+  "type": "array"
+}
    • changedInput schema / properties / blueprint / properties / channels / items / properties / posting_roles / description
      Previous value: -"With read_only: role names that may still post."New value: +"With read_only: role names that may still post and start threads."
    • addedInput schema / properties / blueprint / properties / channels / items / properties / private_to / anyOf
      Added value: +[
+  {
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]
    • changedInput schema / properties / blueprint / properties / channels / items / properties / private_to / description
      Previous value: -"Role names that can see this channel. Everyone else is denied view."New value: +"Role names that can see this channel; everyone else is denied view. [] leaves only admins. null makes it visible to everyone. Omit to follow the category."
    • removedInput schema / properties / blueprint / properties / channels / items / properties / private_to / items
      Removed value: -{
-  "type": "string"
-}
    • removedInput schema / properties / blueprint / properties / channels / items / properties / private_to / type
      Removed value: -"array"
    • addedInput schema / properties / blueprint / properties / roles / items / properties / color / anyOf
      Added value: +[
+  {
+    "pattern": "^#?[0-9a-fA-F]{6}$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / blueprint / properties / roles / items / properties / color / description
      Added value: +"null clears it."
    • removedInput schema / properties / blueprint / properties / roles / items / properties / color / pattern
      Removed value: -"^#?[0-9a-fA-F]{6}$"
    • removedInput schema / properties / blueprint / properties / roles / items / properties / color / type
      Removed value: -"string"
    • addedInput schema / properties / blueprint / properties / roles / items / properties / id
      Added value: +{
+  "description": "Discord id from export_server_blueprint. Matches this exact item, so a new name renames it.",
+  "pattern": "^\\d{17,20}$",
+  "type": "string"
+}
    • addedInput schema / properties / remove
      Added value: +{
+  "description": "Items to delete, by name or id. Deletions run last. The blueprint may be empty when only deleting.",
+  "properties": {
+    "categories": {
+      "items": {
+        "type": "string"
+      },
+      "maxItems": 50,
+      "type": "array"
+    },
+    "channels": {
+      "items": {
+        "type": "string"
+      },
+      "maxItems": 500,
+      "type": "array"
+    },
+    "roles": {
+      "items": {
+        "type": "string"
+      },
+      "maxItems": 100,
+      "type": "array"
+    }
+  },
+  "type": "object"
+}
    • addedInput schema / properties / update_existing
      Added value: +{
+  "description": "Also change existing items to match the blueprint. Default false: reuse them as they are.",
+  "type": "boolean"
+}
  2. Changed3 schema fields changedv1.4.0
    • changedInput schema / properties / blueprint / properties / channels / maxItems
      Previous value: -100New value: +500
    • addedInput schema / properties / blueprint / properties / roles / description
      Added value: +"Highest role first, the way the server settings list them. A build creates them in this order and that order is the hierarchy."
    • changedInput schema / properties / blueprint / properties / roles / maxItems
      Previous value: -50New value: +250
  3. Changed9 schema fields changedv1.3.0
    • removedInput schema / additionalProperties
      Removed value: -false
    • removedInput schema / properties / blueprint / additionalProperties
      Removed value: -false
    • removedInput schema / properties / blueprint / properties / categories / items / additionalProperties
      Removed value: -false
    • removedInput schema / properties / blueprint / properties / categories / items / properties / channels / items / additionalProperties
      Removed value: -false
    • removedInput schema / properties / blueprint / properties / channels / items / $ref
      Removed value: -"#/properties/blueprint/properties/categories/items/properties/channels/items"
    • addedInput schema / properties / blueprint / properties / channels / items / properties
      Added value: +{
+  "name": {
+    "maxLength": 100,
+    "minLength": 1,
+    "type": "string"
+  },
+  "nsfw": {
+    "type": "boolean"
+  },
+  "posting_roles": {
+    "description": "With read_only: role names that may still post.",
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  },
+  "private_to": {
+    "description": "Role names that can see this channel. Everyone else is denied view.",
+    "items": {
+      "type": "string"
+    },
+    "type": "array"
+  },
+  "read_only": {
+    "description": "Deny sending for everyone; for rules and announcements.",
+    "type": "boolean"
+  },
+  "slowmode_seconds": {
+    "maximum": 21600,
+    "minimum": 0,
+    "type": "integer"
+  },
+  "topic": {
+    "maxLength": 1024,
+    "type": "string"
+  },
+  "type": {
+    "description": "Default text.",
+    "enum": [
+      "text",
+      "voice",
+      "forum",
+      "stage",
+      "announcement"
+    ],
+    "type": "string"
+  }
+}
    • addedInput schema / properties / blueprint / properties / channels / items / required
      Added value: +[
+  "name"
+]
    • addedInput schema / properties / blueprint / properties / channels / items / type
      Added value: +"object"
    • removedInput schema / properties / blueprint / properties / roles / items / additionalProperties
      Removed value: -false
  4. First observedv1.0.2

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Changes nothing on Discord' rather than contradicting it. Beyond that it discloses the validation checks, the aggregate error reporting, before/after previews for changes, risk-flagged deletions, and the plan_id execution constraint — exactly the behavioral context the annotation cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and the safety statement before the conditional details on update_existing and remove. It is dense and long — some sentences pack several distinct rules — but nearly every sentence carries decision-relevant information rather than restating the name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a deeply nested blueprint tool with no output schema, the description covers what validation happens, what the plan contains (before/after, deletion losses, flagged risks), and how the plan is later executed via plan_id. An agent has enough to call it correctly and explain the result to a user without further documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, and the description goes beyond it by explaining what update_existing actually mutates (renames via exported ids, permissions, colors, topics, slowmode, category moves, visibility) and the non-destructive rule that omitted items are never deleted. The remaining gap is that the guild and blueprint nesting semantics are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb pair and resource: 'Validate a blueprint against the live server and stage an ordered build plan.' It also distinguishes itself from the execution sibling by noting a plan 'runs only by its plan_id, exactly as shown,' so an agent can tell planning from executing without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear when-to-use guidance: 'Use it for any multi-step structure, even a small one,' plus the default reuse behavior and the update_existing and remove conditions. It stops short of explicitly naming execute_build_plan as the required follow-up or stating when a single-item tool (create_channel, create_role) is preferable, so it is strong but not fully routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools