Problem/Motivation

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:

  • Tool API defines typed, access-checked tools.
  • MCP Server exposes them over the Model Context Protocol: STDIO via Drush for Claude Desktop/Code, and HTTP at /mcp with OAuth for remote connectors.

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:

  1. Block validation. On load, the editor regenerates each block's HTML with the block's JavaScript save(). When the stored HTML differs, the block is marked invalid. PHP can't produce that HTML, so the assistant has to write it exactly.
  2. Each content type allows different blocks. 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.
  3. Content location. The content goes in the content type's Gutenberg text field, with the gutenberg text format.

Proposed resolution

Add an experimental submodule, gutenberg_tools, 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.

The submodule is flagged lifecycle: experimental, 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.

Tools

Tool Purpose
gutenberg_content_types Gutenberg-enabled content types, with their text field, template, lock and title options
gutenberg_block_catalog The blocks a content type allows: attributes, supports, SDC props/slots/variants, placeable fields, theme presets
gutenberg_markup_guide Exact markup examples for the allowed core and Drupal blocks, so the assistant writes HTML the editor accepts
gutenberg_get_page A node's content as a block tree with block paths, plus the raw markup
gutenberg_validate Checks markup: unknown or disallowed blocks, attribute types and enums, parent rules, template lock, mapped title
gutenberg_create_page Creates a node from validated markup (unpublished by default)
gutenberg_update_page Replaces the content, or edits single blocks (replace/insert/remove/move at a block path), saved as a new revision with a log message
gutenberg_preview Rendered frontend HTML of a node or of unsaved markup

Access requires a new use gutenberg tools permission plus node access, and the assistant acts as the authenticated user.

Changes to the main module

  • A PHP block serializer next to BlockParser: a port of WordPress serialize_block()/serialize_blocks().
  • A public helper that returns the allowed blocks of a content type. It is extracted from Plugin/Editor/Gutenberg::getJsSettings(), so the editor and the tools share it.
  • A PHP block validator built on TemplateManager::getCatalog(): the server-side counterpart of the template editor's lintTemplate().

Out of scope for now: fixing invalid blocks automatically in the editor, and running the JS serializer in Node on the server.

Remaining tasks

  • Block serializer and round-trip tests against the parser
  • Allowed blocks helper, used by the editor plugin
  • Block validator
  • gutenberg_tools submodule and its tools
  • Markup guide, with a Playwright test that opens every example in the editor and expects no invalid blocks (this catches save() changes on Gutenberg upgrades)
  • README: setup with MCP Server for Claude Code and Desktop (local) and for claude.ai and ChatGPT connectors (OAuth, Drupal 11)
  • Check whether MCP Server OAuth supports the dynamic client registration that remote connectors use

User interface changes

None in the editor. The new permission is "Use Gutenberg tools".

API changes

New: a block serializer, a block validator and an allowed-blocks helper. The submodule adds the Tool API plugins.

Data model changes

None.

Issue fork gutenberg-3630858

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

About issue forks

Comments

marcofernandes created an issue. See original summary.

marcofernandes opened merge request !297

marcofernandes’s picture

marcofernandes commented
Status: Active » Needs review