Droost

Droost gives AI coding agents structured, first-hand knowledge of this Drupal application. It is the Drupal analog of Laravel Boost: a developer-acceleration toolkit that exposes the application and codebase itself - versions, the entity and configuration model, routes, services, logs, database schema, and a set of guarded operations - as Model Context Protocol (MCP) tools.

It is built entirely on MCP Server and the official mcp/sdk: MCP Server provides the runtime and the #[Tool] plugin system; Droost provides the tools.

The problem it solves

An AI agent asked to write Drupal code is usually working blind. It does not know which modules and versions are installed, what entity types and fields exist, which services it should inject instead of calling \Drupal::, what the routes and permissions are, or whether the last request errored. It guesses - and guesses age badly as a project evolves.

The common workaround is to tell the agent to run Drush and parse the free-text output. Droost takes a different path: it exposes that information as explicit, schema-described tools that return structured JSON. The agent gets reliable, version-correct answers about the real site, and capabilities become discoverable and individually gateable rather than hidden behind a shell.

Features

• 22 MCP tools spanning read-only introspection and guarded operations, each returning a uniform {success, message, data} envelope.
• Read-only by default. State-changing tools are registered so an agent can discover them, but refuse to act until explicitly opted in.
• A real security model (see below): per-flag gating, secret redaction in config reads, and a read-only SQL guard.
• Bundled, version-stamped guidelines - composable Drupal conventions plus on-demand deep-dive topics, served over MCP and writable to AGENTS.md.
• On-disk documentation search across core, contrib, and custom modules, so answers match the exact versions installed.
• One-command adoption with drush droost:install (auto-detects DDEV).

Requirements

• Drupal 10.3+ or 11; PHP 8.3+.
• MCP Server (drupal/mcp_server) ^2.0@alpha - provides the MCP runtime and the drush mcp:server command.
• Drush 12+ - Droost is served over STDIO by Drush and ships the droost:install command.
• The core Database Logging (dblog) module - optional; only the droost_logs and droost_last_error tools depend on it, and they degrade gracefully when it is absent.

Installation

Install with Composer (recommended) so the MCP Server dependency is resolved:

composer require drupal/droost
drush en droost -y

Note: MCP Server is currently an alpha release, so a site on the default stable minimum-stability cannot resolve it without opting in. Either require the dependency explicitly first:

composer require drupal/mcp_server:^2.0@alpha
composer require drupal/droost

or set "minimum-stability": "alpha" with "prefer-stable": true in your root composer.json before requiring Droost.

Usage

1. Wire up your editor

drush droost:install

droost:install (alias droost) registers the Droost MCP server in the project's .mcp.json, writes the bundled guidelines to AGENTS.md, and prints ready-to-paste registration commands for common clients. It auto-detects DDEV and, in that case, uses ddev drush mcp:server as the launch command.

Options:

The command prints per-editor hints, for example:

Claude Code:  claude mcp add -s local -t stdio droost ddev drush mcp:server
Gemini CLI:   gemini mcp add -s project -t stdio droost ddev drush mcp:server
Codex:        codex mcp add droost -- ddev drush mcp:server

2. Serve the tools

MCP Server serves Droost's enabled tools over STDIO with drush mcp:server (run as ddev drush mcp:server under DDEV); your editor launches this and speaks JSON-RPC to it. After enabling or adding tools, rebuild caches and reload MCP servers in your editor:

drush cache:rebuild

A quick manual handshake, list, and call check:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | drush mcp:server

Configuration

Droost ships read-only. State-changing tools are gated by two boolean flags in droost.settings, both off by default. Configure them at Admin > Configuration > Development > Droost (/admin/config/development/droost, requires the Administer Droost permission), or from the CLI:

drush config:set droost.settings allow_destructive true
drush config:set droost.settings allow_eval true

Each flag is independent: enabling destructive tools does not enable the eval tool.

Tool reference

Every tool returns {success, message, data}. The columns mirror the MCP annotations Droost sets on each tool.

Introspection (read-only)

Operations

Security model

Droost is explicit about runtime safety:

• Read-only by default. Every tool sets accurate MCP annotations (readOnly, destructive, idempotent, openWorld). These are advisory hints to the client; the real gate is enforced in code.
• Opt-in gating. State-changing tools are registered (so an agent can discover them) but call a gate at the top of execution and refuse unless the relevant droost.settings flag is on. The refusal message explains exactly how to enable the tool.
• Why a config flag, not a permission. Over STDIO there is no web session or authenticated user, so a Drupal permission cannot gate the call; the config flag does. The module still ships the matching use droost * permissions for the case where MCP Server is additionally exposed over HTTP at /_mcp - in which case destructive tools should remain STDIO-only.
• Secret redaction. droost_config_get recursively redacts values whose keys look sensitive (*pass*, *secret*, *token*, *credential*, *hmac*, *salt*, key / *_key, API/client keys), so credentials never reach the agent. It never returns settings.php values.
• Read-only SQL guard. droost_db_query accepts a single statement, allows only SELECT / WITH / SHOW / DESCRIBE / EXPLAIN, and rejects write or DDL keywords, stacked statements, and file functions (INTO OUTFILE, LOAD_FILE).
• Eval is doubly gated. droost_eval is off by default behind its own allow_eval flag (separate from allow_destructive) and is documented as trusted-local-development only.

Guidelines

Droost bundles composable Drupal know-how under guidelines/:

• Core conventions (guidelines/core/) - always-on guidance an agent should follow on every change: dependency injection over \Drupal::, hooks, the entity and config APIs, render arrays, plugins, coding standards, and security.
• Deep-dive topics (guidelines/topics/) - pulled on demand by name: entity-api, plugins, mcp-tools, and security.

The droost_guidelines tool serves the core conventions (version-stamped to the live Drupal and PHP versions) plus the topic list; pass topic for one topic's full content. drush droost:install writes the same composed guidelines into a delimited block in AGENTS.md so non-MCP tooling can use them too.

Submodules

• droost_devel (requires Devel) - droost_generate creates content, users, or terms via devel_generate. Destructive; gated by allow_destructive.
• droost_profiler (self-contained, no external dependency) - a lightweight request profiler. Opt-in middleware records DB queries, wall-clock time, and peak memory per HTTP request; droost_profile_list and droost_profile read them back over MCP, surfacing the slowest and duplicate queries.

Extending Droost

A Droost tool is a plugin class under src/Plugin/Tool/. To add one:

1. Carry the #[Tool] attribute (id, label, description, inputSchema, outputSchema, and the readOnly / destructive / idempotent / openWorld annotations).
2. Extend DroostToolBase (or DestructiveToolBase for state-changing tools). The base classes provide the succeed() / fail() envelope helpers, small typed-argument coercion helpers (stringArg(), intArg(), stringListArg(), toString(), toInt()), the enabled => TRUE default so the tool auto-registers, and - for DestructiveToolBase - the gate() check.
3. Implement execute(array $arguments, ClientGateway $gateway): mixed and return a {success, message, data} array.
4. Inject services through create() rather than calling \Drupal::.

A minimal read-only tool:

#[Tool(
  id: 'droost_example',
  label: new TranslatableMarkup('Droost: Example'),
  description: new TranslatableMarkup('Returns a greeting. Read-only.'),
  inputSchema: ['type' => 'object'],
  readOnly: TRUE,
  destructive: FALSE,
  idempotent: TRUE,
  openWorld: FALSE,
)]
final class Example extends DroostToolBase {

  public function execute(array $arguments, ClientGateway $gateway): mixed {
    return $this->succeed('Hello from Droost.', ['greeting' => 'hello']);
  }

}

A state-changing tool calls the gate first:

public function execute(array $arguments, ClientGateway $gateway): mixed {
  if (($blocked = $this->gate()) !== NULL) {
    return $blocked;
  }
  // perform the guarded operation
}

See src/Plugin/Tool/AppInfo.php for a complete read-only example, src/Plugin/Tool/ConfigSet.php for a gated one, and the mcp-tools guideline topic for the full contract. Run drush cache:rebuild and the tool appears in tools/list.