drupal-dev MCP server
Commit Nov 9, 2026Provides version-aware Drupal documentation and API knowledge to AI agents using a local SQLite index with verifiable citations.
Also known as ednark/drupal-dev-mcp
- Stars
- 0
- Tools
- 18
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- MIT
What is drupal-dev MCP?
drupal-dev provides version-aware Drupal documentation and API knowledge to AI agents using a local SQLite index with verifiable citations. It exposes 18 tools, such as question, drupal_version, query.
Summary generated from the project's README
About drupal-dev MCP server
Providing version-specific Drupal documentation and API guidance to AI coding agents is the primary function of this MCP server. It uses a local SQLite index containing core API docs, change records, and Symfony or PHP documentation to ensure developers receive accurate information. The server is designed to be read-only, offering six deterministic retrieval tools that provide verifiable citations via drupal:// URIs.
Users can query specific versions such as Drupal 10.6, 11.4, or the 12.0.x pre-release. The system runs locally via stdio transport and does not require Docker. While most tools are for pure evidence retrieval, an opt-in synthesis tool called ask_a_drupal_expert allows for grounded decision-making. This specific tool requires an OpenAI API key and can operate in either a single-round ask mode or a multi-round research mode. The server supports optional semantic search through LanceDB embeddings, but remains functional in a lexical-only mode using SQLite FTS5 if embeddings are not configured.
What you can do with it
- 1Verify Drupal API documentationAn AI agent can retrieve the exact indexed text of a document to confirm a claim is accurate.
- 2Validate module namesDevelopers can use the server to check if a module name is correct before attempting to install it via composer.
- 3Perform version-specific researchAn agent can conduct iterative research to compare different Drupal concepts across specific versions.
- 4Navigate API relationshipsA developer can use the server to explore how different entities or pieces of evidence are connected within the Drupal graph.
Written from the project's README. Every use case is checked against a quote from it.
drupal-dev MCP tools 18
Detected from the READMEquestiondrupal_versionquerydatasetstop_kper_dataset_limitstrategyinclude_textinclude_metadatamax_iterationsqueries_per_iterationinitial_top_k
| question | — | |
| drupal_version | — | |
| query | — | |
| datasets | — | |
| top_k | — | |
| per_dataset_limit | — | |
| strategy | — | |
| include_text | — | |
| include_metadata | — | |
| max_iterations | — | |
| queries_per_iteration | — | |
| initial_top_k | — |
Show all 18 toolsShow fewer tools
followup_top_kmax_evidence_chunksoutput_formatinclude_evidence_textskill_idformat
| followup_top_k | — | |
| max_evidence_chunks | — | |
| output_format | — | |
| include_evidence_text | — | |
| skill_id | — | |
| format | — |
Configuration
DRUPAL_MCP_INDEX_ROOTLANCEDB_PATHOPENAI_AGENT_MODELOPENAI_API_KEYOPENAI_BASE_URL
| Name | Description | |
|---|---|---|
| DRUPAL_MCP_INDEX_ROOT | — | |
| LANCEDB_PATH | — | |
| OPENAI_AGENT_MODEL | — | |
| OPENAI_API_KEY | — | |
| OPENAI_BASE_URL | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableednark/drupal-dev-mcp is public and reachablegithub.com/ednark/drupal-dev-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/ednark/drupal-dev-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model18 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubdrupal-dev-mcp
Version-aware Drupal knowledge for AI coding agents — with citations you can verify.
An MCP server that answers Drupal questions from a local, version-scoped index of core API docs, change records, contrib source, Symfony/PHP docs, and curated guidance. Every result carries a drupal:// citation, and get_drupal_document returns the exact indexed text behind a claim so it can be checked rather than trusted.
- Read-only by design. The six retrieval tools never synthesize advice. The single synthesis tool (
ask_a_drupal_expert) is opt-in, needs its own API key, and returnsinsufficient_evidenceinstead of guessing. - Version-aware. Query Drupal 10.6, 11.4, or the 12.0.x pre-release — or ask for an explicit cross-version search.
- Runs locally. SQLite FTS5 plus a semantic graph. Embeddings are optional; without them search still works and reports
degraded_mode: "lexical_only". - No server, no Docker. One local index, stdio transport, MIT licensed.
Version 0.2 is a clean-break redesign with three npm workspaces (none published to npm):
@drupal-dev-mcp/knowledgebuilds and queries a versioned SQLite, FTS5, semantic-graph, and optional LanceDB index.@drupal-dev-mcp/serverexposes seven deterministic MCP tools (six retrieval tools plus one opt-in synthesis tool) and three resource surfaces over aKnowledgeProvider.@drupal-dev-mcp/agentcontains optional OpenAI-backed answer and iterative-research workflows as a library, CLI, and the engine behind the server'sask_a_drupal_experttool.
The retrieval tools do not synthesize advice; ask_a_drupal_expert is the single explicit exception, gated on its own API key. The server never runs indexing, executes commands, fetches arbitrary URLs, or mutates the workspace.
Quick start
Requirements: Node.js 22+ (26 recommended — .nvmrc pins it), npm 10+, Git, and enough local disk for two Drupal core checkouts and the generated index. better-sqlite3 is a native module: after a Node major upgrade, run npm rebuild better-sqlite3 if it fails to load (the test suite's pretest doctor check will tell you).
npm install
npm run build
npm run index:fetch
npm run index:rebuild
npm run index:verify
npm run mcp:start
The active build defaults to Drupal 11.4. Every query can target Drupal 10.6, the pre-release Drupal 12.0 (12.0.x branch), or request an explicit cross-version search.
Embeddings are optional. Without them, search remains fully operational through SQLite FTS5 and returns degraded_mode: "lexical_only". To create the unified LanceDB table, explicitly authorize sending indexed chunk text to the configured embedding provider and run:
npm run index:rebuild -- --with-embeddings
MCP surface
The normative wire contract for these tools — schemas, result envelope, _meta keys, resource URIs, capability advertisement, and status semantics — is docs/tools-spec.md. A companion agent skill packages the usage guidance (routing, grounding workflow, token budgeting) for skill-aware clients: skills/querying-drupal-knowledge/. The six read-only, non-destructive, idempotent, closed-world retrieval tools plus one opt-in synthesis tool:
search_drupal— searches evidence using version, mode, project, source type, entity kind, limit, snippet-budget, and relevance-floor (min_score) filters. Short keyword/identifier queries score best; semantic hits carry chunk-level citation URIs. Ordering is deterministic within an index build.source_types: ["guidance"]narrows to the curated guidance corpora — change-placement docs and AI-frequent anti-pattern docs (legacy-pattern fallbacks like service-locator calls,|rawin Twig, missing cache metadata, and their current replacements);["tooling"]also matches validation-tooling guidance (PHPStan/PHPCS/complexity tooling and the agent fix-loop pattern).get_drupal_entity— resolves an opaqueent_…ID or exact identifier and returns disambiguation, metadata, deprecations, evidence, and relationships.get_drupal_entities— resolves up to 25 opaqueent_…IDs in one call; unknown IDs are reported per item instead of failing the batch.explore_drupal_relationships— traverses evidence-backed graph edges with predicate, direction, depth, confidence, and node limits.get_drupal_document— returns the exact indexed text of a document or a single chunk, for verifying citations against source without re-searching.get_index_status— reports the active verified build: readiness, build date, versions, counts, verification, and build-drift detection (staleBuildwhen the index was rebuilt after this server spawned).verify_drupal_modules— deterministic module-name verification against the indexed registry: per machine name,core/contrib/not_foundwith evidence. Catches fabricated or misspelled module names beforecomposer installordrush en.ask_a_drupal_expert(opt-in synthesis) — evidence-grounded answers to questions that need conclusions rather than retrieval ("where do style changes live?", "when is a custom theme warranted?", "how should I migrate this site?"). Runs in two modes:depth: "ask"(one evidence round) anddepth: "research"(iterative multi-query rounds). Every claim is cited withdrupal://URIs; questions it cannot ground returninsufficient_evidenceinstead of guesses. RequiresOPENAI_API_KEYin the MCP client's env for this server — without it the tool returnsstatus: "unavailable"and all other tools keep working. This tool exists as the worked example of turning indexed sources into grounded decisions; the six retrieval tools remain pure-evidence.
Every successful result includes a stable resource URI, version compatibility, provenance, authority, and freshness. Graph traversal defaults to confidence >= 0.7.
Resources:
drupal://index/status
drupal://entity/{id}
drupal://document/{id}
drupal://document/{id}#chunk/{chunkId}
Running your own agent loop around this server? See docs/integration-agent-loops.md for the canonical client config, annotation-based policy mapping, recommended call patterns, and token-budgeting knobs.
Example MCP client entry after npm run build:
{
"mcpServers": {
"drupal-dev-mcp": {
"command": "node",
"args": ["/absolute/path/to/drupal-dev-mcp/packages/server/dist/index.js"],
"env": {
"DRUPAL_MCP_INDEX_ROOT": "/absolute/path/to/drupal-dev-mcp/data/index"
}
}
}
}
Maintainer commands
npm run index:fetch # refresh all git-based sources (core snapshots, contrib code, examples, skills, symfony docs); -- --core-only for core snapshots alone
npm run index:fetch-advisories # fetch Drupal core security advisories (cron-friendly; --pages=N for backfill, --check-only to diff)
npm run index:fetch-change-records # fetch NEW change records + full text (cron-friendly; --backfill-full-text upgrades existing files)
npm run index:build # build and atomically activate a verified index
npm run index:verify # verify active SQLite integrity and references
npm run index:rebuild # clean full-index build; no old-index migration
npm run index:status # report active run, counts, versions, and warnings
npm run index:freshness # compare data/sources against the active build; exit 1 when sources need re-processing
# add --check-upstream to also git-fetch each source's remote and flag clones whose
# upstream moved (status: upstream_drift) — disk-vs-index "fresh" does NOT mean upstream-current
npm run index:benchmark # rank-aware retrieval gate (39 cases: top-3 pass, MRR, chrome invariant, negative terms); -- --save-baseline refreshes docs/eval/benchmark-baseline.json; regression-fails against the stored baseline otherwise
npm run index:health # corpus ingestion-quality gate: chrome ratio, stub ratio, size floors per text source (catches pollution search gates cannot see)
npm run index:version-smoke # version-scoped retrieval probes (per-version presence/absence matrix); exit 1 on failure
npm run check # typecheck + test in one gate
npm test
Builds live under data/index/builds/{run-id}. A build becomes active only after verification passes and data/index/active.json is atomically replaced. A failed build leaves the prior active manifest untouched.
Optional agent
The agent package receives evidence only through KnowledgeProvider and explicitly reports insufficient evidence. Synthesis prompts enforce strict grounding (evidence-only claims, chunk-level drupal:// citations, source-authority weighting, version and deprecation awareness); the research loop tracks already-executed queries and generates short keyword-style follow-ups. Tool calls, admitted evidence, iterations, budgets, and stop reasons are observable.
npm run agent:ask -- --drupal-version 11.4 "How does dependency injection work?"
npm run agent:research -- --drupal-version 11.4 --max-iterations 4 "Compare event subscribers and hooks"
Set OPENAI_API_KEY and optionally OPENAI_AGENT_MODEL in .env. Agent citations retain both stable drupal:// resource URIs and canonical source URLs.
LLM providers and model sizing
The agent (and therefore ask_a_drupal_expert) speaks the OpenAI Chat Completions API, so it also works against any OpenAI-compatible local endpoint:
# .env — Ollama example
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_API_KEY=ollama # placeholder; the endpoint ignores it
OPENAI_AGENT_MODEL=qwen3:32b # any locally pulled model tag
The same two variables belong in your MCP client config (env block for this server) when using the expert tool, not just .env. Without a custom OPENAI_BASE_URL, a real OpenAI key is required.
Hard budgets in code
These are fixed by the implementation (packages/agent/src/openai-provider.ts, packages/agent/src/agent.ts) and define what a model must cope with:
| Budget | Value | Where |
|---|---|---|
| Output cap per synthesis call | 2,000 tokens (override with AGENT_MAX_OUTPUT_TOKENS) |
answer + research report |
| Research query-planner output | 400 tokens, strict JSON required | per planning round |
Evidence bundle, depth: "ask" |
≤ 8 hits × ≤ 800-char snippets ≈ 2–4k input tokens total prompt | one search round |
Evidence bundle, depth: "research" |
up to 24 admitted items ≈ 8–12k input tokens final report prompt (budget adjustable 5–100) | accumulated rounds |
What that means for local models
- Context window: 8k is enough to run
ask; aim for ≥16k–32k forresearchso evidence plus a full report fit without truncation. RaiseAGENT_MAX_OUTPUT_TOKENSonly if your hardware gives the model headroom for it. - Capability floor: every synthesis call must emit grounded, URI-cited prose, and research mode additionally requires reliable strict-JSON emission from the planner. That instruction-following burden is why sub-7B models tend to produce mushy or uncited answers even when they "fit".
- Practical minimum: instruction-tuned ~8B class (e.g.
llama3.1:8b-instruct-q4_K_M) — acceptable forask. - Recommended: 30B+ class (e.g.
qwen3:32b) forresearchreports worth keeping.
- Practical minimum: instruction-tuned ~8B class (e.g.
- Graceful degradation is built in: if a small model emits invalid planner JSON, the research loop simply stops after admitting what it found rather than crashing; an empty evidence set yields an explicit
insufficient_evidenceanswer. - Verify small-model output: weaker models still cite plausible-looking URIs that may be wrong. The mechanical check exists for exactly this — pass their
drupal://citations toget_drupal_documentand confirm exact text before trusting them (see docs/integration-agent-loops.md).
Caveat: only generation is provider-swappable today. Embeddings (hybrid semantic search and index builds with --with-embeddings) always use OpenAI embedding endpoints; fully local setups should expect lexical-only retrieval unless they have an embeddings key set.
Architecture and migration
See docs/architecture-0.2.md for schemas, extraction confidence, retrieval stages, activation, and verification details.
The 0.1 tools ask_drupal_expert, search_drupal_docs, deep_research_drupal, drupal_skill_guide, and initialize_drupal_docs were removed. Skill guides are normal searchable documents/resources; index creation is a maintainer CLI operation; synthesis and research moved to the agent package.
As of 0.2.x, an ask_a_drupal_expert tool has been restored as a thin, opt-in MCP wrapper around the agent package, together with a curated change-placement guidance corpus (data/sources/drupal-placement-guidance/) and a crawled Drupal theming guide — so the classic "when do I use X and where does Y live" questions get grounded, citable answers instead of API-facts-only retrieval.
License
MIT. See LICENSE.
The 0.1 source trees (
src/,etl/,tests/, rootdist/, and thetsconfig.typecheck/tsconfig.fetcherconfigs) were removed in the 0.2 cleanup; this section is retained purely as a migration reference and its file paths no longer exist. The 0.1 evaluation question sets live in docs/eval/.
drupal-dev-mcp (0.1)
Drupal development MCP server powered by RAG + LLM — gives AI assistants direct access to Drupal documentation, source code, best-practice skill guides, and iterative deep-research capabilities via local vector search and OpenAI synthesis.
Overview
drupal-dev-mcp is a Model Context Protocol (MCP) server that exposes four complementary tools to any MCP-compatible AI client (Claude Desktop, Cursor, RooCode, etc.). The server is powered by a locally embedded LanceDB vector database built from a broad corpus of official Drupal documentation, API references, contrib module source code, PHP and Symfony documentation, certification study guides, and community tutorials.
Answers and research outputs are grounded entirely in the local corpus — no internet search is performed at query time. All LLM synthesis is handled by OpenAI (text-embedding-3-small for retrieval, GPT-4o for synthesis by default). The server communicates over stdio transport and is registered in your AI client's MCP configuration as a standard server entry.
The ETL pipeline fetches, parses, chunks, embeds, and loads content from 14+ knowledge sources into LanceDB tables. Once indexed, the four MCP tools can be called at any time from your AI client to retrieve canonical Drupal references, synthesize expert answers, load domain-specific skill guides, or drive multi-iteration research workflows.
Available MCP Tools
The following tools are registered in src/index.ts and exposed to MCP clients.
ask_drupal_expert
File: src/tools/ask-drupal-expert.ts
Provides conversational, citation-backed explanations for human Drupal backend developers. This tool searches the local Drupal documentation corpus and source code, then synthesizes an educational answer tailored to people seeking conceptual clarity. Covers hooks, services, dependency injection, entity API, form API, routing, config management, caching, plugins, migrations, events, and Drupal/Symfony patterns.
Primary use case: Explaining concepts, answering implementation questions, and synthesizing guidance from multiple documentation sources into a single Markdown answer with [Source N] citations and a ## Sources section.
When to use: When you need a narrative, human-readable answer with citations. Not for raw retrieval hits or structured data.
| Parameter | Type | Required | Description |
|---|---|---|---|
question |
string | ✅ | The Drupal development question to answer |
drupal_version |
string | no | Optional version filter (e.g., "11.x"). If omitted, searches all versions. |
search_drupal_docs
File: src/tools/search-drupal-docs.ts
Raw Drupal documentation search for agents. Returns unsynthesized retrieval hits with exact excerpts and metadata. Ideal for agentic workflows where the AI client needs to inspect source material directly rather than receive a synthesized answer.
Primary use case: Gathering raw evidence chunks before deciding how to act. Use in planning workflows, before calling ask_drupal_expert, or when you want to control synthesis yourself.
When to use: When you need structured retrieval results (JSON), want to filter specific datasets, or are building agentic workflows that inspect evidence before synthesis.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query |
string | ✅ | — | Natural-language search query |
drupal_version |
string | no | all | Optional version filter (e.g., "10.x", "11.x") |
datasets |
string[] | no | all | Explicit dataset allowlist (see dataset names below) |
top_k |
integer (1–25) | no | 8 | Maximum hits returned after merge and filtering |
per_dataset_limit |
integer (1–10) | no | 4 | Maximum hits fetched from each dataset before merge |
strategy |
"tiered" | "flat" |
no | "tiered" |
Whether to preserve source-quality tiers or rank globally by relevance |
include_text |
boolean | no | true |
Whether to include chunk text in the response |
include_metadata |
boolean | no | true |
Whether to include section, file path, symbol name, and related metadata |
deep_research_drupal
File: src/tools/deep-research-drupal.ts
Iterative Drupal research planner. Produces implementation roadmaps and architectural guidance grounded in local documentation evidence. Runs multiple rounds of retrieval, using GPT-4o to generate follow-up queries, accumulate a structured evidence dossier, and synthesize key findings, open questions, contradictions, and a recommended approach.
Primary use case: Multi-domain architectural investigations, implementation planning, or any question that requires synthesizing evidence across many source types before recommending an approach.
When to use: For high-stakes, multi-step research tasks (e.g., "What is the recommended pattern for building a decoupled Drupal site with JSON:API and React?"). More expensive than ask_drupal_expert but delivers structured dossiers with implementation roadmaps and evidence ledgers.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
question |
string | ✅ | — | Primary Drupal research question |
drupal_version |
string | no | all | Optional version filter (e.g., "11.x") |
datasets |
string[] | no | all | Optional dataset allowlist for all research iterations |
max_iterations |
integer (1–6) | no | 4 | Hard cap on research rounds |
queries_per_iteration |
integer (1–5) | no | 2 | Maximum follow-up queries generated per iteration |
initial_top_k |
integer (1–15) | no | 8 | Maximum hits for the initial broad retrieval step |
followup_top_k |
integer (1–10) | no | 5 | Maximum hits per follow-up query |
max_evidence_chunks |
integer (5–40) | no | 18 | Cap on evidence stored in the final dossier |
output_format |
"json" | "markdown" |
no | "json" |
Preferred response format |
include_evidence_text |
boolean | no | false |
Whether to include full chunk text excerpts in the final response |
drupal_skill_guide
File: src/tools/drupal-skill-guide.ts
Returns Drupal best-practice skill rules for a specific domain. Reads curated SKILL.md files from the local drupal-best-practices data source, which contain authoritative naming conventions, guardrails, usage patterns, and validation commands. Pair with ask_drupal_expert for searched documentation.
Primary use case: Loading domain-specific guardrails and naming conventions before generating or reviewing Drupal configuration, code, or architecture plans.
When to use: At the start of a site-building or module-development workflow to establish the correct conventions before asking broader questions or generating code.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
skill_id |
string | ✅ | — | Drupal skill domain to retrieve. Valid values: nodes, blocks, taxonomy, fields, views, forms, text-formats-editors, theming, config-parser, other-content-entities |
format |
"raw" | "trimmed" | "json" |
no | "trimmed" |
"raw" returns the complete SKILL.md. "trimmed" strips frontmatter and ## References. "json" returns a structured object with id, title, description, usage, guardrails, validation_command, and references. |
Data Sources
The RAG index is built from the following knowledge sources. Each is fetched, parsed, chunked, embedded, and loaded into a named LanceDB dataset.
| Dataset name | Source | Description |
|---|---|---|
drupal_core_docs |
api.drupal.org, drupal.org/docs/user_guide | Core API docs, user guide, PHPDoc |
api_drupal_org_docs |
api.drupal.org/api | Canonical function, hook, and service documentation |
change_records |
drupal.org/list-changes | Release-by-release behavioral notes and API changes |
core_module_code |
git.drupalcode.org (Drupal core) | Source code of Drupal core modules |
contrib_module_code |
git.drupalcode.org (contrib) | Source code for widely used contrib modules |
contrib_module_docs |
drupal.org/docs/contributed-modules | Contrib module README and handbook pages |
contrib_module_handbook |
drupal.org/docs/contributed-modules | Handbook pages fetched via Jina proxy |
drupal_module_handbook |
drupal.org/docs/develop | Official module developer handbook |
drupal_developer_guides |
drupal.org/docs/develop/developer-tools | Modern Drupal workflow developer guides |
drupal_tutorials |
drupal.org/docs | How-to tutorials and articles |
drupal_examples |
drupal.org/project/examples | Runnable example implementations |
drupal_best_practices |
drupal.org/docs/develop/best-practices | Community best-practices guide + curated skill files |
php_docs |
php.net/manual/en/ | PHP manual pages relevant to Drupal runtime |
symfony_docs |
symfony.com/doc/current/ | Symfony component docs (routing, services, events) |
certification_docs |
acquia.com/academy | Acquia certification study guide material |
Prerequisites
- Node.js ≥ 20.0.0 (pin with
.nvmrc:nvm use) - npm ≥ 10 (bundled with Node 20)
- OpenAI API key — platform.openai.com/api-keys
- git — for cloning Drupal core during source sync
Installation
# 1. Clone the repository
git clone https://github.com/your-org/drupal-dev-mcp.git
cd drupal-dev-mcp
# 2. Install Node dependencies
npm install
# 3. Configure environment
cp .env.example .env
# Edit .env and set OPENAI_API_KEY=sk-...
# 4. Build TypeScript
npm run build
drupal-dev MCP questions
What tools does drupal-dev MCP provide?
It exposes 18 tools, including question, drupal_version, query, datasets, top_k.
Does this server synthesize advice or just retrieve information?
The six retrieval tools are read-only and never synthesize advice. There is a single opt-in synthesis tool called 'ask_a_drupal_expert' that requires an API key.
Can I use this without embeddings?
Yes, embeddings are optional. If they are not used, search still works via SQLite FTS5 and will report a degraded lexical-only mode.
How can I verify the information provided by the AI?
Every result includes a drupal:// citation, and you can use the get_drupal_document tool to retrieve the exact indexed text to verify the claim.
Which Drupal versions are supported?
The server supports multiple versions including Drupal 10.6, 11.4, and the Drupal 12.0.x pre-release.