# superdoc_edit

The primary tool for inserting content into documents. ALWAYS use action "insert" with type "markdown" to create headings, paragraphs, or any block content: this is faster and creates proper document structure in one call. Do NOT use superdoc_create for headings or paragraphs. The markdown parser creates headings from # markers (# = Heading1, ## = Heading2), bold from text, italic from *text*, and numbered/bullet lists. Position markdown inserts with "target" (a BlockNodeAddress like {kind:"block", nodeType, nodeId}) and "placement" (before, after, insideStart, insideEnd). Without a target, content appends at the end of the document. IMPORTANT: After a markdown insert, analyze the document context (what kind of document, how titles and body text are styled) and follow up with ONE superdoc_mutations call to format inserted blocks so they look like they belong. Each format.apply step accepts "inline" (fontFamily, fontSize, bold, underline, color), "alignment", and "scope" in the same step. Use scope: "block" so formatting covers the entire paragraph. Copy the exact property values from the existing get_content blocks (fontFamily, fontSize, color, alignment, bold, underline). Do NOT invent values: use what the blocks show. Also supports replace, delete, and undo/redo. For ordinary replace and delete, pass a "ref" from superdoc_search or superdoc_get_content blocks. Action "delete" removes a text range and leaves the block container in place. To remove a whole paragraph, heading, list item, or table, use action "delete_block" with target:{kind:"block", nodeType, nodeId} from superdoc_get_content action "blocks", or action "delete_block_range" with "start" and "end" block addresses to remove a contiguous span of top-level blocks (inclusive). A search ref covers only the matched substring; a block ref covers the entire block text, so use block refs when rewriting or shortening whole paragraphs. To replace every block in the main body, use action "replace" with target:{kind:"story",storyType:"body"}, one text/value/content payload, and changeMode:"direct". This replaces body content, not the DOCX package, and does not require a search first. Tracked whole-body replacement is unsupported. For multi-step redlines or whole-clause rewrites, prefer superdoc_mutations with where:{by:"block", nodeType, nodeId} from superdoc_get_content action "blocks" includeText:true rather than relying on text selectors. Refs expire after any mutation; always re-search before the next edit. For 2+ edits that must succeed or fail atomically, use superdoc_mutations instead. Before an exact HTML or Markdown insert/replace that must be fidelity-checked, use action "check_support", review its outcome and diagnostics, then pass its guard back as "supportCheck" on the unchanged write. Supports "dryRun" to preview changes and "changeMode: tracked" to record edits as tracked changes. Do NOT build "target" objects manually when a ref is available; prefer "ref" for simpler, more reliable targeting. EXAMPLES: 1. {"action":"insert","type":"markdown","target":{"kind":"block","nodeType":"paragraph","nodeId":"<nodeId>"},"placement":"before","value":"# Executive Summary\n\nThis agreement sets forth the principal terms...","changeMode":"direct"} 2. {"action":"insert","type":"html","value":"<h2>Review heading</h2><p>Tracked rich content.</p>","changeMode":"tracked"} 3. {"action":"insert","type":"markdown","value":"# Section Title\n\nParagraph content here.\n\n# Another Section\n\nMore content with bold and *italic*."} 4. {"action":"replace","ref":"<handle.ref>","text":"new text here"} 5. {"action":"replace","ref":"<handle.ref>","value":"Direct rich replacement","type":"markdown","changeMode":"direct"} 6. {"action":"replace","ref":"<handle.ref>","value":"<strong>Tracked rich replacement</strong>","type":"html","changeMode":"tracked"} 7. {"action":"check_support","operation":"insert","input":{"type":"markdown","value":"# Checked section"},"options":{"changeMode":"direct"}} 8. {"action":"replace","target":{"kind":"story","storyType":"body"},"value":"# Replacement\n\nComplete new body.","type":"markdown","changeMode":"direct"} 9. {"action":"delete","ref":"<handle.ref>"} 10. {"action":"delete_block","target":{"kind":"block","nodeType":"heading","nodeId":"<nodeId>"}} 11. {"action":"undo"}

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

## Facts

- Tool: `superdoc_edit`
- 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: Write (Medium risk)
- Registry record: grade F, identity unverified
- Server rate-limited: no
- Parameters: 12 (1 required)
- Recommended policy verdict: Rate-limited

## 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 |
| `end` | object | no | Required for action 'delete_block_range'. |
| `ref` | object | no | Handle ref from superdoc_search result (pass handle.ref value directly). Preferred over building a target object. Only for actions 'insert', 'replace', 'delete' |
| `text` | string | no | Complete replacement text for the main body. Only for action 'replace'. Omit for other actions. |
| `type` | object | no | Only for actions 'insert', 'replace'. Omit for other actions. |
| `force` | boolean | no | Bypass confirmation checks. |
| `input` | object | no | Only for action 'check_support'. Omit for other actions. |
| `start` | object | no | Required for action 'delete_block_range'. |
| `value` | object | no | HTML or Markdown content to convert and insert. Only for actions 'insert', 'replace'. Omit for other actions. |
| `action` | string | yes | The action to perform. One of: check_support, delete, delete_block, delete_block_range, insert, redo, replace, undo. |
| `dryRun` | boolean | no | Preview the result without applying changes. |
| `target` | object | no | Block address for structural insertion: {kind:'block', nodeType:'...', nodeId:'...'}. Required for action 'delete_block'. |

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_edit",
    "arguments": {
      "action": "<action>"
    }
  }
}
```

## Why superdoc_edit is rated Medium

An AI agent can call superdoc_edit faster than any human can review: one bad instruction and it creates or modifies resources in Superdoc by the hundred, each call as confident as the last.

Risk signals: Accepts raw HTML/template content (content) · High parameter count (36 properties) · Bulk/mass operation — affects multiple targets

## Use case

AI agents use superdoc_edit to create or update resources in Superdoc, usually the action step of a workflow, after the agent has gathered context. Every call changes real data in your Superdoc environment.

## Recommended policy (PolicyLayer)

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

```json
{
  "version": "1",
  "default": "deny",
  "tools": {
    "superdoc_edit": {
      "limits": [
        {
          "counter": "superdoc_edit_rate",
          "window": "minute",
          "max": 30,
          "scope": "grant"
        }
      ]
    }
  }
}
```

## Other tools on Superdoc (12)

- `superdoc_mutations` — Destructive — https://policylayer.com/tools/superdoc-mcp/superdoc-mutations.md
- `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_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