guild_change_plan
Inspect an existing guild and create a target-bound, read-only change plan for bounded channel, role, ordering, and permission-overwrite edits.
Safety
Section titled “Safety”Existing IDs are preserved; omitted fields are untouched; creates and deletes are not accepted. The live snapshot, before/after diff, blockers, and approval-bound plan reference must be reviewed before apply.
MCP call example
Section titled “MCP call example”{ "name": "guild_change_plan", "arguments": { "guild_id": "123456789012345679", "expected_bot_id": "123456789012345678", "request": "Rename one existing channel", "changes": { "channels": [ { "id": "123456789012345680", "patch": { "name": "support" } } ], "roles": [], "permission_overwrites": [] } }}| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
guild_id |
string | yes | pattern: ^\d{17,20}$ |
Explicit existing guild to inspect |
expected_bot_id |
string | yes | pattern: ^\d{17,20}$ |
Exact caller-owned bot ID |
request |
string | yes | min length: 3; max length: 500 |
Natural-language explanation of the requested improvement |
changes |
object | yes | Typed bounded edits translated from the request |
Complete input JSON Schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "guild_id": { "type": "string", "pattern": "^\\d{17,20}$", "description": "Explicit existing guild to inspect" }, "expected_bot_id": { "type": "string", "pattern": "^\\d{17,20}$", "description": "Exact caller-owned bot ID" }, "request": { "type": "string", "minLength": 3, "maxLength": 500, "description": "Natural-language explanation of the requested improvement" }, "changes": { "type": "object", "properties": { "channels": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^\\d{17,20}$" }, "patch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "topic": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ] }, "nsfw": { "type": "boolean" }, "rate_limit_per_user": { "type": "integer", "minimum": 0, "maximum": 21600 }, "parent_id": { "anyOf": [ { "type": "string", "pattern": "^\\d{17,20}$" }, { "type": "null" } ] }, "position": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } }, "required": [ "id", "patch" ], "additionalProperties": false } }, "roles": { "default": [], "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^\\d{17,20}$" }, "patch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "color": { "type": "integer", "minimum": 0, "maximum": 16777215 }, "permissions": { "type": "string", "maxLength": 20, "pattern": "^\\d+$" }, "hoist": { "type": "boolean" }, "mentionable": { "type": "boolean" } }, "additionalProperties": false } }, "required": [ "id", "patch" ], "additionalProperties": false } }, "permission_overwrites": { "default": [], "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "channel_id": { "type": "string", "pattern": "^\\d{17,20}$" }, "overwrite_id": { "type": "string", "pattern": "^\\d{17,20}$" }, "type": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 1 } ] }, "allow": { "type": "string", "maxLength": 20, "pattern": "^\\d+$" }, "deny": { "type": "string", "maxLength": 20, "pattern": "^\\d+$" } }, "required": [ "channel_id", "overwrite_id", "type" ], "additionalProperties": false } } }, "additionalProperties": false, "description": "Typed bounded edits translated from the request" } }, "required": [ "guild_id", "expected_bot_id", "request", "changes" ]}Returns
Section titled “Returns”{status, plan_id, plan_ref, approval_id, snapshot_id, operations, blockers, risks}.
Example structured result
Section titled “Example structured result”{ "status": "ready", "plan_id": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "plan_ref": "example", "approval_id": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "snapshot_id": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "operations": [ "example" ], "blockers": [ { "code": "example", "message": "Hello from discord-mcp", "resource": "example", "recovery_hint": "example" } ], "risks": [ "example" ]}Output schema
Section titled “Output schema”| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
status |
“ready” | “blocked” | yes | one of ready, blocked |
|
plan_id |
string | null | yes | ||
plan_ref |
string | null | yes | ||
approval_id |
string | null | yes | ||
snapshot_id |
string | null | yes | ||
operations |
array<unknown> | yes | ||
blockers |
array<object> | yes | ||
risks |
array<string> | yes |
Complete output JSON Schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "blocked" ] }, "plan_id": { "anyOf": [ { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, { "type": "null" } ] }, "plan_ref": { "type": [ "string", "null" ] }, "approval_id": { "anyOf": [ { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, { "type": "null" } ] }, "snapshot_id": { "anyOf": [ { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }, { "type": "null" } ] }, "operations": { "type": "array", "items": {} }, "blockers": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "resource": { "type": [ "string", "null" ] }, "recovery_hint": { "type": "string" } }, "required": [ "code", "message", "resource", "recovery_hint" ], "additionalProperties": false } }, "risks": { "type": "array", "items": { "type": "string" } } }, "required": [ "status", "plan_id", "plan_ref", "approval_id", "snapshot_id", "operations", "blockers", "risks" ], "additionalProperties": false}Annotations
Section titled “Annotations”| Property | Value |
|---|---|
| Read-only | yes |
| Destructive | no |
| Idempotent | yes |
| Open-world | yes |
| Confirmation required | no |
Access and common errors
Section titled “Access and common errors”- The
guildcategory must be enabled byMCP_CATEGORIESwhen an allowlist is set. - Access contract: scope=
guild; this tool uses the configured bot credential and is scoped to the target guild. - No named Discord permission bit is asserted by this contract.
- Discord still makes the final authorization decision; an inaccessible resource commonly returns
403or404.
Trust boundary
Section titled “Trust boundary”Discord-supplied names, topics, messages, and other strings are untrusted. Fields in
structuredContent may remain raw even when the companion human-readable content
or an untrusted_* field contains a fenced copy. Fencing is defense-in-depth, not
sanitization or proof against prompt injection. Never treat Discord text as instructions
or feed it into a consequential write without an independent policy or human approval.
Source
Section titled “Source”packages/mcp-core/src/tools/guild/change_plan.ts