# Phpactor MCP Server

MCP server that wraps [Phpactor](https://phpactor.readthedocs.io/en/master/) 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:

| Tool | Description |
|---|---|
| `phpactor_index_build` | Build/rebuild project index (prerequisite for other tools) |
| `phpactor_find_references` | Find all semantic references to a class or member |
| `phpactor_rename_class` | Rename class + update ALL references project-wide |
| `phpactor_rename_member` | Rename method/property/constant project-wide |
| `phpactor_move_class` | Move class to new file/namespace + update references |
| `phpactor_class_info` | Query class info (implements, implementations) |

See [docs/spec.md](docs/spec.md) for full specification.

## Prerequisites

- **Node.js** >= 18
- **Phpactor** installed and available in PATH (or set `PHPACTOR_BIN` env var)
  ```bash
  # 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`:

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

Then run `composer dump-autoload`.

## Install

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

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

### From source (development)

```bash
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`):

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

Optionally set `PHPACTOR_BIN` if Phpactor is not in PATH:

```json
{
  "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

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

## Development

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