Droost

What it is

Droost is a local development toolkit that lets an AI coding agent ask your Drupal site about itself, and then build on it deterministically.

It is the Drupal analog of Laravel Boost. Agents writing Drupal code normally work blind: they do not know which modules and versions are installed, what entity types and fields exist, which service to inject instead of calling \Drupal::, or whether the last request errored. So they guess, and their guesses age badly.

The usual workaround is to have the agent shell out to Drush and parse the text. Droost exposes the same information as schema-described MCP tools returning structured JSON — reliable, version-correct answers about the real site, with each capability individually gateable instead of hidden behind a shell.

Built entirely on MCP Server and the official mcp/sdk: MCP Server provides the runtime and the #[Tool] plugin system, Droost provides the tools.

⚠️ Local development only

Droost is in the same class as devel, devel_php and webprofiler. It deliberately exposes your application, can run raw SQL, and — when you opt in — arbitrary PHP.

composer require --dev 'drupal/droost:^2.0@alpha' 'drupal/mcp_server:^2.0@alpha'

Enable it on local and trusted development environments only. The gates described below reduce footguns; they are not a security boundary against an untrusted caller. Running Droost on a production or internet-reachable site means accepting that.

Two minutes to a wired agent

composer require --dev 'drupal/droost:^2.0@alpha' 'drupal/mcp_server:^2.0@alpha'
drush en droost -y
drush droost:install --harness=claude    # or codex, gemini, qwen, opencode, all

droost:install registers the MCP server and writes an AGENTS.md block pointing your agent at this site. It is reversible. (If Composer refuses on an mcp/sdk security advisory, KNOWN_LIMITATIONS.md #6 has the one-command workaround until the next mcp_server release.)

Then ask your agent: "Ask Droost what this site knows about itself."

Or let the agent drive the setup: droost:install also ships three guided slash commands — /droost-init (first wiring, knowledge layer, verification), /droost-configure (profiles, write gates, embedding backend, workflow levers, each shown before and after) and /droost-upgrade (walks the shipped upgrade bulletins in order, confirming every irreversible step).

A work pipeline, not just tools

Droost also installs the Droost Workflow pack (droost/workflow, a framework-free PHP library): /droost-work walks every change through plan → code → test → document → complete, gated by real quality tools.

• Levers live in one repo-root file, droost.workflow.yml — a file rather than Drupal config on purpose, so the agent can read it while the site is mid-build, the CLI reads it with no site at all, and loosening a gate shows up in review as a diff. droost:install writes it measured to your layout.
• Presets factory (everything, strict, full EARS spec), light (same phases, lighter artifacts), custom (spelled out per gate) — plus your own commands as first-class gates (semgrep, behat, anything that exits zero).
• enforcement: hard | soft | off — harness hooks hold the phase discipline while a run is active, and are silent outside one.
• The reports never round up: a gate that could not run is recorded skipped with its reason, never as passed — "nothing failed" and "three things were never checked" are different sentences.

What the tools cover

Know the site — droost_app_info, droost_entities, droost_routes, droost_services, droost_permissions, droost_config_*, droost_db_schema, droost_logs, droost_last_error. Give droost_services an id and it answers the question that actually blocks an agent mid-edit: which interface do I type-hint to autowire this, and what did it used to be called?

Know the codebase — droost_search (lexical, symbol and semantic), droost_symbol and droost_graph over a real code graph — who calls this, what depends on that module. Semantic search runs on a local embedding backend; no paid API.

Know the project — droost_capabilities, droost_architecture, droost_module_patterns, droost_guidelines — a per-project knowledge layer that answers "how does this codebase do things", seeded on install and rebuilt from the code.

Build — droost_scaffold generates 22 kinds of Drupal construct — plugins, services, forms, entities, SDCs, hooks, Drush commands, recipes, MCP tools, and more — and they come out green against phpcs and PHPStan at level max, because that is gated in CI on the generated output, not just the module. droost_structure_create and the entity/config write tools build the content model. droost_display_compose writes Manage Display config from Single Directory Components via UI Patterns 2. droost_views_compose builds views from an intent spec, validated through Views itself before anything is saved. droost_canvas_tree_set writes Canvas page trees.

Verify — droost_verify runs phpcs, PHPStan and the test suite. droost_doctor is the first thing to run when something is confusing: it reports which write gates are armed, whether semantic search can actually work, whether Canvas and UI Patterns can coexist on this site, and which project recipes would fail to apply.

Writes are disarmed by default

Reads run freely. Every write is gated behind an explicit flag, by category — allow_scaffold, allow_entity_write, allow_db_write, allow_config_write, allow_module_ops, allow_eval — so you can let an agent scaffold code without also arming DELETE against real content. Flags live at /admin/config/development/droost.

A refused write is the gate working. droost_doctor names which categories are currently armed, so "why did that refuse?" is one call, not a hunt.

Context economy

64 tools is more than most agents should carry. Droost registers a profile:

• lean — 21 tools: read and understand, no writes.
• standard (default) — 46 tools: everything most sessions need, and it fits in one tools/list page.
• full — all 64.

Sibling projects can declare which profile their own droost_-prefixed tools belong in, via hook_droost_tool_profile_info().

Optional submodules

droost_display (SDC-driven Manage Display), droost_canvas (Canvas page trees), droost_views (view composition), droost_examples (a green reference corpus), droost_ai (bridge to drupal/ai), droost_devel. Core carries the brain, search, the wiki and the methodology guidance; the rest is opt-in.

Requirements

Drupal 11.1+ or 12; PHP 8.3+; drupal/mcp_server. Semantic search additionally wants a local embedding backend (Ollama and anything OpenAI-compatible both work). Canvas and UI Patterns are needed only by the submodules that orchestrate them — and they can run together: droost_canvas bridges the upstream Canvas/decorator conflict (#3561618) from its own service provider while enabled, standing down automatically once Canvas ships the fix, and drush droost:doctor's coexistence check reports the pair's live state either way.

Upgrading from 1.x

Uninstall the seven merged modules before you pull 2.x — required, not advised. Their code moved into droost core, and a site that updates with them still installed will not boot: a module left in core.extension with no directory on disk breaks bootstrap before any repair hook can run.

# On 1.x, while the modules still exist:
drush pm:uninstall droost_search droost_wiki droost_brain droost_profiler \
  droost_knowledge droost_help droost_playbook

# Then move to 2.x:
composer require --dev 'drupal/droost:^2.0@alpha' 'drupal/mcp_server:^2.0@alpha'
drush updb && drush cr

# Rebuild what uninstalling discarded:
drush droost:search:index
drush droost:brain:build

Every tool id, drush command, database table, State key and config object survives the move unchanged — nothing an agent or a script calls needs editing. If you already pulled 2.x with the modules installed, the 2.x release notes carry the recovery runbook. /droost-upgrade walks all of this interactively from the shipped bulletins.

Where to look next

• README — the full tool inventory and the gating model.
• QUICKSTART — the two-minute path, expanded.
• docs/demos/ — four recorded builds, including the acid test: a context-free agent given nothing but a mockup, a two-sentence brief and a wire script, building a themed three-page site through the tool surface alone. That one is the honest demo — it includes what went wrong and what got fixed because of it.
• KNOWN_LIMITATIONS.md — what does not work, and why.