RibbonSmith talks to your Dataverse environment with plain Web API calls under your own identity. Nothing is installed in the environment; a small unmanaged container solution (RibbonEditMCP_<entity>) is created per edited entity to carry the customizations — the same "workspace solution" mechanism the Ribbon Workbench used.

Why

Hand-writing RibbonDiffXml fails easily: ids, locations, template aliases and element order must all be exactly right, and the feedback loop (import → publish → check) is slow. RibbonSmith closes the loop for an agent:

• Grounding — read tools return the real composed ribbon (every valid location, control id, command and sequence) as compact JSON.
• Declarative writes — ribbon_add_button & friends generate schema-correct XML; the escape hatch ribbon_edit_diff accepts raw XML for advanced cases.
• Validation before anything touches the server — references, locations, element order, web-resource existence, unsupported-entity blocklist.
• Transactional publish — validate → backup → async import → publish → verify the change is actually live by re-reading the composed ribbon.
• Instant revert — every checkout and publish snapshots a restorable backup.

Setup

Prerequisites: Node.js ≥ 20 and a Dataverse user with permission to create/ import solutions and publish (e.g. System Administrator / System Customizer).

npm install
npm run build

Register with Claude Code:

claude mcp add ribbonsmith --env RIBBON_MCP_ENV_URL=https://yourorg.crm4.dynamics.com -- node <absolute-path>/ribbonsmith/dist/index.js

Or copy .mcp.json.example to your project's .mcp.json.

Authentication

On the first call that needs the network, RibbonSmith acquires a token using the first strategy that works (override with RIBBON_MCP_AUTH):

| Strategy | RIBBON_MCP_AUTH | How it works | |---|---|---| | Service principal | clientsecret | Set RIBBON_MCP_TENANT_ID, RIBBON_MCP_CLIENT_ID, RIBBON_MCP_CLIENT_SECRET. For CI/pipelines; the app registration needs an application user in the environment. | | Azure CLI | azcli | Reuses your az login session (requires Azure CLI). | | Browser SSO | interactive | Opens your browser for a normal Microsoft Entra sign-in (auth code + PKCE on a localhost loopback), then caches and silently refreshes tokens — the same sign-in experience as Microsoft's official Dataverse MCP local proxy. |

In auto mode (default) the order is: clientsecret (if env vars present) → azcli (if available) → interactive. Tokens from the interactive flow are cached in the workspace directory; delete token-cache.json to sign out.

The interactive flow uses the public client id Microsoft ships in its own Dataverse QuickStart samples (51f81489-…), requesting the standard user_impersonation delegated permission — so unlike the official Dataverse MCP server's proxy, no tenant admin consent or Power Platform admin center enablement is required. If your tenant restricts that client id, register your own public client app (redirect URI http://localhost, Dynamics CRM user_impersonation permission) and set RIBBON_MCP_CLIENT_ID.

The edit lifecycle

ribbon_checkout ──► edit tools (local only) ──► ribbon_preview_diff ──► ribbon_publish
      │                                                                     │
      └── backup (restorable)            backup (pre-publish) ──────────────┘
                              ribbon_restore_backup  ◄── revert anytime

1. ribbon_checkout { entity: "account" } — snapshots the current ribbon customizations (backup) and creates a local working copy of the entity's RibbonDiffXml.
2. Edit locally — none of these touch the environment: ribbon_get_structure (your map of valid targets), ribbon_add_button, ribbon_hide_control, ribbon_customize_command (copy an out-of-the-box command into the diff to modify it), ribbon_edit_diff (validated raw XML), ribbon_remove_customization, ribbon_discard.
3. ribbon_preview_diff — the exact XML that will be published + full validation report.
4. ribbon_publish — validates, backs up, submits an async solution import, publishes, then verifies the controls are live (or hidden) in the freshly retrieved composed ribbon. Server-side imports take 1–3 minutes; if the import outlasts waitSeconds (default 120), the tool returns status: "importing" — call ribbon_publish_status to complete it.
5. ribbon_restore_backup — re-import any backup and publish: full revert.

Working files and backups live under ~/.dataverse-ribbon-mcp/<env-host>/ (override with RIBBON_MCP_WORKSPACE). Everything is a plain file; worst case, import a backup zip manually through the maker portal.

Example: agent session

User: Add a "Send to SAP" button on the account form that calls new_/js/sap.js: sendToSap(recordId), only for existing records.

ribbon_checkout        { entity: "account" }
ribbon_get_structure   { entity: "account", location: "Form" }
ribbon_add_button      {
  entity: "account",
  id: "new_.account.SendToSap.Button",
  location: "Mscrm.Form.account.MainTab.Save.Controls._children",
  label: "Send to SAP",
  sequence: 45,
  modernImage: "ExportToExcel",
  action: { type: "JavaScriptFunction", library: "new_/js/sap.js",
            functionName: "sendToSap",
            parameters: [{ type: "CrmParameter", value: "FirstPrimaryItemId" }] },
  enableRules: [{ type: "FormStateRule", id: "new_.account.SendToSap.Existing",
                  state: "Existing", default: true }]
}
ribbon_preview_diff    { entity: "account" }
ribbon_publish         { entity: "account" }
  → { status: "published", verification: { status: "verified" }, backupId: "..." }

Tool reference

| Tool | Network | Purpose | |---|---|---| | ribbon_status | yes | WhoAmI, checkouts, recent backups | | ribbon_checkout | yes | Begin editing; snapshot backup + local working copy | | ribbon_get_structure | cached | Composed ribbon as JSON (tabs → groups → controls) | | ribbon_get_command | cached | One command's actions + rules (for reuse/customization) | | ribbon_get_diff | no | Current working RibbonDiffXml + summary | | ribbon_add_button | no* | Declarative button/command/rules/labels | | ribbon_hide_control | no* | HideCustomAction for an existing control | | ribbon_customize_command | no* | Copy an OOTB command into the diff | | ribbon_edit_diff | no* | Replace the whole working diff (validated) | | ribbon_remove_customization | no | Remove one element from the diff by id | | ribbon_preview_diff | no* | Diff XML + validation report | | ribbon_publish | yes | Validate → backup → async import → publish → verify | | ribbon_publish_status | yes | Poll/complete a pending publish or restore import | | ribbon_discard | no | Reset working copy to last exported state | | ribbon_list_backups | no | List restorable snapshots | | ribbon_restore_backup | yes | Re-import a snapshot + publish (revert) |

* validation may consult the cached composed ribbon and check web-resource existence over the network.

Safety model

• Every ribbon_checkout and every ribbon_publish writes a timestamped solution zip before any change; ribbon_restore_backup re-imports it.
• Publishes only ever touch the RibbonDiffXml node inside a fresh export of the container solution — entity metadata is never round-tripped (the entity ships as an unmodified="1" shell).
• Validation blocks publishes on: malformed XML, wrong element order, missing Mscrm.Templates, duplicate ids, unresolved command/rule/label references, missing web resources, unsupported system entities.
• Import failures surface the importjob's own error text; imports are transactional server-side, so a failed import changes nothing.

Status & limitations

• Entity ribbons: stable. The full lifecycle (add → publish → verify → hide → publish → verify → restore → verify) is covered by a live E2E suite (test/e2e/run-e2e.ts) plus 56 unit tests over a real composed ribbon.
• Application ribbon (APPLICATION): EXPERIMENTAL. Implemented per the documented schema (component type 50, diff under ImportExportXml) but not yet covered by the live E2E suite. Keep backup ids at hand.
• Classic RibbonDiffXml only: commands built with the modern Power Apps command designer (Power Fx / appaction) are not read or written. Classic customizations render fine in Unified Interface.
• Flyout/Menu/group/tab creation goes through ribbon_edit_diff (raw XML).
• One editor per entity at a time is assumed (shared container solution).

Development

npm test                                    # unit tests (vitest)
npx tsc --noEmit                            # typecheck
npx tsx test/e2e/run-e2e.ts https://yourorg.crm4.dynamics.com
                                            # live E2E — modifies + restores the
                                            # 'contact' ribbon in that environment!

• docs/ARCHITECTURE.md — module map, data flows, why async import, testing strategy.
• docs/RIBBON-CONCEPTS.md — a primer on ribbon XML (composed ribbon vs diff, locations, commands/rules, Command Checker).

Acknowledgments

RibbonSmith re-implements, as MCP tools, the declarative editing model pioneered by Scott Durow's Ribbon Workbench — for years the way humans customized Dynamics ribbons safely. This project shares no code with it; the mechanism (workspace solution → RibbonDiffXml splice → import → publish) was studied from its observable behavior and from Microsoft's public documentation of the ribbon schemas and solution APIs.

License

MIT