feat(mcp): expose blocks.delete/deleteRange via superdoc_edit

Wire the existing document-api blocks.delete / blocks.deleteRange ops
into the MCP tool surface as superdoc_edit actions delete_block and
delete_block_range, so clients can remove an entire block node, not
just its text content. Deleting a heading/paragraph's text previously
left an empty container behind, still rendering as block spacing.

Regenerates the MCP catalog and intent-dispatch (Node, browser,
Python) and adds end-to-end protocol tests proving physical block
removal (block-count decrement + nodeId absence).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: 2 people

apps/mcp/src/__tests__/protocol.test.ts

@@ -203,4 +203,153 @@ describe('MCP protocol integration', () => {
     const body = JSON.parse(textContent(result));
     expect(body).toHaveProperty('session_id');
   });
+
+  // ---------------------------------------------------------------------------
+  // Block-node deletion via superdoc_edit (delete_block / delete_block_range)
+  //
+  // These tests prove the *reported bug* is fixed end-to-end through the MCP
+  // layer: a text `delete` (by ref) empties a block but leaves the container
+  // behind, whereas `delete_block` (by {kind:'block', nodeType, nodeId} target)
+  // physically removes the whole block node.
+  //
+  // Addressing model (must be respected or the test fails):
+  //   - get_content action:"blocks" returns { total, blocks: [...], revision };
+  //     each entry exposes BOTH a `nodeId` and a `ref`.
+  //   - text `delete` takes a `ref`.
+  //   - `delete_block` takes `target: {kind:'block', nodeType, nodeId}`.
+  //   - refs and block handles EXPIRE after ANY mutation; we re-fetch blocks
+  //     before every call that consumes a handle.
+  // ---------------------------------------------------------------------------
+
+  interface BlockEntry {
+    nodeId: string;
+    nodeType: string;
+    isEmpty: boolean;
+    ref?: string;
+    textPreview: string | null;
+  }
+
+  interface BlocksPayload {
+    total: number;
+    blocks: BlockEntry[];
+    revision: string;
+  }
+
+  // Always re-fetch — never cache a handle across a mutation.
+  async function fetchBlocks(sid: string): Promise<BlocksPayload> {
+    const result = await client.callTool({
+      name: 'superdoc_get_content',
+      arguments: { session_id: sid, action: 'blocks' },
+    });
+    return parseContent(result) as BlocksPayload;
+  }
+
+  it('exposes delete_block and delete_block_range in the superdoc_edit action enum', async () => {
+    await ready;
+    const { tools } = await client.listTools();
+
+    const editTool = tools.find((t) => t.name === 'superdoc_edit');
+    expect(editTool).toBeDefined();
+
+    const schema = editTool!.inputSchema as { properties?: Record<string, { enum?: string[] }> };
+    const actionEnum = schema.properties?.action?.enum;
+    expect(actionEnum).toBeArray();
+    expect(actionEnum).toContain('delete_block');
+    expect(actionEnum).toContain('delete_block_range');
+  });
+
+  it('delete_block physically removes a block node (count decrements, nodeId absent)', async () => {
+    await ready;
+
+    // Open a blank document.
+    const openResult = await client.callTool({ name: 'superdoc_open', arguments: { path: BLANK_DOCX } });
+    const { session_id: sid } = parseContent(openResult) as { session_id: string };
+
+    // Create a heading and a paragraph (proven create workflow).
+    const headingResult = await client.callTool({
+      name: 'superdoc_create',
+      arguments: { session_id: sid, action: 'heading', text: 'Block To Delete', level: 1 },
+    });
+    expect(textContent(headingResult)).toBeTruthy();
+
+    const paraResult = await client.callTool({
+      name: 'superdoc_create',
+      arguments: { session_id: sid, action: 'paragraph', text: 'Surviving paragraph' },
+    });
+    expect(textContent(paraResult)).toBeTruthy();
+
+    // Record block count N and the heading's nodeId from the authoritative listing.
+    const before = await fetchBlocks(sid);
+    const heading = before.blocks.find((b) => b.nodeType === 'heading');
+    expect(heading).toBeDefined();
+    const headingNodeId = heading!.nodeId;
+    const countBefore = before.blocks.length;
+    expect(countBefore).toBeGreaterThan(1);
+
+    // Delete the entire heading block by its target address.
+    const deleteResult = await client.callTool({
+      name: 'superdoc_edit',
+      arguments: {
+        session_id: sid,
+        action: 'delete_block',
+        target: { kind: 'block', nodeType: 'heading', nodeId: headingNodeId },
+      },
+    });
+    expect(deleteResult).not.toHaveProperty('isError');
+
+    // Re-fetch (handles expired) and assert PHYSICAL removal.
+    const after = await fetchBlocks(sid);
+    expect(after.blocks.length).toBe(countBefore - 1);
+    expect(after.blocks.some((b) => b.nodeId === headingNodeId)).toBe(false);
+
+    await client.callTool({ name: 'superdoc_close', arguments: { session_id: sid } });
+  });
+
+  it('text delete leaves an empty container; delete_block removes it (the reported bug)', async () => {
+    await ready;
+
+    // Open a blank document and create a heading to operate on.
+    const openResult = await client.callTool({ name: 'superdoc_open', arguments: { path: BLANK_DOCX } });
+    const { session_id: sid } = parseContent(openResult) as { session_id: string };
+
+    await client.callTool({
+      name: 'superdoc_create',
+      arguments: { session_id: sid, action: 'heading', text: 'Heading body text', level: 1 },
+    });
+
+    // Locate the heading; capture its nodeId AND its fresh ref.
+    const before = await fetchBlocks(sid);
+    const heading = before.blocks.find((b) => b.nodeType === 'heading');
+    expect(heading).toBeDefined();
+    const headingNodeId = heading!.nodeId;
+    expect(heading!.ref).toBeString();
+
+    // 1) Text `delete` by ref: empties the block but leaves the container.
+    const textDelete = await client.callTool({
+      name: 'superdoc_edit',
+      arguments: { session_id: sid, action: 'delete', ref: heading!.ref },
+    });
+    expect(textDelete).not.toHaveProperty('isError');
+
+    const afterTextDelete = await fetchBlocks(sid);
+    const survivor = afterTextDelete.blocks.find((b) => b.nodeId === headingNodeId);
+    expect(survivor).toBeDefined(); // container survives — this is the bug
+    expect(survivor!.isEmpty).toBe(true);
+
+    // 2) delete_block by target: physically removes the container.
+    const blockDelete = await client.callTool({
+      name: 'superdoc_edit',
+      arguments: {
+        session_id: sid,
+        action: 'delete_block',
+        target: { kind: 'block', nodeType: 'heading', nodeId: headingNodeId },
+      },
+    });
+    expect(blockDelete).not.toHaveProperty('isError');
+
+    const afterBlockDelete = await fetchBlocks(sid);
+    expect(afterBlockDelete.blocks.some((b) => b.nodeId === headingNodeId)).toBe(false);
+
+    await client.callTool({ name: 'superdoc_close', arguments: { session_id: sid } });
+  });
 });