instruckt_drupal

Instruckt adds a click-to-annotate visual feedback toolbar to your Drupal site's front end and exposes those annotations to AI coding agents via the MCP module. Developers, designers, and reviewers can click any element on a live page, attach a comment, intent (fix / change / question / approve), and optional screenshot — then an AI agent in their editor reads the pending feedback and acts on it without any copy-pasting or context switching.

Features

• Click any element on a front-end page to create an annotation — no markup changes required
• Attach a free-text comment, an intent (fix / change / question / approve), and a severity level
• Capture a cropped screenshot of the annotated element for visual context
• Automatic Twig template detection: when Twig debug mode is enabled, annotations include the template name and file path that rendered the element
• Three MCP tools exposed to AI agents: instrucktdrupal_get_all_pending, instrucktdrupal_get_screenshot, instrucktdrupal_resolve
• Works with Claude Code, Cursor, and any MCP-compatible AI agent
• Annotations stored in the Drupal private filesystem — never publicly accessible
• Permission-gated toolbar: only users with access instruckt_drupal toolbar see it
• Ships with a drush instruckt:setup command that configures private files, MCP auth, and prints a ready-to-use .mcp.json snippet

Post-Installation

The fastest path is three commands:

composer require drupal/instruckt_drupal
drush en mcp instruckt_drupal && drush cr
drush instruckt:setup

drush instruckt:setup handles the full configuration in one step: it creates a private directory outside the web root, writes the $settings['file_private_path'] line to settings.php, creates annotation storage directories, grants use mcp server to the role of your choice, generates an authentication token key, and prints the .mcp.json snippet to paste into your editor.

Once setup is complete, navigate to any non-admin page while logged in — the Instruckt toolbar appears in the bottom-right corner. Click the toolbar icon, click an element, fill in your feedback, and submit. Your AI agent can immediately retrieve it via MCP.

Module settings (enable/disable toolbar, storage path, screenshot size limits) are available at /admin/config/development/instruckt.

Additional Requirements

• Drupal 10.3 or 11
• PHP 8.1+
• drupal/mcp ^1.2 — provides the MCP server endpoint that AI agents connect to
• An AI coding agent that supports MCP (Claude Code, Cursor, or any client with HTTP/Streamable HTTP transport)

The toolbar JavaScript loads from jsDelivr CDN by default (zero extra setup). For production environments or strict Content Security Policies, it can be installed locally via Composer and Asset Packagist — see the README for details.

Similar projects

This module was inspired by the instruckt JavaScript library and instruckt-laravel package, which provide the same concept for Laravel applications. All credit for the original UI and JavaScript implementation goes to the instruckt project contributors.

Comments and similar annotation modules focus on content-level feedback visible to site visitors. Instruckt is strictly a developer/reviewer tool: annotations are private, never displayed to end users, and designed to be consumed programmatically by an AI agent rather than manually reviewed in a Drupal UI.

Community Documentation

Full documentation, including MCP client configuration examples for Claude Code and Cursor, DDEV TLS troubleshooting, and manual MCP auth setup, is in the README file.