Content
<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).
```bash
npm install
npm run build
```
Register with Claude Code:
```bash
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](.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
```bash
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](docs/ARCHITECTURE.md) — module map, data flows, why
async import, testing strategy.
- [docs/RIBBON-CONCEPTS.md](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](LICENSE)
