Ask an AI coding agent to implement a Drupal hook or configure an entity type and it will often guess. It knows what should exist in a well-designed CMS, but not what actually exists in Drupal 10 or 11. The result is code that looks right, uses deprecated APIs, or calls functions that never existed.

Drupal Dev MCP fixes this by giving the agent real Drupal docs to search. It fetches the docs from source, parses and embeds them, and loads them into a local vector database the agent can query over MCP.

The Problem

An agent is only as good as the context it can reach. For Drupal, that context is scattered everywhere: api.drupal.org, drupal.org module pages, Symfony docs, PHP-FIG standards, and dozens of contrib READMEs. Working from training data alone, an agent can't reliably tell Drupal 7, 9, and 11 APIs apart. It'll mix up hook_entity_presave() with hook_ENTITY_TYPE_presave(), suggest Field UI workflows that changed in Drupal 10, or recommend services that were renamed.

You don't fix that with a bigger model. You fix it with grounded retrieval: give the agent the actual docs at query time so its answers are anchored in real source material.

How It Works

Drupal Dev MCP is an MCP server that exposes five tools to any compatible AI agent (Claude, OpenCode, Cursor, or any client that speaks MCP):

  • initialize_drupal_docs : Runs the ETL pipeline: fetches documentation sources, parses them into chunks, generates OpenAI embeddings, and loads them into a local vector database. Requires an OpenAI API key.
  • search_drupal_docs : Raw vector search over the corpus. Returns unsynthesized retrieval hits with exact excerpts, file paths, and metadata. The agent decides what to do with the results.
  • ask_drupal_expert : Conversational synthesis. Takes a natural-language question, searches the corpus, and returns a citation-backed explanation tailored to developers implementing the feature.
  • deep_research_drupal : Iterative research planner. Runs multiple search rounds, follows up on related concepts, and produces an implementation roadmap with architectural guidance grounded in retrieved evidence.
  • drupal_skill_guide : Returns best-practice rules for a specific domain: nodes, blocks, taxonomy, fields, views, forms, text formats, theming, and config. These are opinionated guardrails, not search results.

The Retrieval Architecture

Not all docs are equal, so the server ranks sources by authority: core API docs first, then contrib READMEs, then community posts. Search for hook_form_alter and you get the api.drupal.org definition first, then the Form API reference, then real hook implementations from core.

We're not trying to replace the Drupal handbook. We're trying to make the handbook reachable by the tools that are already writing the code.

Each retrieved chunk carries metadata: Drupal version, section path, file URL, and related symbols. This means the agent can filter by version (drupal_version: "11.x") and avoid recommending Drupal 7 patterns when the project targets Drupal 11.

Skill Guides

Beyond search, the server ships opinionated skill guides for each Drupal domain. These cover how to think about the domain, not just what the API says. The fields guide, for example, covers:

  • Naming conventions for field machine names and storage settings
  • When to use a base field vs a configurable field
  • How field storage interacts with revision tracking
  • Guardrails against common mistakes (direct DB writes, missing schema hooks)

These aren't generated. They're curated rules from developers who've shipped production Drupal sites and know where the footguns are.

Using It

The server runs locally and connects to any MCP-compatible agent. Once initialized it stays resident. The agent queries it on demand without re-fetching anything. The corpus is tens of thousands of chunks across core docs, API references, and selected contrib docs, and it grows with each rebuild.

# The agent can call these tools at any time:

# 1. Search for specific API documentation
search_drupal_docs("hook_entity_presave implementation")

# 2. Ask a conceptual question
ask_drupal_expert("How do I add a custom field to a node type programmatically?")

# 3. Run deep research on a complex topic
deep_research_drupal("How to migrate content from Drupal 7 to 11")

# 4. Get best-practice rules for a domain
drupal_skill_guide("fields")

Why This Matters

You can't learn Drupal from training data alone. The API surface is large, the conventions are specific, and the difference between correct and plausible-looking-wrong is often invisible until production. Ground the agent in real docs at query time and it stops guessing. Not because the model got smarter, but because it doesn't have to.

This is part of a broader pattern we've been working on: giving agents structured, searchable knowledge bases for the specific stack they work in. The same retrieval approach powers the USWDS component registries in the next post.

The project is MIT licensed and designed to work with any MCP-compatible AI coding agent. If you're building Drupal sites with AI assistance, get in touch to share feedback on which documentation sources and skill domains would be most useful to add next.