# superdoc_mutations

All steps succeed or all fail; no partial application. Execute multiple operations atomically in one batch. Use this for any workflow needing 2+ changes. Supported step types: text (text.rewrite, text.insert, text.delete), format (format.apply), create (create.heading, create.paragraph, create.table), assert. Each step has an id, an op, a "where" clause for targeting ({by:"select", select:{...}, require:"first"|"exactlyOne"|"all"} or {by:"ref", ref:"..."} or {by:"block", nodeType:"paragraph", nodeId:"..."}), and "args" with operation-specific parameters. Use {by:"block", nodeType, nodeId} when you want to rewrite, delete, format, or anchor against a whole known block from superdoc_get_content action "blocks" without relying on text matching. For full-paragraph or full-clause rewrites, first call superdoc_get_content with action:"blocks" and includeText:true, then rewrite the matching block by nodeId. For a placeholder or name within a tab-separated paragraph, use a text.rewrite where.by:"select" targeting only the exact placeholder; a whole-block plain-text rewrite omitting tabs deletes those controls. Use {by:"select"} only for substring edits, discovery, or insertion relative to a sentence fragment; do NOT use a shortened text selector to replace an entire known block. For create steps, "where" targets an existing anchor block and args.position ("before" or "after") controls placement. Sequential creates targeting the same anchor maintain correct order via internal position mapping. For format.apply with require "all", use a node selector to format every heading or paragraph at once: {by:"select", select:{type:"node", nodeType:"heading"}, require:"all"}. Selectors resolve at compile time (before execution). This means format.apply steps CANNOT target content created by earlier create steps in the same batch. Split creates and formatting into separate batches: first a mutations call with creates, then a mutations call with format.apply. Action "preview" dry-runs the plan. Action "apply" executes it. If a selector matches nothing, the failure reports the step id plus selector details so you can retry with a shorter or more distinctive anchor. Do NOT create two steps that target overlapping text in the same block; combine them into a single text.rewrite step. EXAMPLES: 1. {"action":"apply","atomic":true,"changeMode":"direct","steps":[{"id":"s1","op":"text.rewrite","where":{"by":"select","select":{"type":"text","pattern":"old term"},"require":"all"},"args":{"replacement":{"text":"new term"}}},{"id":"s2","op":"text.delete","where":{"by":"select","select":{"type":"text","pattern":" (deprecated)"},"require":"all"},"args":{}}]} 2. {"action":"apply","steps":[{"id":"r1","op":"text.rewrite","where":{"by":"block","nodeType":"paragraph","nodeId":"<nodeId>"},"args":{"replacement":{"text":"Updated clause text."}}},{"id":"f1","op":"format.apply","where":{"by":"select","select":{"type":"node","nodeType":"heading"},"require":"all"},"args":{"inline":{"color":"#FF0000"}}},{"id":"f2","op":"format.apply","where":{"by":"select","select":{"type":"text","pattern":"Confidential Information"},"require":"all"},"args":{"inline":{"bold":true}}}]}

Agent View of the PolicyLayer registry record for `superdoc_mutations`. HTML page: https://policylayer.com/tools/superdoc-mcp/superdoc-mutations

## Facts

- Tool: `superdoc_mutations`
- Server: Superdoc (`@superdoc/mcp`) — https://policylayer.com/tools/superdoc-mcp.md
- Install: `npx -y @superdoc/mcp`
- Homepage: https://www.npmjs.com/package/@superdoc/mcp
- Risk category: Destructive (Critical risk)
- Registry record: grade F, identity unverified
- Server rate-limited: no
- Parameters: 9 (5 required)
- Recommended policy verdict: Hidden

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `in` | object | no | Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, e |
| `force` | boolean | no | Bypass confirmation checks. Only for action 'apply'. Omit for other actions. |
| `steps` | array | yes | Ordered array of mutation steps. Each step needs 'op' (text.rewrite, text.insert, text.delete, format.apply, or assert) and a 'where' targeting clause. |
| `action` | string | yes | The action to perform. One of: apply, preview. |
| `atomic` | boolean | yes | Must be true. All steps execute as one atomic transaction. |
| `detail` | object | no | Only for action 'preview'. Omit for other actions. |
| `changeMode` | string | yes | Required. Use 'direct' for immediate edits or 'tracked' for suggestions. Must always be provided. |
| `session_id` | string | yes | Session ID from superdoc_open. |
| `expectedRevision` | string | no | Document revision for optimistic concurrency. Mutation fails if document was modified since this revision. Only for action 'preview'. Omit for other actions. |

Parameters from the server's own tool schema.

## Example call (MCP tools/call, JSON-RPC 2.0)

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "superdoc_mutations",
    "arguments": {
      "steps": [],
      "action": "<action>",
      "atomic": false,
      "changeMode": "<changeMode>",
      "session_id": "<session_id>"
    }
  }
}
```

## Why superdoc_mutations is rated Critical

An AI agent that decides to call superdoc_mutations doesn't hesitate, doesn't double-check, and doesn't stop at one. Whatever it removes from Superdoc is gone. There is no undo for destructive operations.

Risk signals: High parameter count (11 properties)

## Use case

AI agents call superdoc_mutations to permanently remove resources in Superdoc, typically in cleanup and lifecycle workflows. It does its job in a single call, and there is no undo.

## Recommended policy (PolicyLayer)

Verdict: **Hidden**. Enforced by the PolicyLayer MCP gateway (https://policylayer.com/mcp-gateway) before a call reaches Superdoc:

```json
{
  "version": "1",
  "default": "deny",
  "hide": [
    "superdoc_mutations"
  ]
}
```

## Other tools on Superdoc (12)

- `superdoc_table` — Destructive — https://policylayer.com/tools/superdoc-mcp/superdoc-table.md
- `superdoc_track_changes` — Destructive — https://policylayer.com/tools/superdoc-mcp/superdoc-track-changes.md
- `superdoc_format` — Execute — https://policylayer.com/tools/superdoc-mcp/superdoc-format.md
- `superdoc_get_content` — Read — https://policylayer.com/tools/superdoc-mcp/superdoc-get-content.md
- `superdoc_list` — Read — https://policylayer.com/tools/superdoc-mcp/superdoc-list.md
- `superdoc_search` — Read — https://policylayer.com/tools/superdoc-mcp/superdoc-search.md
- `superdoc_close` — Write — https://policylayer.com/tools/superdoc-mcp/superdoc-close.md
- `superdoc_comment` — Write — https://policylayer.com/tools/superdoc-mcp/superdoc-comment.md
- `superdoc_create` — Write — https://policylayer.com/tools/superdoc-mcp/superdoc-create.md
- `superdoc_edit` — Write — https://policylayer.com/tools/superdoc-mcp/superdoc-edit.md
- `superdoc_open` — Write — https://policylayer.com/tools/superdoc-mcp/superdoc-open.md
- `superdoc_save` — Write — https://policylayer.com/tools/superdoc-mcp/superdoc-save.md

## For agents

This record is a snapshot. Live verdicts and the full registry:

- Check every server in your MCP config at once: `npx -y policylayer stack`
- Vet a server before you add it: install the mcp-precheck skill — `npx skills add https://policylayer.com` (skill text: https://policylayer.com/skill.md)
- Query the registry over MCP: endpoint `https://api.policylayer.com/mcp` — tools `check_mcp_server`, `check_mcp_stack`, `check_tool`, `search_registry`, `get_change_events`

---

Source: the PolicyLayer MCP registry — one continuously verified record per MCP server. Full record: https://policylayer.com/registry?q=superdoc-mcp · API: https://policylayer.com/registry/api · Policy library: https://policylayer.com/policies/superdoc-mcp