RibbonSmith

<p align="center"> <img src="assets/logo.svg" width="160" alt="RibbonSmith logo — a smith's hammer forging a ribbon command button on an anvil"/> </p>

<h1 align="center">RibbonSmith</h1>

<p align="center"> <b>Forge Dynamics 365 command bars, declaratively.</b><br/> An MCP server that gives AI coding agents (and you) safe, validated, revertible ribbon customization — the way the classic Ribbon Workbench did it. </p>

---

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