Rector

MCP server providing tools to query and filter Rector PHP refactoring rules.

Installation

Quick Start (No Installation Required)

Run the MCP Rector server directly from GitHub Packages:

npx @vasilvestre/mcp-rector

To use a specific version:

npx @vasilvestre/[email protected]

Global Installation

For permanent installation:

npm install -g @vasilvestre/mcp-rector
mcp-rector

Development Setup

For local development:

npm install
npm run build

Configuration for MCP Clients

Claude Desktop (Anthropic)

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "rector": {
      "command": "npx",
      "args": ["-y", "@vasilvestre/mcp-rector"]
    }
  }
}

For a specific version (e.g., 1.0.0):

{
  "mcpServers": {
    "rector": {
      "command": "npx",
      "args": ["-y", "@vasilvestre/[email protected]"]
    }
  }
}

After updating the config, restart Claude Desktop to activate the MCP server.

Cline (VS Code Extension)

Add to your Cline MCP settings:

1. Open VS Code Settings (Cmd/Ctrl + ,)
2. Search for "Cline: MCP Settings"
3. Edit settings.json:

{
  "cline.mcpServers": {
    "rector": {
      "command": "npx",
      "args": ["-y", "@vasilvestre/mcp-rector"]
    }
  }
}

Alternatively, use the Cline MCP Settings UI to add the server.

Continue.dev (VS Code/JetBrains Extension)

Add to Continue configuration at ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "rector",
      "command": "npx",
      "args": ["-y", "@vasilvestre/mcp-rector"]
    }
  ]
}

Zed Editor

Add to your Zed settings at ~/.config/zed/settings.json:

{
  "context_servers": {
    "rector": {
      "command": {
        "path": "npx",
        "args": ["-y", "@vasilvestre/mcp-rector"]
      }
    }
  }
}

Using Globally Installed Package

If you prefer a global installation instead of npx:

npm install -g @vasilvestre/mcp-rector

Then configure with direct command:

{
  "mcpServers": {
    "rector": {
      "command": "mcp-rector"
    }
  }
}

Verifying Configuration

After configuring your MCP client:

1. Restart the application
2. Check for "mcp-rector" in available tools/context
3. Look for tools: list-rector-rules, filter-rector-rules, search-rector-rules

Testing Locally with MCP Inspector

The MCP Inspector is a developer tool for testing MCP servers locally before integrating them with clients.

Install Inspector

npx @modelcontextprotocol/inspector

Run the Server with Inspector

npx @modelcontextprotocol/inspector npx -y @vasilvestre/mcp-rector

This will:

1. Start the MCP Inspector UI in your browser
2. Connect to your mcp-rector server
3. Allow you to test all available tools interactively

Using the Inspector

The Inspector provides:

• Tools tab: View and test all registered tools (list-rector-rules, search-rector-rules, etc.)
• Request/Response panels: See the full MCP protocol messages
• Interactive testing: Call tools with custom parameters and see results immediately

Example test flow:

1. Open the Inspector
2. Navigate to the Tools tab
3. Select list-rector-rules
4. Add optional parameters (e.g., {"ruleSet": "naming"})
5. Click "Run" to see the results

Available Tools

list-rector-rules

List all available Rector rules with optional filtering by rule set.

Parameters:

• ruleSet (optional): Filter rules by rule set category (e.g., "php80", "code-quality")

search-rector-rules

Search Rector rules by keyword with multi-word query support.

Parameters:

• query (required): Search keyword or multi-word phrase (e.g., "rename class")
• ruleSet (optional): Filter results by rule set category

Features:

• Multi-word tokenized search: "rename class" matches "RenameClass"
• Searches across rule names, descriptions, and tags
• Results sorted by relevance (name matches first, then description, then tags)

Examples:

• {"query": "rename class"} → Finds RenameClass, RenameClassConstFetch, etc.
• {"query": "type declaration"} → Finds AddParamTypeDeclaration, ReturnTypeDeclaration, etc.
• {"query": "php80", "ruleSet": "php80"} → Searches within PHP 8.0 rule set only

filter-rector-rules

Filter rules by rule set category.

Parameters:

• ruleSet (required): Rule set name to filter by (case-insensitive)

Additional tools documented in specs/001-list-rector-rules/

Development

npm run build      # Build TypeScript to build/
npm test           # Run tests
npm run test:watch # Run tests in watch mode

Troubleshooting

npx command not found

Ensure Node.js 18+ and npm are installed:

node --version  # Should be >= 18.0.0
npm --version

Permission denied errors (Unix/Linux)

The package should handle permissions automatically. If issues persist, try:

npx --yes mcp-rector

Network/registry errors

Check npm registry connectivity:

npm ping

Clear npx cache

If experiencing issues with cached versions, clear the npx cache:

rm -rf ~/.npm/_npx

Windows execution issues

On Windows, you may need to adjust PowerShell execution policy:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser