mat-drupal-mcp/README.md

MatDrupal MCP - AI Assistant for Drupal Projects with bilingual FR/EN support

# 🚀 MatDrupal MCP - AI Assistant for Drupal Projects

[![GitHub release (latest by date)](https://img.shields.io/github/v/release/boisvertmath/mat-drupal-mcp)](https://github.com/boisvertmath/mat-drupal-mcp/releases/latest)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)

> **An intelligent Model Context Protocol (MCP) server for advanced Drupal project analysis with bilingual French/English support.**

Created by **[Mathieu Boisvert](https://github.com/boisvertmath)** to enhance GitHub Copilot with specialized Drupal development intelligence.

## ⚡ One-Click Installation

<details>
<summary><b>Install in VS Code</b></summary>

[<img alt="Install MatDrupal MCP in VS Code" src="https://img.shields.io/badge/VS_Code-Install_MatDrupal_MCP?style=flat-square&logo=visualstudiocode&logoColor=white&color=007ACC">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22matdrupal%22%2C%22command%22%3A%22bash%22%2C%22args%22%3A%5B%22-c%22%2C%22curl%20-sL%20https%3A//raw.githubusercontent.com/boisvertmath/mat-drupal-mcp/main/scripts/install.sh%20%7C%20bash%22%5D%7D)

</details>

## 🚀 Installation

### Option 1: Installation complète (recommandée)
```bash
# Installation + configuration automatique GitHub Copilot
curl -sL https://raw.githubusercontent.com/boisvertmath/mat-drupal-mcp/main/scripts/install.sh | bash
```

### Option 2: Package NPM (développeurs)
```bash
# Installation du binaire seulement
npm install -g mat-drupal-mcp

# Vérification
matdrupal --version

# Configuration GitHub Copilot manuelle requise
# Voir docs/npm-publication.md pour les détails
```

### Option 3: Installation manuelle
For development or custom setup:
```bash
git clone https://github.com/boisvertmath/mat-drupal-mcp.git ~/.matdrupal
cd ~/.matdrupal
npm install && npm run build
```

### Configure Existing Drupal Projects
Optional: Configure Drupal file associations for better syntax highlighting:
```bash
# Auto-configure Drupal project (file associations only)
~/.matdrupal/setup-project.sh /path/to/your/drupal/project

# Or configure current directory
cd /path/to/your/drupal/project
~/.matdrupal/setup-project.sh
```

> **Note**: @matdrupal is now configured globally and works in all projects automatically!

## � Usage Examples

Once installed, use these commands in GitHub Copilot Chat:

### 🔍 Project Analysis
```
@matdrupal Analyze this Drupal project completely
@matdrupal Analyser ce projet Drupal en détail
```

**What you'll get:**
- Drupal version detection
- Docroot structure analysis  
- Custom modules inventory
- Technical debt assessment

### 📦 Module Exploration  
```
@matdrupal Explore the custom module "my_module"
@matdrupal Explorer le module custom "mon_module"
```

**What you'll get:**
- Module dependencies mapping
- Hook implementations analysis
- Business logic overview
- Security considerations

### 🔧 Technical Debt Assessment
```
@matdrupal Assess technical debt and generate D11 migration roadmap
@matdrupal Évaluer la dette technique et créer un plan de migration D11
```

**What you'll get:**
- D11 compatibility analysis
- Migration complexity score
- Step-by-step upgrade plan
- Risk assessment

### 🐳 Lando Environment
```
@matdrupal Start Lando environment
@matdrupal Analyser l'environnement Lando actuel
```

**What you'll get:**
- Environment status check
- Container management
- Performance optimization tips

## 🔄 Updates & Maintenance

### Quick Update (Recommended)
```bash
# Simple one-line update
~/.matdrupal/update.sh
```

### Clean Reinstall
```bash
# Reinstall latest version (keeps your configuration)
curl -sL https://raw.githubusercontent.com/boisvertmath/mat-drupal-mcp/main/scripts/install.sh | bash
```

### Check Version
```bash
# See current version
node ~/.matdrupal/dist/index.js --version
```

### Uninstall (Complete Removal)
```bash
# Complete uninstallation with backup
curl -sL https://raw.githubusercontent.com/boisvertmath/mat-drupal-mcp/main/scripts/uninstall.sh | bash

# Or if installed locally
~/.matdrupal/scripts/uninstall.sh
```

**🔒 Safe uninstallation:** Creates automatic backup before removal, preserves other MCP servers.

### Update Process
1. **Automatic backup** of existing configuration
2. **Download** latest version from GitHub
3. **Preserve** your custom settings
4. **Test** installation integrity
5. **Restore** if update fails

**🔔 Update notifications:** You'll be notified in GitHub Copilot when new versions are available.

## � Real-World Examples

### 🎯 Common Workflows

**New Team Member Onboarding:**
```
@matdrupal I'm new to this project. Help me understand the Drupal architecture, custom modules, and current technical state.
```

**Pre-Migration Planning:**
```
@matdrupal We need to migrate to Drupal 11. Analyze compatibility, create migration plan, and identify risks.
```

**Code Review Assistance:**
```
@matdrupal Review this custom module for best practices and suggest improvements for D11 compatibility.
```

**Development Environment Setup:**
```
@matdrupal Start the Lando environment and check if everything is properly configured.
```

### 💼 Business Use Cases

| Scenario | Command | Expected Output |
|----------|---------|-----------------|
| **Project Audit** | `@matdrupal Complete project analysis` | Version, modules, technical debt score |
| **Module Documentation** | `@matdrupal Document the "user_management" module` | Purpose, dependencies, API overview |
| **Performance Review** | `@matdrupal Identify performance optimization opportunities` | Bottlenecks, recommendations |
| **Security Check** | `@matdrupal Security analysis of custom modules` | Vulnerabilities, best practices |

## 🛠️ Available Tools

| Tool | Description | Capabilities |
|------|-------------|--------------|
| `analyze_project_overview` | Complete project analysis | Docroot detection, Drupal version, module inventory |
| `explore_custom_module` | Detailed module inspection | Dependencies, hooks, business logic mapping |
| `assess_technical_debt` | D11 migration planning | Compatibility analysis, upgrade complexity assessment |
| `manage_lando_environment` | Lando container management | Start/stop/analyze local development environments |
| `acquia_intelligence_helper` | Acquia CLI integration | Cloud deployment compatibility checks |

## 📋 Prerequisites

- **macOS**
- **Node.js 18+** 
- **GitHub Copilot** subscription
- **VS Code** or **PhpStorm** with GitHub Copilot extension

## 📚 Documentation

- **[Installation Guide](INSTALL.md)** - Detailed setup instructions
- **[Usage Examples](docs/usage-examples.md)** - Comprehensive command examples
- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions
- **[Quick Start](QUICKSTART.md)** - Get up and running in 5 minutes

## 🏗️ Architecture

MatDrupal MCP leverages the Model Context Protocol to provide:

- **Intelligent Context Awareness** - Understands Drupal project structures
- **Bilingual Processing** - Adapts responses based on user language preference  
- **Environment Integration** - Works seamlessly with Lando and Acquia workflows
- **Extensible Design** - Easy to add new analysis tools and capabilities

## 🔧 Development

```bash
# Clone the repository
git clone https://github.com/boisvertmath/mat-drupal-mcp.git
cd mat-drupal-mcp

# Install dependencies
npm install

# Build and test
npm run build
npm test

# Run full test suite
./test-mcp.sh
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 👨‍💻 Author

**Mathieu Boisvert**
- GitHub: [@boisvertmath](https://github.com/boisvertmath)
- Created for enhanced Drupal development workflows

---

*Transform your Drupal development experience with AI-powered project intelligence.*