📑 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

💡 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:

composer global require phpstan/phpstan

npm install @cfworker/json-schema

🔒 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.