>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3630858. --> Reported by: [marcofernandes](https://www.drupal.org/user/2127558) Related to !297 >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>Site builders increasingly want to work on content from an AI assistant such as Claude or ChatGPT: "draft a landing page from this brief", "add a FAQ section to the pricing page". Drupal already has what connects these assistants to a site:</p> <ul> <li><a href="https://www.drupal.org/project/tool">Tool API</a> defines typed, access-checked tools.</li> <li><a href="https://www.drupal.org/project/mcp_server">MCP Server</a> exposes them over the Model Context Protocol: STDIO via Drush for Claude Desktop/Code, and HTTP at <code>/mcp</code> with OAuth for remote connectors.</li> </ul> <p>What's missing is a set of tools that understand Gutenberg content. A generic "update the body field" tool doesn't work well because of three things specific to Gutenberg:</p> <ol> <li><strong>Block validation.</strong> On load, the editor regenerates each block's HTML with the block's JavaScript <code>save()</code>. When the stored HTML differs, the block is marked invalid. PHP can't produce that HTML, so the assistant has to write it exactly.</li> <li><strong>Each content type allows different blocks.</strong> Allowed blocks, SDC components, field blocks, the entity title block, templates and their locks, and mapped fields all vary by content type, and the assistant can't see any of this.</li> <li><strong>Content location.</strong> The content goes in the content type's Gutenberg text field, with the <code>gutenberg</code> text format.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>Add an <strong>experimental</strong> submodule, <code>gutenberg_tools</code>, that provides Tool API plugins. It doesn't depend on MCP Server. MCP Server exposes the tools to assistants, and AI Agents and ECA can use the same tools.</p> <p>The submodule is flagged <code>lifecycle: experimental</code>, because Tool API (1.0.0-beta) and MCP Server (2.0.0-beta) aren't stable yet. Tool names, inputs and outputs may change until they are.</p> <h4>Tools</h4> <table> <thead> <tr> <th>Tool</th> <th>Purpose</th> </tr> </thead> <tbody> <tr> <td><code>gutenberg_content_types</code></td> <td>Gutenberg-enabled content types, with their text field, template, lock and title options</td> </tr> <tr> <td><code>gutenberg_block_catalog</code></td> <td>The blocks a content type allows: attributes, supports, SDC props/slots/variants, placeable fields, theme presets</td> </tr> <tr> <td><code>gutenberg_markup_guide</code></td> <td>Exact markup examples for the allowed core and Drupal blocks, so the assistant writes HTML the editor accepts</td> </tr> <tr> <td><code>gutenberg_get_page</code></td> <td>A node's content as a block tree with block paths, plus the raw markup</td> </tr> <tr> <td><code>gutenberg_validate</code></td> <td>Checks markup: unknown or disallowed blocks, attribute types and enums, parent rules, template lock, mapped title</td> </tr> <tr> <td><code>gutenberg_create_page</code></td> <td>Creates a node from validated markup (unpublished by default)</td> </tr> <tr> <td><code>gutenberg_update_page</code></td> <td>Replaces the content, or edits single blocks (replace/insert/remove/move at a block path), saved as a new revision with a log message</td> </tr> <tr> <td><code>gutenberg_preview</code></td> <td>Rendered frontend HTML of a node or of unsaved markup</td> </tr> </tbody> </table> <p>Access requires a new <code>use gutenberg tools</code> permission plus node access, and the assistant acts as the authenticated user.</p> <h4>Changes to the main module</h4> <ul> <li>A PHP block serializer next to <code>BlockParser</code>: a port of WordPress <code>serialize_block()</code>/<code>serialize_blocks()</code>.</li> <li>A public helper that returns the allowed blocks of a content type. It is extracted from <code>Plugin/Editor/Gutenberg::getJsSettings()</code>, so the editor and the tools share it.</li> <li>A PHP block validator built on <code>TemplateManager::getCatalog()</code>: the server-side counterpart of the template editor's <code>lintTemplate()</code>.</li> </ul> <p><strong>Out of scope for now:</strong> fixing invalid blocks automatically in the editor, and running the JS serializer in Node on the server.</p> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Block serializer and round-trip tests against the parser</li> <li>Allowed blocks helper, used by the editor plugin</li> <li>Block validator</li> <li><code>gutenberg_tools</code> submodule and its tools</li> <li>Markup guide, with a Playwright test that opens every example in the editor and expects no invalid blocks (this catches <code>save()</code> changes on Gutenberg upgrades)</li> <li>README: setup with MCP Server for Claude Code and Desktop (local) and for claude.ai and ChatGPT connectors (OAuth, Drupal 11)</li> <li>Check whether MCP Server OAuth supports the dynamic client registration that remote connectors use</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None in the editor. The new permission is "Use Gutenberg tools".</p> <h3 id="summary-api-changes">API changes</h3> <p>New: a block serializer, a block validator and an allowed-blocks helper. The submodule adds the Tool API plugins.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>None.</p>