# WPCS MCP Server
A Model Context Protocol (MCP) server that integrates WordPress Coding Standards (WPCS) with Claude AI. Automatically check and fix your WordPress plugin/theme code to meet WordPress.org standards.
> **Don't use Claude AI?** No problem! See [GIT-HOOKS-SETUP.md](GIT-HOOKS-SETUP.md) for standalone Git hooks, GitHub Actions, and CI/CD setup.
## One-Line Install (Git Hooks Only)
For automatic WPCS checks on every commit **without Claude AI**:
```bash
curl -sSL https://raw.githubusercontent.com/vapvarun/wpcs-mcp-server/main/scripts/install-hooks.sh | bash
```
This installs phpcs + WPCS + PHPCompatibility and sets up pre-commit hooks in your current repo.
---
## Why Use This?
If you're developing WordPress plugins or themes, your code must follow [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/) to:
- ✅ Get approved on WordPress.org plugin/theme directory
- ✅ Write consistent, readable code
- ✅ Follow security best practices
- ✅ Make your code maintainable
**This MCP server lets Claude AI automatically check and fix your PHP code against WPCS before you commit.**
---
## Requirements Checklist
Before installing, ensure you have all requirements:
| Requirement | Minimum Version | Check Command | Install Guide |
|-------------|-----------------|---------------|---------------|
| **Node.js** | 18+ | `node -v` | [nodejs.org](https://nodejs.org) |
| **PHP** | 8.2+ | `php -v` | See PHP Setup below |
| **Composer** | 2.0+ | `composer -V` | [getcomposer.org](https://getcomposer.org) |
| **Claude Desktop or Claude Code** | Latest | `claude --version` | [claude.ai](https://claude.ai) |
### PHP Setup by Platform
<details>
<summary><strong>macOS with Laravel Herd (Recommended)</strong></summary>
```bash
# Herd installs PHP at:
# ~/Library/Application Support/Herd/bin/php
# Verify Herd PHP
~/Library/Application\ Support/Herd/bin/php -v
# Should show PHP 8.2+
# Herd also provides Composer at:
# ~/Library/Application Support/Herd/bin/composer
```
</details>
<details>
<summary><strong>macOS with Homebrew</strong></summary>
```bash
# Install PHP 8.4
brew install php@8.4
# Add to PATH in ~/.zshrc
export PATH="/opt/homebrew/opt/php@8.4/bin:$PATH"
# Verify
php -v
```
</details>
<details>
<summary><strong>macOS with MAMP</strong></summary>
```bash
# MAMP PHP location
/Applications/MAMP/bin/php/php8.2.x/bin/php
# Add to PATH in ~/.zshrc
export PATH="/Applications/MAMP/bin/php/php8.2.x/bin:$PATH"
```
</details>
<details>
<summary><strong>Windows</strong></summary>
```powershell
# Install via Chocolatey
choco install php --version=8.4
# Or download from php.net and add to PATH
```
</details>
<details>
<summary><strong>Linux (Ubuntu/Debian)</strong></summary>
```bash
sudo apt update
sudo apt install php8.2 php8.2-cli composer
```
</details>
---
## Quick Start
### Step 1: Clone & Build
```bash
git clone https://github.com/vapvarun/wpcs-mcp-server.git ~/.mcp-servers/wpcs-mcp-server
cd ~/.mcp-servers/wpcs-mcp-server
npm install --include=dev && npm run build
```
> **Important:** Use `npm install --include=dev` to ensure TypeScript compiler is available for building.
### Step 2: Install WPCS Dependencies
The server attempts auto-install, but for reliability, install manually:
```bash
# Allow the composer installer plugin
composer global config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
# Install phpcs, WPCS, and PHPCompatibility
composer global require squizlabs/php_codesniffer wp-coding-standards/wpcs phpcompatibility/phpcompatibility-wp dealerdirect/phpcodesniffer-composer-installer
# Verify installation
~/.composer/vendor/bin/phpcs -i
# Should show: WordPress, WordPress-Core, WordPress-Docs, WordPress-Extra, PHPCompatibility, PHPCompatibilityWP
```
### Step 3: Configure MCP Server
Choose your setup method:
---
## Configuration Options
### For Claude Code CLI (Recommended)
**Option A: Using CLI Command (Global)**
```bash
claude mcp add wpcs --scope user -- node ~/.mcp-servers/wpcs-mcp-server/build/index.js
```
Then manually add the PATH environment in `~/.claude.json`:
```json
{
"mcpServers": {
"wpcs": {
"type": "stdio",
"command": "node",
"args": ["/Users/YOUR_USERNAME/.mcp-servers/wpcs-mcp-server/build/index.js"],
"env": {
"PATH": "/Users/YOUR_USERNAME/Library/Application Support/Herd/bin:/Users/YOUR_USERNAME/.composer/vendor/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
}
}
}
}
```
**Option B: Manual Configuration (Global)**
Add to `~/.claude.json` under the `mcpServers` key at root level:
```json
{
"mcpServers": {
"wpcs": {
"type": "stdio",
"command": "node",
"args": ["/Users/YOUR_USERNAME/.mcp-servers/wpcs-mcp-server/build/index.js"],
"env": {
"PATH": "/Users/YOUR_USERNAME/Library/Application Support/Herd/bin:/Users/YOUR_USERNAME/.composer/vendor/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
}
}
}
}
```
**Option C: Project-Level Configuration**
Add to `~/.claude.json` under a specific project:
```json
{
"projects": {
"/path/to/your/wordpress-project": {
"mcpServers": {
"wpcs": {
"type": "stdio",
"command": "node",
"args": ["/Users/YOUR_USERNAME/.mcp-servers/wpcs-mcp-server/build/index.js"],
"env": {
"PATH": "/Users/YOUR_USERNAME/Library/Application Support/Herd/bin:/Users/YOUR_USERNAME/.composer/vendor/bin:/usr/local/bin:/usr/bin:/bin"
}
}
}
}
}
}
```
### For Claude Desktop
**macOS** - Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"wpcs": {
"command": "node",
"args": ["/Users/YOUR_USERNAME/.mcp-servers/wpcs-mcp-server/build/index.js"],
"env": {
"PATH": "/Users/YOUR_USERNAME/Library/Application Support/Herd/bin:/Users/YOUR_USERNAME/.composer/vendor/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
}
}
}
}
```
**Windows** - Edit `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"wpcs": {
"command": "node",
"args": ["C:\\Users\\YOUR_USERNAME\\.mcp-servers\\wpcs-mcp-server\\build\\index.js"],
"env": {
"PATH": "C:\\php;C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\Composer\\vendor\\bin;%PATH%"
}
}
}
}
```
---
## PATH Configuration by Setup
Choose the correct PATH based on your PHP installation:
| PHP Setup | PATH Value |
|-----------|------------|
| **Herd (macOS)** | `~/Library/Application Support/Herd/bin:~/.composer/vendor/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin` |
| **Homebrew (macOS)** | `/opt/homebrew/opt/php@8.4/bin:~/.composer/vendor/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin` |
| **MAMP (macOS)** | `/Applications/MAMP/bin/php/php8.2.x/bin:~/.composer/vendor/bin:/usr/local/bin:/usr/bin:/bin` |
| **System PHP (Linux)** | `~/.composer/vendor/bin:/usr/local/bin:/usr/bin:/bin` |
| **Windows** | `C:\php;C:\Users\YOU\AppData\Roaming\Composer\vendor\bin` |
> **Important:** Replace `~` with your full home path (e.g., `/Users/yourname`) in JSON configs.
---
## Step 4: Verify Installation
```bash
# Check MCP server status
claude mcp list
# Should show:
# wpcs: node ~/.mcp-servers/wpcs-mcp-server/build/index.js - ✓ Connected
```
### Test the Server Manually
```bash
cd ~/.mcp-servers/wpcs-mcp-server
PATH="YOUR_PHP_PATH:$HOME/.composer/vendor/bin:$PATH" node build/index.js
# Should output:
# Starting WPCS MCP Server...
# phpcs path: /Users/you/.composer/vendor/bin/phpcs
# Available standards: ... WordPress, WordPress-Core, WordPress-Docs, WordPress-Extra, PHPCompatibility ...
# WPCS MCP Server running on stdio
```
---
## Available Tools
| Tool | What It Does |
|------|--------------|
| `wpcs_pre_commit` | **Most useful!** Auto-fix staged files, re-stage, report remaining issues |
| `wpcs_check_staged` | Check all staged PHP files before commit |
| `wpcs_check_file` | Check a single PHP file |
| `wpcs_check_directory` | Check all PHP files in a directory |
| `wpcs_fix_file` | Auto-fix WPCS violations in a file |
| `wpcs_check_php_compatibility` | Check PHP 8.1/8.2/8.3/8.4 compatibility |
---
## Usage Examples
Just ask Claude in natural language:
```
"Check my staged files for WPCS issues"
"Run wpcs_pre_commit before I commit"
"Fix WPCS issues in includes/class-my-plugin.php"
"Check the entire src/ directory for coding standards"
"Check PHP 8.2 compatibility for my plugin"
"Is my code compatible with PHP 8.1 to 8.4?"
```
### Typical Workflow
1. Write your WordPress plugin/theme code
2. Stage your changes: `git add .`
3. Ask Claude: **"Run wpcs_pre_commit"**
4. Claude will:
- Auto-fix what can be fixed (spacing, formatting, etc.)
- Re-stage the fixed files
- Report any remaining issues that need manual fixes
5. Commit your clean code!
---
## What WPCS Checks
The `WordPress` ruleset includes:
| Standard | What It Checks |
|----------|----------------|
| **WordPress-Core** | Naming conventions, spacing, formatting, PHP compatibility |
| **WordPress-Extra** | Discouraged functions, loose comparisons, Yoda conditions |
| **WordPress-Docs** | PHPDoc comments, inline documentation |
### Common Issues It Catches:
- ❌ `if($x == true)` → ✅ `if ( true === $x )`
- ❌ Missing spaces in function calls
- ❌ Using `extract()`, `eval()`, `create_function()`
- ❌ Missing or incorrect PHPDoc blocks
- ❌ Incorrect text domain in translations
- ❌ Direct database queries without preparation
---
## PHP Compatibility Checking
Check if your code works with PHP 8.1, 8.2, 8.3, and 8.4:
```
"Check PHP 8.2 compatibility for src/"
"Is my plugin compatible with PHP 8.1-8.4?"
```
### What It Detects:
| Issue Type | Example |
|------------|---------|
| **Removed Functions** | `create_function()` removed in PHP 8.0 |
| **Deprecated Features** | `${var}` string interpolation deprecated in 8.2 |
| **New Syntax** | Named arguments require PHP 8.0+ |
| **Type Changes** | Return type changes in built-in functions |
| **Removed Constants** | `FILTER_SANITIZE_STRING` removed in 8.1 |
### Version Examples:
```
"8.1" → Check for PHP 8.1 compatibility only
"8.2" → Check for PHP 8.2 compatibility only
"7.4-" → Check PHP 7.4 and all newer versions
"8.1-8.4" → Check PHP 8.1 through 8.4 compatibility
```
WordPress.org requires **PHP 7.4+** minimum, so use `"7.4-"` to ensure broad compatibility.
---
## Add Tool Permissions (Claude Code)
Add to `~/.claude/settings.json`:
```json
{
"permissions": {
"allow": [
"mcp__wpcs__wpcs_check_staged",
"mcp__wpcs__wpcs_check_file",
"mcp__wpcs__wpcs_check_directory",
"mcp__wpcs__wpcs_fix_file",
"mcp__wpcs__wpcs_pre_commit",
"mcp__wpcs__wpcs_check_php_compatibility"
]
}
}
```
---
## Optional: Auto-Check Before Commits
Add a Claude Code hook to automatically check WPCS before every commit.
Create `~/.claude/hooks/wpcs-pre-commit.sh`:
```bash
#!/bin/bash
export PATH="$HOME/.composer/vendor/bin:$PATH"
STAGED_PHP=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.php$' || true)
if [ -z "$STAGED_PHP" ]; then
exit 0
fi
PHP_COUNT=$(echo "$STAGED_PHP" | wc -l | tr -d ' ')
echo "WPCS: Found $PHP_COUNT staged PHP file(s). Run wpcs_pre_commit to check."
exit 0
```
Add to `~/.claude/settings.json`:
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash(git commit*)",
"hooks": [
{
"type": "command",
"command": "bash \"$HOME/.claude/hooks/wpcs-pre-commit.sh\""
}
]
}
]
}
}
```
---
## Troubleshooting
### "Failed to connect" in `claude mcp list`
**Most common cause:** Wrong PHP version in PATH.
```bash
# Check which PHP the MCP server sees
cd ~/.mcp-servers/wpcs-mcp-server
PATH="YOUR_CONFIG_PATH" node build/index.js 2>&1 | head -5
# If you see "PHP Fatal error: Composer detected issues... require PHP >= 8.2"
# Your PATH doesn't include PHP 8.2+
```
**Fix:** Update the PATH in your MCP config to include your PHP 8.2+ binary directory FIRST.
### "phpcs not found"
```bash
# Install manually
composer global config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer global require squizlabs/php_codesniffer wp-coding-standards/wpcs phpcompatibility/phpcompatibility-wp dealerdirect/phpcodesniffer-composer-installer
# Verify
~/.composer/vendor/bin/phpcs --version
```
### "WordPress standard not found"
```bash
# Check available standards
~/.composer/vendor/bin/phpcs -i
# If WordPress not listed, reinstall:
composer global remove wp-coding-standards/wpcs dealerdirect/phpcodesniffer-composer-installer
composer global require wp-coding-standards/wpcs dealerdirect/phpcodesniffer-composer-installer
```
### Build fails with "tsc: command not found"
```bash
cd ~/.mcp-servers/wpcs-mcp-server
rm -rf node_modules
npm install --include=dev
npm run build
```
### "Auto-install failed" on server startup
This happens when:
1. PHP version is too old (need 8.2+)
2. Composer version is too old (need 2.0+)
3. Network issues
**Fix:** Install dependencies manually (see Step 2 above).
### MCP server not loading in Claude Desktop
1. Verify the path in your config uses absolute paths (no `~`)
2. Ensure you ran `npm run build`
3. Restart Claude Desktop completely (quit and reopen)
4. Check the path exists: `ls -la ~/.mcp-servers/wpcs-mcp-server/build/index.js`
---
## Development
```bash
git clone https://github.com/vapvarun/wpcs-mcp-server.git
cd wpcs-mcp-server
npm install --include=dev
npm run build
# Watch mode for development
npm run dev
```
---
## Complete Setup Checklist
Use this checklist to ensure everything is configured correctly:
- [ ] **Node.js 18+** installed (`node -v`)
- [ ] **PHP 8.2+** installed and in PATH (`php -v`)
- [ ] **Composer 2.0+** installed (`composer -V`)
- [ ] **Repository cloned** to `~/.mcp-servers/wpcs-mcp-server`
- [ ] **Built with dev dependencies** (`npm install --include=dev && npm run build`)
- [ ] **WPCS installed globally** via Composer
- [ ] **phpcs shows WordPress standards** (`~/.composer/vendor/bin/phpcs -i`)
- [ ] **MCP config added** to `~/.claude.json` or Claude Desktop config
- [ ] **PATH includes PHP binary directory** in MCP env config
- [ ] **PATH includes composer/vendor/bin** in MCP env config
- [ ] **Server shows Connected** (`claude mcp list`)
---
## License
GPL-2.0-or-later
## Author
**Varun Dubey** ([@vapvarun](https://github.com/vapvarun))
- Website: [wbcomdesigns.com](https://wbcomdesigns.com)
- Email: varun@wbcomdesigns.com
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Acknowledgments
- [WordPress Coding Standards](https://github.com/WordPress/WordPress-Coding-Standards)
- [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer)
- [Model Context Protocol](https://modelcontextprotocol.io/)
