<div align="center">

🐘 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

</div>

---

📑 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

Category	Count	Examples
🛠 Tools	33	get_php_info, analyze_php_code, composer_audit, scan_secrets, laravel_routes, phpustik_doctor, phpustik_init
📚 Resources	8	php://info, phpustik://workspace, phpustik://composer-json
💬 Prompts	7	review_php_code, security_audit, upgrade_php
🧰 PHP tools wired	11	PHP, Composer, PHPStan, Psalm, PHPMD, PHPCS, PHPMND, Rector, PHP Insights, PHPCPD, PHPUnit
🚀 Killer features	2	phpustik_doctor (one-shot health check) + phpustik_init (project bootstrap)
📡 MCP v2 features	3	Logging notifications, progress reporting, cancellation

---

✨ Features

Area	What you get
MCP protocol	Implements McpServer with the v2 high-level registerTool API.
Transport	StdioServerTransport for first-class integration with every major MCP client.
Validation	Zod v4 input validation on every tool — invalid calls are rejected before any IO.
MCP logging	Real-time notifications/message updates while long tools run.
Progress	notifications/progress for multi-step operations (phpustik_doctor, phpustik_init).
Cancellation	AbortSignal-aware; long ops are tracked and can be killed if the user cancels.
Structured output	structuredContent on key tools — model iterates typed data, not Markdown tables.
Error UX	Friendly, actionable messages for missing binaries, timeouts, permission errors.
Cross-platform	POSIX, Windows, UNC, WSL, file:// and ~-prefixed paths accepted and normalised.
Security	No shell: true, no eval, capped output buffers, secrets never logged.
Observability	Stderr-only logger with PHPUSTIK_LOG_LEVEL (debug/info/warn/error).
Workspace-aware	Auto-detects project root from composer.json / phpstan.neon / artisan / bin/console.
Framework-aware	Auto-detects Laravel, Symfony, WordPress, CodeIgniter, Yii, Slim, Laminas, Phalcon, CakePHP.
Caching	TTL cache for expensive ops (composer info, phpstan, audits) — 60 s default.
Distribution	bin field + files whitelist → npm i -g phpustik or npx phpustik.
CI / Release	GitHub Actions matrix (3 OS × 3 Node versions), semantic-release.

---

🩺 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

Software	Minimum	Required for
Node.js	20.0 LTS	Running the MCP server
npm	10 (bundled)	Package manager (or pnpm/yarn)
PHP	8.0+	All PHP-runtime tools
Composer	2.x	composer_* tools
PHPUnit	10+	run_phpunit
PHPStan	1.x or 2.x	analyze_php_code (recommended)
Psalm	5+	run_psalm
PHPMD	2.x	run_phpmd
PHPCS	3.x	run_phpcs
PHPMND	3.x	run_phpmnd
Rector	1.x	run_rector
PHP Insights	2.x	run_phpinsights
PHPCPD	6+	run_phpcpd
PHP-CS-Fixer	3.x	format_php_code

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

OS	Command
macOS	brew install php
Ubuntu/Zorin	sudo apt-get install -y php-cli php-mbstring php-xml
Fedora	sudo dnf install -y php-cli
Alpine	sudo apk add php php-mbstring
Windows	Download from https://windows.php.net/download/ or winget install PHP.PHP.8.3

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)

Tool	Purpose
get_php_info	PHP sürümü, modüller, INI.
show_opcache_status	OPcache + JIT (PHP 8+) durumu.
get_extension_info	Tek bir eklentinin fonksiyon/sabit/INI detayı.
get_php_ini	Aktif php.ini, tarama dizini, direktifler.
check_php_compatibility	PHPCompatibility ile hedef PHP sürüm denetimi.

🧪 Linting, Formatting & Syntax (4)

Tool	Purpose
lint_php_file	php -l ile sözdizimi denetimi.
run_phpcs	PHP_CodeSniffer (PSR12, Squiz, vb.). fix=true ile otomatik düzeltme.
format_php_code	PHP-CS-Fixer (PSR-12) — dry-run veya apply.
add_strict_types	Dosyaya declare(strict_types=1); ekler.

📐 Static Analysis (6)

Tool	Purpose
analyze_php_code	PHPStan seviye 0–max.
run_psalm	Psalm seviye 1–8.
run_phpmd	Mess Detector (karmaşıklık, unused code, design).
run_phpmnd	Magic number tespiti.
run_phpcpd	Copy-paste tespiti.
run_phpinsights	Genel kod kalite skoru (Code / Architecture / Style / Complexity).

🛠 Refactoring & Codegen (3)

Tool	Purpose
run_rector	Otomatik refactoring — dryRun=true önizleme. ⚠️
generate_phpdoc	Eksik PHPDoc bloklarını raporlar.
suggest_refactoring	Uzun metod, god class, derin nesting heuristik önerileri.

▶️ Execution & Testing (2)

Tool	Purpose
run_php_script	İzole temp dosyada PHP kodu çalıştır. ⚠️
run_phpunit	PHPUnit testleri (filter, testdox, coverage).

📦 Composer (9)

Tool	Purpose
composer_info	Yüklü paketler / belirli paket bilgisi.
composer_validate	composer.json doğrulama.
composer_audit	Bilinen CVE taraması.
composer_outdated	Güncellenmesi gereken paketler.
composer_require	Paket ekle. ⚠️
composer_remove	Paket kaldır. ⚠️
composer_install	composer install. ⚠️
composer_update	composer update. ⚠️
composer_dump_autoload	composer dump-autoload.

🔐 Security (4)

Tool	Purpose
scan_secrets	Hardcoded API key, private key, token, basic-auth URL.
scan_vulnerable_functions	eval(), system(), unserialize(), weak hash, extract().
scan_sql_injection	Query string concatenation, whereRaw, DB::statement.
scan_xss	Unescaped echo $_GET, Blade {!! !!}, Twig `

🏗 Framework Integration (7)

Tool	Purpose
detect_framework	Laravel / Symfony / WordPress / … otomatik tespit.
laravel_artisan	php artisan <command> çalıştır. ⚠️
laravel_routes	Tüm route'lar (method, uri, name, action, middleware).
laravel_migrations	php artisan migrate:status.
symfony_console	bin/console <command>. ⚠️
symfony_container	debug:container ile servis listesi.

🚀 Meta-tools (2)

Tool	Purpose
phpustik_doctor	Tek çağrıda tüm kalite/güvenlik/test kontrollerini çalıştırır, priorize rapor döner.
phpustik_init	PHPStan / Psalm / Rector / phpcs / phpunit / .editorconfig / .gitattributes / CI workflow üretir.

---

📚 Resources (8)

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

URI	MIME	Description
phpustik://workspace	text/plain	Aktif proje özeti (root, config dosyaları).
phpustik://composer-json	application/json	composer.json içeriği.
phpustik://composer-extra	application/json	composer.json extra bloğu.
phpustik://php-version	text/plain	.php-version içeriği.
phpustik://framework	application/json	Tespit edilen framework + sürüm.
php://info	text/plain	php -i çıktısı (ilk 200 satır).
php://extensions	text/plain	php -m (yüklü eklentiler).
php://ini-loaded	application/json	Sistem + proje INI dosyaları.

---

💬 Prompts (7)

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

Prompt	Arguments	Purpose
review_php_code	filepath, focus	PSR-12, güvenlik ve performans review.
explain_php_code	filepath, depth	Satır satır kod açıklaması.
refactor_php_code	filepath, goal	Somut refactoring önerileri + değişiklik örnekleri.
write_phpunit_test	filepath, method?, coverage	PHPUnit testi üret.
write_pest_test	filepath, method?	Pest testi üret.
security_audit	path?	4'lü güvenlik taraması başlat.
upgrade_php	fromVersion, toVersion	PHP sürüm yükseltme yol haritası.

---

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

Variable	Default	Description
PHPUSTIK_LOG_LEVEL	info	debug / info / warn / error — stderr.
PHPUSTIK_CACHE_TTL	60000	Tool result cache TTL (ms).
PHPUSTIK_TIMEOUT_MS	30000	Default command timeout.
PHPUSTIK_PHPSTAN_BIN	phpstan	Override PHPStan binary path.
PHPUSTIK_PSALM_BIN	psalm	Override Psalm binary path.
PHPUSTIK_PHPCS_BIN	phpcs	Override PHPCS binary path.
PATH	—	The system PATH is used to find every PHP tool.

---

🧯 Troubleshooting

Common issues & fixes:

<details> <summary><strong>Server starts but the model reports "tool not found".</strong></summary>

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

</details>

<details> <summary><strong>"PHPStan / Psalm / PHPMD … bulunamadı" errors.</strong></summary>

composer global require phpstan/phpstan

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

</details>

<details> <summary><strong>Windows: "php is not recognized".</strong></summary>

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

</details>

<details> <summary><strong>The server exits silently with no log line.</strong></summary>

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.

</details>

<details> <summary><strong>@cfworker/json-schema missing.</strong></summary>

npm install @cfworker/json-schema

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

</details>

---

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

<div align="center">

Made with ❤️ for the PHP + AI community.

</div>