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            # wires .mcp.json, AGENTS.md, CLAUDE.md, .claude/ by itself
drush droost:install          # the TOOLSET path: submodules, write gates, the knowledge layer
drush droost:workflow:install # the PIPELINE path: levers, gates, the pack, the wall

The install is two paths. droost:install enables every submodule whose backend is present, asks which editor you use (auto-detected) and whether to arm allow_scaffold — explaining what a write gate is before it asks — and builds the knowledge layer. droost:workflow:install is the separate, deliberate step that installs the Droost Workflow described below. Both are reversible; drush droost:setup:status reports where a site stands on either. (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."

The Droost Workflow: a governed pipeline, not just tools

Tools that can build are only half of it; the other half is making sure an agent builds the way a good Drupal team would. That is the Droost Workflow — droost/workflow on Packagist, developed at github.com/Ignibyte/droost-workflow, a framework-free PHP library that drush droost:workflow:install wires into your project. Every build runs through it: /droost:workflow:start opens a run, /droost:workflow:continue advances it one phase at a time — plan → code → test → complete — and /droost:workflow:status tells you where things stand.

• A spec first, enforced. The plan phase produces a spec with EARS acceptance criteria and a Tooling plan that maps every construct to the surface that builds it; the engine refuses to enter code without one, and refuses to complete without a Realized capture of what was actually built.
• Real gates, never rounded up. phpcs, PHPStan and phpunit are mandatory; config_clean byte-compares active configuration against your tracked export; rendered_check renders the site. A gate that could not run is recorded skipped with its reason, never as passed.
• An adversarial reviewer the run cannot talk past. The seeker checkpoint dispatches an independent inspection of the cumulative diff; its ledger is parsed, never self-reported, and the whole inspection arc — not just the last verdict — stays in the permanent record.
• The behavior change to read first: the wall. With the pipeline installed, a require_run wall (default hard) blocks ungoverned custom-code edits and droost's own build tools while no run is active. The block names the two ways forward: start a run, or an operator-granted bypass.
• Droost directs the routing. droost_decide walks shipped decision graphs server-side — which surface builds a permissions file? — consulting gate state and this site's drush generate list live. Droost extends Drush, it never competes with it: the answer is the exact command, and hand-writing is allowed only with the map's own reason.
• Operator controls, scoped. Levers live in one repo-root file, droost.workflow.yml — written measured to your layout, a file rather than config so the agent can read it mid-build and a loosened gate shows up in review as a diff. drush droost:workflow:gate-waive <gate> "<reason>" waives one gate for one run, reasoned and recorded, and is deliberately CLI-only: an agent can never waive its own gates.

How well does it hold? It was validated by eleven consecutive accepted live-agent rounds on registry installs — features from content models and Views to batch backfills, kernel-event redirects, config migrations, queue workers and editorial moderation — each judged by a functional acceptance script written before the run, with zero product failures across the final six. The graded record ships in the repository under scripts/evals/.

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

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

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

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

Optional submodules

droost_workflow (the pipeline bridge — installed by droost:workflow:install), droost_ui_patterns (SDC-driven Manage Display via UI Patterns 2), droost_canvas (Canvas page trees), droost_examples (a green reference corpus), droost_ai (bridge to drupal/ai), droost_devel. Core carries view composition, the brain, search, the codebase wiki (kept at droost/wiki, out of your own docs/, and configurable) 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.

⚠️ No upgrade path from 1.x

1.x is not supported as an upgrade source. 2.x is a re-architecture — seven 1.x modules merged into core, the install became two paths, the workflow became the default — and it ships no upgrade hooks for 1.x sites. The safe route is a clean cut: uninstall every droost module while its 1.x code still exists, remove the package, then install 2.x as a new module.

# Still on 1.x — uninstall while the code exists:
drush pm:uninstall droost      # plus any droost_* submodule you enabled
composer remove drupal/droost

# Then install 2.x fresh:
composer require --dev 'drupal/droost:^2.0@alpha' 'drupal/mcp_server:^2.0@alpha'
drush en droost -y && drush droost:install

Uninstalling first is required, not advised: a merged module left in core.extension with no directory on disk breaks bootstrap before any repair could run. What you lose rebuilds cheaply — the brain and search indexes regenerate from your code (drush droost:brain:build, drush droost:search:index), and a wiki bundle is plain files that survive on disk.

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.
• Droost Workflow — the library's own repository: the phase skills, the gate model, and the pack that gets materialized into your project.
• scripts/evals/RESULTS.md — every graded live-agent round, including what went wrong and what got fixed because of it.