🐘 phpustik — MCP Server for PHP

AI'nin PHP gözü, kulağı ve eli olacak.

MCP Sunucusu · Tek npx ile AI asistanınıza PHP runtime, statik analiz, güvenlik taraması, test koşucusu, Composer ve framework entegrasyonu kazandırır.

🏷️ MCP Server | PHP Tools | AI Integration | Static Analysis | Composer | Laravel | Symfony
"The bridge between AI assistants and the PHP ecosystem."

Production-grade MCP server that gives AI assistants deep visibility into the entire PHP ecosystem — runtime, linting, static analysis, security, testing, Composer and framework tools.
Works with Claude Desktop, Cursor, Claude Code, Opencode, Cline and any MCP-compatible client.

A Model Context Protocol server for PHP — written in TypeScript, shipped as a single npx-able package, battle-tested on Windows, macOS and Linux.
🎯 Vision: Make every AI assistant a PHP expert — no Config, no Setup, just npx phpustik.

Features · Installation · Usage · Tools · Resources · Prompts · Integrations

📑 Table of contents

• Why phpustik?

• What's inside

• Features

• Architecture

• Prerequisites

• Installation

• Usage

• Tools — 31 tools in 9 categories

• Resources — 8 read-only data sources

• Prompts — 7 pre-baked workflows

• Integrations

• Configuration

• Troubleshooting

• Security

• Roadmap

• Contributing

• License

Related MCP server: Xdebug MCP Server

💡 Why phpustik?

AI assistants like Cursor, Claude Desktop, Claude Code and Opencode are increasingly good at writing PHP, but they remain blind to the runtime they target:

• They don't know which PHP version is installed.

• They cannot run php -l to catch a missing semicolon.

• They cannot invoke PHPStan, Psalm, PHP-CS-Fixer, PHPUnit, Rector, PHPMD, PHPCS…

• They cannot manage Composer packages, audit security, or detect the framework.

• They cannot run Laravel artisan or Symfony console commands.

phpustik closes that gap. It is a self-contained MCP server that exposes 31 tools, 8 resources and 7 prompts to the model — across runtime, static analysis, security, testing, refactoring, dependency management and framework integration.

It is:

• Production-ready — strict TypeScript, no any, exhaustive error handling, structured logs.

• Cross-platform — Windows, macOS, Linux, WSL. Path handling is normalised centrally.

• Safe by default — execFile (no shell), deterministic timeouts, output capping, isError: true on every failure.

• Honest — if a binary is missing, the model is told exactly which command to run.

📦 What's inside

✨ Features

🩺 Killer features

phpustik_doctor — one-shot health check

A single tool call that runs the entire PHP quality pipeline and produces a prioritised Markdown + JSON report.

{
  "tool": "phpustik_doctor",
  "arguments": {
    "category": "all",
    "failOn": "high",
    "skipTests": false,
    "fix": false,
    "json": false
  }
}

• Runs composer validate, composer audit, analyze_php_code, run_phpcs, run_phpmd, run_phpunit, scan_secrets, scan_vulnerable_functions, scan_sql_injection, scan_xss, check_php_compatibility, suggest_refactoring, get_php_ini, detect_framework, get_php_info — in order, with progress notifications.

• Returns a unified Markdown report plus a typed DoctorReport structured content (overall status, per-check severity, fixable count, recommendations).

• failOn lets the model or CI fail at a configurable severity threshold.

• json: true mode for CI pipelines (returns only the structured content).

• category: security|quality|style to run a targeted subset.

phpustik_init — project bootstrap

Generates optimal config files for a PHP project, tailored to its framework and PHP version.

{
  "tool": "phpustik_init",
  "arguments": {
    "dryRun": true,
    "force": false,
    "phpstanLevel": "5",
    "psalmLevel": "4",
    "phpVersions": "8.1,8.2,8.3,8.4"
  }
}

• Detects composer.json, composer.lock, framework, PHP version.

• Generates up to 11 config files: phpstan.neon, psalm.xml, .php-cs-fixer.php, rector.php, phpmd.xml, phpcs.xml, phpunit.xml, .editorconfig, .gitattributes, .github/workflows/ci.yml, bin/pre-commit.

• All templates hand-tuned for low false-positive rate, modern PHP, PSR-12 + strict types.

• dryRun: true (default) shows a unified diff without touching disk.

• force: true overwrites existing files; default is "keep what's there".

• only: "phpstan.neon,phpunit.xml" restricts to a subset.

🏗 Architecture

┌──────────────────────┐    JSON-RPC over stdio    ┌────────────────────────────────────────┐
│   MCP client         │  ◀────────────────────▶   │              phpustik server           │
│ (Cursor / Claude /   │                          │            (TypeScript, ESM)            │
│  Opencode / Cline)   │                          │                                        │
└──────────────────────┘                          │  33 tools │ 8 resources │ 7 prompts    │
                                                   └──────────────────┬─────────────────────┘
                                                                      │
        ┌──────────────────────────┬────────────────────────────┬──┴─────────────────────────────┐
        │                          │                            │                                │
        ▼                          ▼                            ▼                                ▼
   ┌────────┐  ┌────────┐  ┌────────────┐  ┌────────────┐  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐
   │  php   │  │ composer│ │  phpstan / │  │  phpcs /   │  │  rector /    │  │  laravel /   │  │  pattern    │
   │  -v -m │  │  *      │ │  psalm /   │  │  phpmd /   │  │  insights /  │  │  symfony     │  │  scanner    │
   │  -l -i │  │         │ │  phpmnd    │  │  phpcpd    │  │  phpcpd      │  │  console     │  │  (secrets,  │
   │  -r    │  │         │ │            │  │            │  │              │  │              │  │  SQLi, XSS) │
   └────────┘  └────────┘  └────────────┘  └────────────┘  └──────────────┘  └──────────────┘  └─────────────┘

Source layout

src/
├── index.ts                 # entry point
├── server.ts                # bootstrap (tools + resources + prompts)
├── constants.ts             # binary names, install hints, timeouts
├── prompts.ts               # 7 MCP prompts
├── resources.ts             # 8 MCP resources
├── tools/
│   ├── get-php-info.ts
│   ├── lint-php-file.ts
│   ├── analyze-php-code.ts
│   ├── format-php-code.ts
│   ├── run-php-script.ts
│   ├── show-opcache-status.ts
│   ├── get-extension-info.ts
│   ├── get-php-ini.ts
│   ├── check-php-compatibility.ts
│   ├── run-phpunit.ts
│   ├── run-psalm.ts
│   ├── run-phpmd.ts
│   ├── run-phpcs.ts
│   ├── run-phpmnd.ts
│   ├── run-phpcpd.ts
│   ├── run-phpinsights.ts
│   ├── run-rector.ts
│   ├── composer.ts          # 9 composer_* tools
│   ├── scan-security.ts     # 4 scan_* tools
│   ├── codegen.ts           # add_strict_types, generate_phpdoc, suggest_refactoring
│   ├── framework.ts         # detect + Laravel + Symfony tools
│   ├── doctor.ts            # phpustik_doctor
│   └── init.ts              # phpustik_init
└── utils/
    ├── executor.ts          # execFile wrapper, no shell, timeouts
    ├── paths.ts             # cross-platform path normalisation
    ├── logger.ts            # stderr-only structured logger
    ├── responses.ts         # uniform MCP tool responses
    ├── workspace.ts         # project root auto-detection
    ├── framework-detector.ts
    ├── patterns.ts          # secrets / SQLi / XSS / vuln-func catalogues
    ├── scan-runner.ts       # pattern-scan engine
    ├── file-scanner.ts      # FS walker with skips
    ├── cache.ts             # TTL cache
    ├── active-ops.ts        # AbortController registry for cancellation
    ├── notification-sink.ts # MCP logging/progress bridge
    └── config-templates.ts  # init tool generators

✅ Prerequisites

All of these are optional — phpustik will tell you which to install when a tool needs a missing binary.

Quick check

node -v     # v20 or higher
php -v      # PHP 8.0 or higher
composer --version

🛠 Installation

1. Install PHP

2. Install Composer

# macOS / Linux / WSL
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

# Windows (PowerShell)
Invoke-WebRequest https://getcomposer.org/installer -OutFile composer-setup.php
php composer-setup.php
Move-Item composer.phar C:\Program Files\composer\composer.exe

3. Install all PHP tools (optional but recommended)

composer global require \
    phpstan/phpstan \
    vimeo/psalm \
    phpmd/phpmd \
    squizlabs/php_codesniffer \
    povils/phpmnd \
    sebastianbergmann/phpcpd \
    nunomaduro/phpinsights \
    rector/rector \
    friendsofphp/php-cs-fixer \
    phpcompatibility/php-compatibility

Make sure ~/.composer/vendor/bin (Linux/macOS) or %USERPROFILE%\Composer\vendor\bin (Windows) is on your PATH.

4. Install phpustik

# Option A: run on demand
npx -y phpustik

# Option B: install globally
npm install -g phpustik
phpustik

🚀 Usage

Quick start with npx

npx -y phpustik

You'll see on stderr:

[INFO] server.boot {"name":"phpustik","version":"1.0.0"}
[INFO] server.php_detected {"version":"PHP 8.3.6 (cli)"}
[INFO] server.ready {"transport":"stdio"}

Local development

git clone https://github.com/halitartuc/phpustik.git
cd phpustik
npm install
npm run dev          # tsx, no build

Inspect with the MCP Inspector

npm run inspect

This opens a local web UI where you can call every tool by hand.

🛠 Tools (33)

All tools accept JSON Schema (Zod-validated) input and return MCP text content (and, where useful, a typed structuredContent companion). Tools marked ⚠️ are destructive (they modify the filesystem). Tools marked 🔒 require project-level configuration.

🔍 PHP Runtime & Environment (5)

🧪 Linting, Formatting & Syntax (4)

📐 Static Analysis (6)

🛠 Refactoring & Codegen (3)

▶️ Execution & Testing (2)

📦 Composer (9)

🔐 Security (4)

🏗 Framework Integration (7)

🚀 Meta-tools (2)

📚 Resources (8)

Resources are server-side data the model can read on demand to enrich its context. No parameters required.

💬 Prompts (7)

Prompts are pre-baked, parameterised workflows the model can invoke.

🔌 Integrations

The server speaks stdio MCP — any client that supports MCP can use it.

Cursor

Settings → MCP → + Add new global MCP server:

{
  "mcpServers": {
    "phpustik": {
      "command": "npx",
      "args": ["-y", "phpustik"]
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "phpustik": {
      "command": "npx",
      "args": ["-y", "phpustik"]
    }
  }
}

Claude Code (CLI)

claude mcp add phpustik -- npx -y phpustik
claude mcp list

Opencode

~/.config/opencode/mcp.json:

{
  "mcpServers": {
    "phpustik": {
      "command": "npx",
      "args": ["-y", "phpustik"]
    }
  }
}

Cline / Continue.dev

.vscode/cline_mcp_settings.json:

{
  "mcpServers": {
    "phpustik": { "command": "npx", "args": ["-y", "phpustik"] }
  }
}

⚙️ Configuration

All via env vars. Everything has a sensible default.

🧯 Troubleshooting

Common issues & fixes:

• Make sure the MCP client config is valid JSON. Trailing commas break it.

• Restart the MCP client after editing the config.

• Run the server manually: npx -y phpustik. If it crashes, the issue is server-side.

composer global require phpstan/phpstan

Make sure ~/.composer/vendor/bin is on your PATH. Restart the terminal and the MCP client.

Add C:\php to Path in System Environment Variables, then restart the terminal and the MCP client.

The server sends logs to stderr and protocol frames to stdout. If your client shows nothing, set PHPUSTIK_LOG_LEVEL=debug and check its log panel.

npm install @cfworker/json-schema

It's a peer dep of the MCP SDK v2 alpha.

🔒 Security

• No shell: true. Every command runs through execFile — arguments are never parsed as shell.

• Every tool input goes through Zod validation before any IO.

• File-system access is read-only by default. Destructive tools are clearly marked ⚠️.

• Output buffers are capped at 1 MiB per stream.

• File contents are never logged — only paths and metadata.

Please report security issues privately — see SECURITY.md.

🗺 Roadmap

• php -S managed dev server tool

• phpdbg interactive debugging

• php -d ini override preview

• Docker image: phpustik/phpustik:latest with every tool pre-installed

• HTTP/SSE transport for remote deployments

• VS Code extension proxy

• GitHub Actions annotation output for CI integration

🤝 Contributing

See CONTRIBUTING.md. Run npm run lint && npm run typecheck && npm run build before opening a PR.

📄 License

MIT — © 2024-2026 phpustik contributors.

🙏 Acknowledgements

• The Model Context Protocol team for the spec and SDK.

• PHPStan, Psalm, PHPMD, PHPCS, Rector, PHP Insights and PHP-CS-Fixer — every PHP tool that makes this server possible.

• Composer for dependency management.

• Everyone who ⭐️s, opens issues or sends PRs.

Made with ❤️ for the PHP + AI community.