mcp_manage_ribbon

Summary

Field	Value
Tool name	manage_ribbon
MCP title	Manage classic Dataverse ribbon buttons and customizations
Category	advanced
Implementation	DynamicsCrm.DevKit.Cli/Mcp/Tools/ManageRibbonTool.cs
Estimated token count	~1051 tokens (tools/list tool JSON, o200k_base, measured 2026-06-18)
Last verified	2026-06-18

MCP Tool Description (Exact)

Classic/legacy RibbonDiffXml for Dataverse entities (via solution import).

TOOL SELECTION: Use for Dataverse ribbon/button customization: 'ribbon', 'legacy', 'classic', 'button', 'nút', 'custom button', 'action button', 'UI button', 'JavaScript button', 'sub_grid button', 'homepage grid button', or generic button requests. This MCP server exposes classic RibbonDiffXml operations only. For modern Power Fx command bar customization, use Power Apps command designer outside this MCP server.

Actions:
- list: entities with ribbon customizations in solution 'devkit-ribbon'
- buttons: all OOB+custom buttons across form/main_grid/sub_grid (entity_name)
- detail: current RibbonDiffXml (entity_name)
- update: apply operations. Required: entity_name + operations. Auto: validate → fetch existing → apply → validate XSD → backup → import → start PublishAll async
- undo: restore (entity_name + ribbonxml backup path)

SUPPORTED OPERATIONS (10): add_button, update_button, hide_button, show_button, add_split_button, update_split_button, add_flyout_static, update_flyout_static, hide_flyout_item, show_flyout_item

add_button REQUIRED: surface, label, library, function, enable_library, enable_function. OPTIONAL: modern_image, tooltip_title, tooltip_description, sequence (default 85), selection_min, selection_max. Selection count is off by default; for main_grid/sub_grid only, use selection_min=1 for one-or-more selected rows or selection_min=1+selection_max=1 for exactly one row.
update_button REQUIRED: button_id OR label. OPTIONAL: label, library, function, enable_library, enable_function, modern_image, tooltip_title, tooltip_description, sequence. NOTE: only works on custom buttons
hide_button / show_button REQUIRED: button_id. Supports OOB and custom
add_split_button REQUIRED: surface, label, library, function, enable_library, enable_function, items[](label,library,function,enable_library,enable_function). OPTIONAL: modern_image, tooltip_title, tooltip_description, sequence (default 85)
update_split_button REQUIRED: split_button_id OR label. items[]: item_label REQUIRED
add_flyout_static REQUIRED: surface, label, items[](label,library,function,enable_library,enable_function). OPTIONAL: modern_image, tooltip_title, tooltip_description, sequence (default 85)
update_flyout_static REQUIRED: flyout_id OR label. items[]: item_label REQUIRED
hide_flyout_item / show_flyout_item REQUIRED: flyout_label OR flyout_id + item_label

WORKFLOW: manage_ribbon(action='update', entity_name=..., operations=[...]). Auto-backup; failure blocks update. Ribbon needs PublishAll (entity-scoped publish doesn't work). Starts PublishAll async after update and returns needsWait=true with asyncOperationId. Wait with get_system_jobs before readback or the next prompt. Poll exactly 3 times using pollScheduleSeconds: 30 seconds, then 60 seconds, then 120 seconds. If the third poll does not report Succeeded or no system-job result is returned, stop waiting, do not call manage_ribbon(buttons/detail), and report the ribbon result to the user with a note that Dataverse publish is still running or did not complete successfully and the user must wait/check the job.

WHEN TO USE:
- Inspect existing ribbon (list/buttons/detail) before editing
- Add/update/hide/show ribbon buttons via operations array (action=update)
- Restore from backup (action=undo)
NAME RESOLUTION: entity_name and operation web resource fields (library, enable_library, modern_image) resolve Display Name contains first, then logical/unique/schema contains.
- Modern Power Fx command bar customization is not exposed by this MCP server

Parameters

Name	Type	Required	Default	Description
action	string	Yes	-	'list', 'buttons', 'detail', 'update', or 'undo'.
entity_name	string	No	""	Entity Display Name or logical name. Required: detail/update/undo/buttons.
operations	string	No	""	JSON array of ribbon operations for action='update'. Operations: add_button, update_button, hide_button, show_button, add_split_button, update_split_button, add_flyout_static, update_flyout_static, hide_flyout_item, show_flyout_item. add_button optional fields include selection_min and selection_max for main_grid/sub_grid SelectionCountRule; omit both to disable selection count, selection_min=1 means one or more rows, selection_min=1 + selection_max=1 means exactly one row.
ribbonxml	string	No	""	For 'undo': backup file path.
backup	boolean	No	true	Backup before overwrite.

Input Schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "description": "'list', 'buttons', 'detail', 'update', or 'undo'."
    },
    "entity_name": {
      "type": "string",
      "description": "Entity Display Name or logical name. Required: detail/update/undo/buttons.",
      "default": ""
    },
    "operations": {
      "type": "string",
      "description": "JSON array of ribbon operations for action='update'. Operations: add_button, update_button, hide_button, show_button, add_split_button, update_split_button, add_flyout_static, update_flyout_static, hide_flyout_item, show_flyout_item. add_button optional fields include selection_min and selection_max for main_grid/sub_grid SelectionCountRule; omit both to disable selection count, selection_min=1 means one or more rows, selection_min=1 + selection_max=1 means exactly one row.",
      "default": ""
    },
    "ribbonxml": {
      "type": "string",
      "description": "For 'undo': backup file path.",
      "default": ""
    },
    "backup": {
      "type": "boolean",
      "description": "Backup before overwrite.",
      "default": true
    }
  },
  "required": [
    "action"
  ]
}

Related MCP Resources

This tool does not require any MCP resources.

When To Use

• Inspect existing ribbon (list/buttons/detail) before editing
• Add/update/hide/show ribbon buttons via operations array (action=update)
• Restore from backup (action=undo)
• Modern Power Fx command bar customization is not exposed by this MCP server

Notes

• TOOL SELECTION: Use for Dataverse ribbon/button customization: 'ribbon', 'legacy', 'classic', 'button', 'nút', 'custom button', 'action button', 'UI button', 'JavaScript button', 'sub_grid button', 'homepage grid button', or generic button requests. This MCP server exposes classic RibbonDiffXml operations only. For modern Power Fx command bar customization, use Power Apps command designer outside this MCP server.
• NAME RESOLUTION: entity_name and operation web resource fields (library, enable_library, modern_image) resolve Display Name contains first, then logical/unique/schema contains.
• Modern Power Fx command bar customization is not exposed by this MCP server
• WORKFLOW: manage_ribbon(action='update', entity_name=..., operations=[...]). Auto-backup; failure blocks update. Ribbon needs PublishAll (entity-scoped publish doesn't work). Starts PublishAll async after update and returns needsWait=true with asyncOperationId. Wait with get_system_jobs before readback or the next prompt. Poll exactly 3 times using pollScheduleSeconds: 30 seconds, then 60 seconds, then 120 seconds. If the third poll does not report Succeeded or no system-job result is returned, stop waiting, do not call manage_ribbon(buttons/detail), and report the ribbon result to the user with a note that Dataverse publish is still running or did not complete successfully and the user must wait/check the job.

Example

{
  "action": "string"
}

Output

Returns CallToolResult from the MCP server. The response content and structured fields follow the tool implementation and model returned by ManageRibbonTool.manage_ribbon.

Prompt Examples

• "List ribbon buttons for the Account main grid and identify custom buttons."
• "Add a classic ribbon button that calls this JavaScript function for selected rows."
• "Hide this out-of-box ribbon button and tell me whether PublishAll is still running."