MCP PHPCS Server

Servidor MCP PHPCS

Um servidor Model Context Protocol que traz o PHP_CodeSniffer para o seu fluxo de trabalho de codificação com IA — verifica PHP de acordo com o seu padrão de codificação e corrige violações automaticamente, direto de qualquer cliente MCP.

Implementado em PHP puro, sem dependências do Composer. Adicione-o a qualquer projeto ou execute-o de forma independente — ele fala JSON-RPC 2.0 via stdio e funciona com Claude Desktop, Claude Code, Cursor e qualquer outro cliente compatível com MCP.

Ferramentas

Ferramenta	Descrição
phpcs_check	Executa o PHP_CodeSniffer em um arquivo ou diretório e retorna um relatório legível das violações.
phpcbf_fix	Executa o PHP Code Beautifier and Fixer (phpcbf) para corrigir automaticamente violações corrigíveis.

Ambas as ferramentas recebem um único path obrigatório (arquivo/diretório com caminho absoluto ou relativo ao projeto).

Requisitos

• PHP 8.1+
• Binários phpcs e phpcbf disponíveis (via PHP_CodeSniffer, por exemplo, o vendor/bin de um projeto ou uma instalação global)

Início rápido

1. Clone o repositório (ou copie-o para o seu projeto):

   git clone https://github.com/larspohlmann/mcp-phpcs-server.git
   

2. Torne o ponto de entrada executável:

   chmod +x mcp-phpcs-server/bin/mcp-phpcs
   

3. Registre-o no seu cliente MCP (veja abaixo).

Configuração

Configure por meio de variáveis de ambiente ou config/config.json. As variáveis de ambiente têm precedência.

Variável	Chave config.json	Descrição	Padrão
MCP_PHPCS_PATH	phpcsPath	Caminho para o binário phpcs	phpcs no PATH
MCP_PHPCBF_PATH	phpcbfPath	Caminho para o binário phpcbf	phpcbf no PATH
MCP_PHPCS_RULESET	rulesetPath	Caminho para um ruleset de padrão de codificação	descoberto automaticamente

Se nenhum ruleset for fornecido, o servidor busca para cima a partir do diretório de trabalho atual por um dos seguintes: phpcs.xml, phpcs.xml.dist ou ruleset.xml.

Configuração do cliente

Claude Desktop / Claude Code

Adicione o servidor à sua configuração MCP:

{
  "mcpServers": {
    "phpcs": {
      "command": "/absolute/path/to/mcp-phpcs-server/bin/mcp-phpcs",
      "env": {
        "MCP_PHPCS_PATH": "/usr/local/bin/phpcs",
        "MCP_PHPCBF_PATH": "/usr/local/bin/phpcbf",
        "MCP_PHPCS_RULESET": "/path/to/your/phpcs.xml"
      }
    }
  }
}

Depois, peça ao seu assistente algo como "Execute o phpcs em src/Service/UserService.php e corrija o que puder."

Exemplo de chamada de ferramenta

{
  "name": "phpcs_check",
  "arguments": { "path": "src/Service/UserService.php" }
}

Arquitetura

O servidor segue uma estrutura leve de Domain-Driven Design:

• src/Domain — contratos de ferramentas e objetos de valor de resultado
• src/Application — servidor MCP JSON-RPC e registro de ferramentas
• src/Infrastructure — executor de processos, configuração, descoberta de rulesets, implementações de ferramentas
• bin/mcp-phpcs — ponto de entrada stdio

Ele implementa os métodos MCP initialize, tools/list e tools/call.

Observações

• O STDOUT transporta apenas mensagens JSON-RPC; todos os logs vão para o STDERR.
• Um código de saída diferente de zero do phpcs significa que foram encontradas violações — isso é relatado como descobertas, não tratado como erro fatal.

Licença

MIT