WPCS MCP Server

WPCS MCP服务器

一个模型上下文协议（MCP）服务器，将WordPress编码标准（WPCS）与Claude AI集成在一起。自动检查并修复您的WordPress插件/主题代码，以满足WordPress.org标准。

不使用Claude AI？ 没问题！看 礼品挂钩套装.md 用于独立的Git挂钩、GitHub操作和CI/CD设置。

单行安装（仅Git挂钩）

用于对每次提交进行自动WPCS检查 没有克劳德AI:

curl -sSL https://raw.githubusercontent.com/vapvarun/wpcs-mcp-server/main/scripts/install-hooks.sh | bash

这将安装phpcs+WPCS+PHP兼容性，并在当前仓库中设置预提交挂钩。

______________________________________________________________________

为什么使用这个？

如果你正在开发WordPress插件或主题，你的代码必须遵循 WordPress编码标准 致：

• ✅ 在WordPress.org插件/主题目录中获得批准
• ✅ 编写一致、可读的代码
• ✅ 遵循安全最佳实践
• ✅ 使您的代码易于维护

此MCP服务器允许Claude AI在您提交之前根据WPCS自动检查和修复您的PHP代码。

______________________________________________________________________

需求检查表

安装前，请确保满足所有要求：

按平台设置PHP

macOS with Laravel Herd (Recommended)

# 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

macOS with Homebrew

# 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

macOS with MAMP

# 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"

Windows

# Install via Chocolatey
choco install php --version=8.4

# Or download from php.net and add to PATH

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install php8.2 php8.2-cli composer

______________________________________________________________________

快速开始

步骤1：克隆和构建

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

重要提示： 使用 npm install --include=dev 以确保TypeScript编译器可用于构建。

步骤2：安装WPCS依赖项

服务器尝试自动安装，但为了确保可靠性，请手动安装：

# 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

步骤3：配置MCP服务器

选择您的设置方法：

______________________________________________________________________

配置选项

适用于Claude Code CLI（推荐）

选项A：使用CLI命令（全局）

claude mcp add wpcs --scope user -- node ~/.mcp-servers/wpcs-mcp-server/build/index.js

然后在中手动添加PATH环境 ~/.claude.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"
      }
    }
  }
}

选项B：手动配置（全局）

添加 ~/.claude.json 在...之下 mcpServers 根级别的密钥：

{
  "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"
      }
    }
  }
}

选项C：项目级配置

添加 ~/.claude.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"
          }
        }
      }
    }
  }
}

适用于克劳德桌面

macOS -编辑 ~/Library/Application Support/Claude/claude_desktop_config.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"
      }
    }
  }
}

视窗 -编辑 %APPDATA%\Claude\claude_desktop_config.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

根据您的PHP安装选择正确的PATH：

重要提示： 替换 ~ 使用您的完整回家路线（例如。， /Users/yourname)在JSON配置中。

______________________________________________________________________

步骤4：验证安装

# Check MCP server status
claude mcp list

# Should show:
# wpcs: node ~/.mcp-servers/wpcs-mcp-server/build/index.js - ✓ Connected

手动测试服务器

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

______________________________________________________________________

可用工具

______________________________________________________________________

使用示例

用自然语言问克劳德：

"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?"

典型工作流程

1. 编写WordPress插件/主题代码
2. 进行更改： git add .
3. 问克劳德： “运行wpcs_pre_commit”
4. 克劳德将：

- 自动修复可以修复的内容（间距、格式等） - 重新暂存已修复的文件 - 报告任何需要手动修复的遗留问题

1. 提交你的干净代码！

______________________________________________________________________

WPCS检查什么

这 WordPress 规则集包括：

常见问题：

• ❌ if($x == true) → ✅ if ( true === $x )
• ❌ 函数调用中缺少空格
• ❌ 使用 extract(), eval(), create_function()
• ❌ 缺少或不正确的PHPDoc块
• ❌ 翻译中的文本域不正确
• ❌ 无需准备即可直接查询数据库

______________________________________________________________________

PHP兼容性检查

检查您的代码是否适用于PHP 8.1、8.2、8.3和8.4：

"Check PHP 8.2 compatibility for src/"
"Is my plugin compatible with PHP 8.1-8.4?"

它检测到什么：

版本示例：

"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需要 PHP 7.4+ 最小，所以使用 "7.4-" 以确保广泛的兼容性。

______________________________________________________________________

添加工具权限（Claude代码）

添加 ~/.claude/settings.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"
    ]
  }
}

______________________________________________________________________

可选：提交前自动检查

添加一个Claude Code挂钩，以便在每次提交之前自动检查WPCS。

创建 ~/.claude/hooks/wpcs-pre-commit.sh:

#!/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

添加 ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$HOME/.claude/hooks/wpcs-pre-commit.sh\""
          }
        ]
      }
    ]
  }
}

______________________________________________________________________

故障排除

中的“连接失败” claude mcp list

最常见的原因： PATH中的PHP版本错误。

# 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+

修复： 更新MCP配置中的PATH，以包含PHP 8.2+二进制目录FIRST。

“未找到phpcs”

# 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标准”

# 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

生成失败，并显示“tsc:找不到命令”

cd ~/.mcp-servers/wpcs-mcp-server
rm -rf node_modules
npm install --include=dev
npm run build

服务器启动时“自动安装失败”

当发生以下情况时，会发生这种情况：

1. PHP版本太旧（需要8.2+）
2. 作曲家版本太旧（需要2.0+）
3. 网络问题

修复： 手动安装依赖项（请参阅上面的步骤2）。

MCP服务器未加载到Claude Desktop中

1. 验证配置中的路径是否使用绝对路径（否 ~)
2. 确保你跑了 npm run build
3. 完全重新启动Claude Desktop（退出并重新打开）
4. 检查路径是否存在： ls -la ~/.mcp-servers/wpcs-mcp-server/build/index.js

______________________________________________________________________

发展

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

______________________________________________________________________

完成安装检查表

使用此检查表确保所有配置正确：

• \[ \] Node.js 18+ 已安装(node -v)
• \[ \] PHP 8.2+ 已安装并位于PATH中(php -v)
• \[ \] 作曲家2.0+ 已安装(composer -V)
• \[ \] 已克隆存储库 到 ~/.mcp-servers/wpcs-mcp-server
• \[ \] 基于开发依赖性构建 (npm install --include=dev && npm run build)
• \[ \] WPCS在全球范围内安装 通过作曲家
• \[ \] phpcs显示WordPress标准 (~/.composer/vendor/bin/phpcs -i)
• \[ \] 已添加MCP配置 到 ~/.claude.json 或Claude桌面配置
• \[ \] PATH包含PHP二进制目录 在MCP环境配置中
• \[ \] PATH包括作曲家/供应商/bin 在MCP环境配置中
• \[ \] 服务器显示已连接 (claude mcp list)

______________________________________________________________________

许可证

GPL-2.0或更高版本

作者

瓦伦·杜贝 (@vapvarun)

• 网站： wbcomdesigns.com
• 电子邮件：varun@wbcomdesigns.com

贡献

欢迎投稿！请随时提交拉取请求。

致谢

• WordPress编码标准
• PHP_CodeSniffer
• 模型上下文协议