Metadata-Version: 2.4
Name: drupal-rag-mcp
Version: 0.1.0
Summary: MCP server for Drupal RAG, file access, routes, and safe Drupal commands
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.27.2
Requires-Dist: requests>=2.34.2
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: PyYAML>=6.0.3
Requires-Dist: psutil>=7.2.2
Requires-Dist: ipython>=9.14.1
Provides-Extra: rag
Requires-Dist: chromadb>=1.5.9; extra == "rag"
Requires-Dist: langchain>=1.3.2; extra == "rag"
Requires-Dist: langchain-chroma>=1.1.0; extra == "rag"
Requires-Dist: langchain-community>=0.4.2; extra == "rag"
Requires-Dist: langchain-core>=1.4.0; extra == "rag"
Requires-Dist: langchain-huggingface>=1.2.2; extra == "rag"
Requires-Dist: langchain-text-splitters>=1.1.2; extra == "rag"
Requires-Dist: sentence-transformers>=5.5.1; extra == "rag"
Requires-Dist: fastapi>=0.136.3; extra == "rag"
Requires-Dist: uvicorn>=0.48.0; extra == "rag"
Dynamic: license-file

# Drupal RAG MCP
<img src="media/screenshot.png" alt="Drupal Agent Screenshot" style="max-width: 150px;">

A Model Context Protocol (MCP) server that gives AI coding assistants direct access to Drupal projects through:

* Drupal codebase search (RAG)
* File reading
* File writing
* Drupal route discovery
* Safe Drupal command execution
* Project file listing

This server is designed for use with MCP-compatible clients such as:

* Claude Desktop
* Claude Code
* Cursor
* Windsurf
* Cline
* OpenAI Codex CLI
* Other MCP-compatible tools

---

## Features

### Search Drupal Knowledge Base

Search indexed Drupal source code and documentation using semantic search.

Tool:

```text
search_drupal_docs
```

### Read Drupal Files

Read any file within the configured Drupal project.

Tool:

```text
read_drupal_file
```

### Write Drupal Files

Create or update files inside the Drupal project.

Tool:

```text
write_drupal_file
```

### Run Drupal Commands

Execute approved Drupal development commands.

Supported commands:

* drush
* composer
* phpunit

Tool:

```text
run_drupal_command
```

### List Project Files

Browse project source files without using embeddings.

Tool:

```text
list_project_files
```

### Discover Drupal Routes

Search Drupal routes by:

* Route name
* Path
* Controller
* Form
* Permission
* Title

Tool:

```text
find_routes
```

---

# Architecture

```text
AI Client
    │
    ▼
Drupal MCP Server
    │
    ▼
Drupal RAG API
    │
    ├── Chroma Vector Database
    ├── Drupal Source Code
    └── Drupal Documentation
```

The MCP server communicates with a local FastAPI service that performs indexing, search, file operations, and command execution.

---

# Installation

Install from PyPI:

```bash
pip install drupal-rag-mcp
```

Or install with RAG dependencies:

```bash
pip install "drupal-rag-mcp[rag]"
```

---

# Requirements

* Python 3.10+
* Drupal project
* Composer
* Drush (optional)
* ChromaDB

---


# Build Your Drupal RAG
Create a .drupal-rag folder under your home directory
```bash
mkdir ~/.drupal-rag 
cd ~/.drupal-rag
touch config.toml
```
Paste this settings
```toml
drupal_root = "/path_to_drupal_project_directory"
db_dir = "~/.drupal-rag/chroma"
```

Inside ~/.drupal-rag
```bash
mkdir docs
```

Inside docs add all your drupal documentation (PDF, MD, txt).
Start indexing your docs to create rag

```bash
drupal-rag-index
```

This will:

1. Scan Drupal files
2. Split documents into chunks
3. Generate embeddings
4. Store vectors in Chroma

---

# Start the API Server

```bash
drupal-rag-api
```

The API provides:

```text
POST /search
POST /read-file
POST /write-file
POST /run-command
POST /list-files
POST /find-routes
```

---

# Start the MCP Server

```bash
drupal-rag-mcp
```

The MCP server uses stdio transport and is intended to be launched by an MCP client.

---

# MCP Client Configuration

## Claude Desktop

```json
{
  "mcpServers": {
    "drupal-rag": {
      "command": "drupal-rag-mcp"
    }
  }
}
```

## Cursor

```json
{
  "mcpServers": {
    "drupal-rag": {
      "command": "drupal-rag-mcp"
    }
  }
}
```

## VSCODE

### Installing and Running Ollama on Mac
```bash
brew install ollama
brew services start ollama
brew services stop ollama
```

### Run and Download an AI Model
```bash
ollama pull qwen3
ollama run qwen3
```

### Set Up Continue
1. Add Extension Continue
2. Configure Continue config.yaml
```yml
name: Local Config
version: 1.0.0
schema: v1

models:
  - name: Qwen3
    provider: ollama
    model: qwen3
```

3.  Add MCP server in Continue

```bash
which drupal-rag-mcp
```
Example output: `/opt/anaconda3/envs/drupal_rag/bin/drupal-rag-mcp`

Configure Continue mcp-server.yaml
```yml
name: Drupal RAG MCP
version: 0.0.1
schema: v1

mcpServers:
  - name: drupal-rag
    command: /opt/anaconda3/envs/drupal_rag/bin/drupal-rag-mcp
    args: []
    env:
      DRUPAL_ROOT: /path_to_your_drupal
```


## Codex CLI

```toml
[mcp_servers.drupal-rag]
command = "drupal-rag-mcp"
args = []
```

---

# Example Prompts

```text
Find the route responsible for user login.
```

```text
Search Drupal documentation for cache tags.
```

```text
Show me all custom routes under /admin.
```

```text
Read web/modules/custom/example/src/Form/ExampleForm.php
```

```text
Run drush cr
```

---

# Security

The server includes several safeguards:

* Path traversal protection
* Drupal root restriction
* Command allow-list
* Ignored directories and file types
* Local-only API access

Only approved commands can be executed.

Review the source code before enabling write access in production environments.

---

# License

MIT License

Copyright (c) 2026 John Paul Mariano

See the LICENSE file for full license text.
