Phpactor MCP Server

MCP server that wraps Phpactor to provide project-wide semantic PHP refactoring tools for AI assistants (Claude Code, etc.).

What it does

Exposes 6 tools that require Phpactor's type-aware engine — things a text-based AI cannot reliably do with grep:

See docs/spec.md for full specification.

Related MCP server: MCP Python Code Navigation Server

Prerequisites

• Node.js >= 18

• Phpactor installed and available in PATH (or set PHPACTOR_BIN env var)

  # Install Phpactor (PHAR)
  curl -Lo phpactor https://github.com/phpactor/phpactor/releases/latest/download/phpactor.phar
  chmod +x phpactor
  mv phpactor ~/.local/bin/

• PHP >= 8.1

• A PHP project with Composer and PSR-4 autoload configured

Yii2 / non-PSR-4 projects

Phpactor requires PSR-4 autoload mappings. For Yii2 projects, add this to composer.json:

{
  "autoload": {
    "psr-4": {
      "common\\": "common/",
      "backend\\": "backend/",
      "frontend\\": "frontend/",
      "console\\": "console/",
      "modules\\": "modules/"
    }
  }
}

Then run composer dump-autoload.

Install

npm install -g @p4it-kft/phpactor-mcp

No build step needed — the package is published prebuilt to npm.

From source (development)

git clone https://github.com/p4it-kft/@p4it-kft/phpactor-mcp
cd @p4it-kft/phpactor-mcp
npm install
npm run build

Configure in Claude Code

Add to ~/.claude/settings.json (or project-level .claude/settings.json):

{
  "mcpServers": {
    "phpactor": {
      "command": "npx",
      "args": ["-y", "@p4it-kft/phpactor-mcp"]
    }
  }
}

Optionally set PHPACTOR_BIN if Phpactor is not in PATH:

{
  "mcpServers": {
    "phpactor": {
      "command": "npx",
      "args": ["-y", "@p4it-kft/phpactor-mcp"],
      "env": {
        "PHPACTOR_BIN": "/path/to/phpactor"
      }
    }
  }
}

Usage

Once configured, the tools are available to Claude. Typical workflow:

1. Build the index first — Claude calls phpactor_index_build with your project path

2. Use tools — find references, rename, move classes as needed

3. Rebuild index after significant file changes

Testing

# Run all integration tests (requires tmp/p4it-website test project)
bash test-phpactor.sh

Development

npm run dev    # Watch mode — recompiles on changes
npm run build  # One-time build