phpstan-mcp-mx 0.14.0 → 0.16.0

package/README.md

@@ -1,42 +1,45 @@
 # phpstan-mcp-mx
 
-Een MCP-server die [PHPStan](https://phpstan.org) ontsluit als tools voor Claude. Eén server
-bedient meerdere PHP-projecten tegelijk; welke dat zijn, leg je zelf vast.
+An MCP server that exposes [PHPStan](https://phpstan.org) as tools for Claude. One server
+serves several PHP projects at once; you decide which ones.
 
-## Installatie
+The server's own output — messages, tool descriptions, prompts and reports — is in Dutch.
+The examples below show that output verbatim, so you can recognise it when you see it.
 
-De server draait als los proces dat je MCP-client opstart. Installeer hem één keer globaal
-en meld hem daarna aan bij de client die je gebruikt — Claude Code en Claude Desktop houden
-elk hun eigen lijst bij, dus voor allebei doe je dat apart.
+## Installation
+
+The server runs as a separate process that your MCP client starts. Install it globally once
+and then register it with the client you use — Claude Code and Claude Desktop each keep their
+own list, so you do this separately for both.
 
 ```bash
 npm install -g phpstan-mcp-mx
 ```
 
-Vervang hieronder overal `/pad/naar/projecten` door de map waar je PHP-projecten in staan.
-Die is verplicht; zie [Configuratie](#configuratie) voor waarom.
+Below, replace `/path/to/projects` everywhere with the directory that holds your PHP
+projects. It is required; see [Configuration](#configuration) for why.
 
 ### Claude Code
 
-Met `--scope user` is de server in al je projecten beschikbaar — wat je wilt bij één server
-die meerdere projecten bedient.
+With `--scope user` the server is available in all your projects — which is what you want
+from one server that serves several projects.
 
 ```bash
 claude mcp add phpstan --scope user \
-  --env PHPSTAN_MCP_ROOTS=/pad/naar/projecten \
+  --env PHPSTAN_MCP_ROOTS=/path/to/projects \
   -- phpstan-mcp-mx
 ```
 
-Zonder globale installatie kan het ook rechtstreeks van de registry; dat kost wel elke
-sessiestart een npx-resolutie:
+Without a global installation you can also run it straight from the registry; that does cost
+an npx resolution at every session start:
 
 ```bash
 claude mcp add phpstan --scope user \
-  --env PHPSTAN_MCP_ROOTS=/pad/naar/projecten \
+  --env PHPSTAN_MCP_ROOTS=/path/to/projects \
   -- npx -y phpstan-mcp-mx
 ```
 
-Nagaan of het gelukt is:
+To check that it worked:
 
 ```bash
 claude mcp get phpstan
@@ -49,77 +52,77 @@ phpstan:
   Type: stdio
   Command: phpstan-mcp-mx
   Environment:
-    PHPSTAN_MCP_ROOTS=/pad/naar/projecten
+    PHPSTAN_MCP_ROOTS=/path/to/projects
 ```
 
-`claude mcp get` en `claude mcp list` verbinden echt met de server in plaats van alleen de
-configuratie terug te lezen — ze melden dus of hij ook daadwerkelijk start. Binnen een
-sessie doet `/mcp` hetzelfde. Vraag daarna om de projectenlijst: komt die leeg terug terwijl
-de verbinding staat, dan wijzen je roots naar de verkeerde map en is er niets mis met de
-server zelf.
+`claude mcp get` and `claude mcp list` actually connect to the server instead of just reading
+back the configuration — so they tell you whether it really starts. Inside a session, `/mcp`
+does the same. Then ask for the project list: if it comes back empty while the connection is
+up, your roots point to the wrong directory and there is nothing wrong with the server
+itself.
 
 ### Claude Desktop
 
-Desktop leest zijn servers uit `claude_desktop_config.json`:
+Desktop reads its servers from `claude_desktop_config.json`:
 
-| besturingssysteem | pad |
+| operating system | path |
 | --- | --- |
 | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
 | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
 | Linux | `~/.config/Claude/claude_desktop_config.json` |
 
-Bestaat dat bestand nog niet, maak het dan zelf aan:
+If that file doesn't exist yet, create it yourself:
 
 ```json
 {
   "mcpServers": {
     "phpstan": {
       "command": "phpstan-mcp-mx",
-      "env": { "PHPSTAN_MCP_ROOTS": "/pad/naar/projecten" }
+      "env": { "PHPSTAN_MCP_ROOTS": "/path/to/projects" }
     }
   }
 }
 ```
 
-Staat er al een `mcpServers`-blok, zet `phpstan` er dan naast in plaats van het bestand te
-vervangen — je overschrijft anders de servers die er al in staan.
+If there already is an `mcpServers` block, add `phpstan` next to the existing entries instead
+of replacing the file — otherwise you overwrite the servers that are already in it.
 
-Desktop leest dat bestand alleen bij het opstarten, en op macOS is het venster sluiten geen
-afsluiten: quit de app volledig (⌘Q) en start hem opnieuw. Daarna staat `phpstan` tussen de
-beschikbare tools in het gesprek.
+Desktop only reads that file at startup, and on macOS closing the window is not quitting:
+quit the app completely (⌘Q) and start it again. After that, `phpstan` shows up among the
+available tools in the conversation.
 
-Heb je Desktop al ingericht en wil je hetzelfde in Claude Code, dan neemt
-`claude mcp add-from-claude-desktop` die servers over (alleen macOS en WSL).
+If you have already set up Desktop and want the same in Claude Code,
+`claude mcp add-from-claude-desktop` copies those servers over (macOS and WSL only).
 
-Werkt het in je terminal wel maar in Desktop niet, ga dan meteen naar de volgende sectie:
-een GUI-app erft je shell-profiel niet, en dat is hier veruit de meest voorkomende oorzaak.
+If it works in your terminal but not in Desktop, go straight to the next section: a GUI app
+does not inherit your shell profile, and that is by far the most common cause here.
 
-### Als de server niet start: PATH
+### If the server won't start: PATH
 
-Krijg je iets als `env: node: No such file or directory`, of blijft de server op "failed to
-connect" staan, dan is dit vrijwel altijd de oorzaak.
+If you get something like `env: node: No such file or directory`, or the server stays on
+"failed to connect", this is almost always the cause.
 
-Het commando `phpstan-mcp-mx` is een script dat begint met `#!/usr/bin/env node`, en `npx`
-is zelf ook een commando dat gevonden moet worden. Allebei werken ze in je terminal omdat je
-shell-profiel Node op `PATH` zet. Maar de MCP-server wordt gestart door een ánder programma,
-en dat erft je shell-profiel niet altijd — een GUI-app op macOS krijgt vaak alleen een kale
-`PATH` met `/usr/bin` en `/bin`. Node staat daar niet: Homebrew zet hem in
-`/opt/homebrew/bin`, en nvm, fnm, asdf en volta ergens onder je home.
+The `phpstan-mcp-mx` command is a script that starts with `#!/usr/bin/env node`, and `npx`
+is itself a command that has to be found. Both work in your terminal because your shell
+profile puts Node on `PATH`. But the MCP server is started by a *different* program, and that
+one does not always inherit your shell profile — a GUI app on macOS often gets only a bare
+`PATH` with `/usr/bin` and `/bin`. Node isn't there: Homebrew puts it in `/opt/homebrew/bin`,
+and nvm, fnm, asdf and volta somewhere under your home directory.
 
-De oplossing is absolute paden gebruiken, zodat er niets meer opgezocht hoeft te worden:
+The fix is to use absolute paths, so nothing needs to be looked up any more:
 
 ```bash
-command -v node   # bijv. /opt/homebrew/bin/node
-npm root -g       # bijv. /opt/homebrew/lib/node_modules
+command -v node   # e.g. /opt/homebrew/bin/node
+npm root -g       # e.g. /opt/homebrew/lib/node_modules
 ```
 
 ```bash
 claude mcp add phpstan --scope user \
-  --env PHPSTAN_MCP_ROOTS=/pad/naar/projecten \
+  --env PHPSTAN_MCP_ROOTS=/path/to/projects \
   -- /opt/homebrew/bin/node /opt/homebrew/lib/node_modules/phpstan-mcp-mx/dist/index.js
 ```
 
-En voor Claude Desktop:
+And for Claude Desktop:
 
 ```json
 {
@@ -127,15 +130,15 @@ En voor Claude Desktop:
     "phpstan": {
       "command": "/opt/homebrew/bin/node",
       "args": ["/opt/homebrew/lib/node_modules/phpstan-mcp-mx/dist/index.js"],
-      "env": { "PHPSTAN_MCP_ROOTS": "/pad/naar/projecten" }
+      "env": { "PHPSTAN_MCP_ROOTS": "/path/to/projects" }
     }
   }
 }
 ```
 
-Zelf nagaan of het aan `PATH` ligt, zonder de MCP-client erbij te halen. Het binary wordt
-eerst in je eigen shell opgezocht en daarna met een kale `PATH` gestart — anders is het
-commando zelf al onvindbaar en meet je iets anders:
+You can check whether `PATH` is the problem yourself, without involving the MCP client. The
+binary is looked up in your own shell first and then started with a bare `PATH` — otherwise
+the command itself can't be found and you are measuring something else:
 
 ```bash
 echo '' | env -i PATH=/usr/bin:/bin "$(command -v phpstan-mcp-mx)"
@@ -145,8 +148,8 @@ echo '' | env -i PATH=/usr/bin:/bin "$(command -v phpstan-mcp-mx)"
 env: node: No such file or directory
 ```
 
-Komt dat eruit, dan weet je genoeg. Dezelfde test op de absolute variant hoort gewoon te
-starten:
+If that is what comes out, you know enough. The same test on the absolute variant should
+start normally:
 
 ```bash
 echo '' | env -i PATH=/usr/bin:/bin \
@@ -157,188 +160,217 @@ echo '' | env -i PATH=/usr/bin:/bin \
 phpstan-mcp 0.1.0 luistert op stdio, 0 root(s) geconfigureerd
 ```
 
-(Nul roots klopt hier: `env -i` gooit ook `PHPSTAN_MCP_ROOTS` weg. Het gaat er alleen om dát
-hij start.)
+(Zero roots is correct here: `env -i` also throws away `PHPSTAN_MCP_ROOTS`. All that matters
+is *that* it starts.)
+
+### Updating
 
-### Vanuit de repo
+A global installation does not update itself:
+
+```bash
+npm install -g phpstan-mcp-mx@latest
+```
+
+Then start a **new session** in your client. Just restarting is not enough: a server that is
+already running keeps the code it loaded at startup, and the client holds on to the tool list
+from the start of the session. New tools are then missing, and an argument the client doesn't
+know yet (such as `runId`) is silently dropped.
+
+If you register the server through `npx`, use `phpstan-mcp-mx@latest` instead of the bare
+name; otherwise npx may keep using an older version from its cache. `server_config` shows
+which version is running.
+
+### From the repository
 
 ```bash
 npm install && npm run build
 claude mcp add phpstan --scope user \
-  --env PHPSTAN_MCP_ROOTS=/pad/naar/projecten \
-  -- node /pad/naar/phpstan-mcp-mx/dist/index.js
+  --env PHPSTAN_MCP_ROOTS=/path/to/projects \
+  -- node /path/to/phpstan-mcp-mx/dist/index.js
 ```
 
-Let op dat je dan vastzit aan die map: verplaats of verwijder je hem, dan faalt de server in
-al je projecten.
+Note that you are then tied to that directory: move or delete it, and the server fails in
+all your projects.
 
-## Configuratie
+## Configuration
 
-Alles kan als env-variabele in je MCP-config, of in één configbestand. **De omgeving wint van
-het bestand**: die staat bij één client, het bestand geldt voor de hele machine.
+Everything can be set as an env variable in your MCP config, or in a single config file.
+**The environment wins over the file**: the environment belongs to one client, the file
+applies to the whole machine.
 
-### Een configbestand
+### A config file
 
-`~/.config/phpstan-mcp/config.json` (of `$XDG_CONFIG_HOME/phpstan-mcp/config.json`, of het
-pad in `PHPSTAN_MCP_CONFIG`):
+`~/.config/phpstan-mcp/config.json` (or `$XDG_CONFIG_HOME/phpstan-mcp/config.json`, or the
+path in `PHPSTAN_MCP_CONFIG`):
 
 ```json
 {
-  "roots": ["/Users/jij/projecten"],
+  "roots": ["/Users/you/projects"],
   "memoryLimit": "2G",
   "maxParallel": 2,
   "tmpDir": "project",
   "allowWrites": false,
   "runners": {
-    "/Users/jij/projecten/admin": {
+    "/Users/you/projects/admin": {
       "command": ["docker", "exec", "-w", "/var/www/html", "admin-app"],
       "workdir": "/var/www/html"
     }
   },
   "projects": {
-    "/Users/jij/projecten/shop": { "memoryLimit": "4G", "timeoutSeconds": 900 }
+    "/Users/you/projects/shop": { "memoryLimit": "4G", "timeoutSeconds": 900 }
   }
 }
 ```
 
-Daarmee is je MCP-registratie één regel zonder `--env`, en staat de configuratie op één plek
-in plaats van verdeeld over zeven variabelen.
+That makes your MCP registration a single line without `--env`, and keeps the configuration
+in one place instead of spread over seven variables.
 
-Een bestand dat er niet is, is geen fout: dan geldt alleen de omgeving. Een bestand dat er
-wél is maar niet klopt, laat de server niet starten — dan heeft iemand iets bedoeld wat
-anders stilzwijgend niet gebeurt.
+A file that doesn't exist is not an error: then only the environment applies. A file that
+*does* exist but is invalid stops the server from starting — someone meant something there
+that would otherwise silently not happen.
 
-### `PHPSTAN_MCP_ROOTS` (verplicht)
+### `PHPSTAN_MCP_ROOTS` (required)
 
-`PHPSTAN_MCP_ROOTS` is verplicht: een lijst absolute paden, gescheiden door een dubbele punt
-(een puntkomma op Windows). Alles daaronder mag geanalyseerd worden, alles daarbuiten niet.
+`PHPSTAN_MCP_ROOTS` is required: a list of absolute paths, separated by a colon (a semicolon
+on Windows). Everything below them may be analysed, nothing outside them.
 
 ```
-PHPSTAN_MCP_ROOTS=/Users/jij/projecten:/Users/jij/werk/klant-x
+PHPSTAN_MCP_ROOTS=/Users/you/projects:/Users/you/work/client-x
 ```
 
-Een root hoeft niet zelf een project te zijn. De server zoekt tot vier niveaus diep naar
-mappen met een `composer.json`, stopt zodra hij er een vindt, en slaat `vendor/`,
-`node_modules/` en verborgen mappen over. Een indeling als `~/projecten/<klant>/<project>`
-werkt dus met `~/projecten` als enige root.
+A root doesn't have to be a project itself. The server searches up to four levels deep for
+directories with a `composer.json`, stops as soon as it finds one, and skips `vendor/`,
+`node_modules/` and hidden directories. A layout like `~/projects/<client>/<project>` works
+with `~/projects` as the only root.
 
-### `PHPSTAN_MCP_MAX_PARALLEL` (optioneel)
+### `PHPSTAN_MCP_MAX_PARALLEL` (optional)
 
-Hoeveel analyses er tegelijk mogen draaien, over projecten heen. Standaard twee.
+How many analyses may run at the same time, across projects. Two by default.
 
 ```
 PHPSTAN_MCP_MAX_PARALLEL=4
 ```
 
-Analyses binnen hetzelfde project gaan altijd op volgorde — PHPStans resultcache ligt in het
-project en twee gelijktijdige runs schrijven daar overheen. Deze grens gaat over de machine
-als geheel: zonder hem start een model dat na `list_projects` tien projecten aanroept tien
-PHPStan-processen, die elk hun eigen parallelle workers opzetten. Met
-`PHPSTAN_MCP_MEMORY_LIMIT=2G` is dat tien keer dat plafond.
+Analyses within the same project always run in order — two simultaneous runs would overwrite
+each other's result cache. This limit is about the machine as a whole: without it, a model
+that calls ten projects after `list_projects` starts ten PHPStan processes, each spinning up
+its own parallel workers. With `PHPSTAN_MCP_MEMORY_LIMIT=2G` that is ten times that ceiling.
 
-Een onbruikbare waarde wordt geweigerd in plaats van stil vervangen door de standaard, en
-komt als `LET OP` in de opstartregel:
+An unusable value is rejected instead of silently replaced by the default, and shows up as
+`LET OP` ("attention") in the startup line:
 
 ```
 phpstan-mcp 0.3.1 luistert op stdio, 1 root(s) geconfigureerd, hoogstens 2 tegelijk
 ```
 
-### `PHPSTAN_MCP_TMPDIR` (optioneel)
+### `PHPSTAN_MCP_TMPDIR` (optional)
 
-Waar PHPStan zijn tijdelijke bestanden neerzet, en daarmee waar de resultcache landt.
+Where PHPStan puts its temporary files, and therefore where the result cache ends up.
 
-| waarde | betekenis |
+| value | meaning |
 | --- | --- |
-| `project` (standaard) | elk project een eigen map onder de tijdelijke map van het systeem |
-| `shared` | niets zetten; wat het systeem toch al gebruikt |
+| `project` (default) | each project gets its own directory under the system temp directory |
+| `shared` | set nothing; whatever the system uses anyway |
 
-De standaard lost een stil probleem op. PHPStans `tmpDir` is standaard
-`sys_get_temp_dir()/phpstan`, dus élk project zonder eigen `tmpDir` in zijn config deelt één
-`resultCache.php`. Twee projecten na elkaar maken dan elkaars cache ongeldig, en de cache —
-de reden dat een tweede analyse snel is — doet niets meer. Gemeten op twee echte projecten,
-met een ander project ertussendoor:
+The default solves a silent problem. PHPStan's `tmpDir` defaults to
+`sys_get_temp_dir()/phpstan`, so *every* project without its own `tmpDir` in its config
+shares a single `resultCache.php`. Two projects in a row then invalidate each other's cache,
+and the cache — the reason a second analysis is fast — stops doing anything. Measured on two
+real projects, with another project in between:
 
 ```
-eigen map:     1s → (ander project) → 1s
-gedeelde map:  5s → (ander project) → 3s
+own directory:     1s → (other project) → 1s
+shared directory:  5s → (other project) → 3s
 ```
 
-Zet je `tmpDir` zelf in je `phpstan.neon`, dan wint die: een configuratie die je expliciet
-hebt gemaakt gaat vóór wat deze server aandraagt.
+The directory name also contains a hash of `composer.lock`. After a `composer update`,
+PHPStan therefore starts in a fresh directory: a result cache from before such an update
+used to make PHPStan crash with a message that pointed nowhere. The server leaves old
+directories in place; the system cleans those up itself.
+
+If you set `tmpDir` yourself in your `phpstan.neon`, that wins: a configuration you made
+explicitly takes precedence over what this server provides.
 
-Kies `shared` als je wil dat de server dezelfde cache gebruikt als je terminal, of als het
-zetten van `TMPDIR` iets in je project stoort — bij Larastan draait er een hele
-Laravel-applicatie in hetzelfde proces mee.
+Choose `shared` if you want the server to use the same cache as your terminal, or if setting
+`TMPDIR` disturbs something in your project — with Larastan, an entire Laravel application
+runs in the same process.
 
-### `PHPSTAN_MCP_RUNNERS` (optioneel)
+### `PHPSTAN_MCP_RUNNERS` (optional)
 
-Sommige projecten zijn op de host niet te analyseren. Larastan start je Laravel-applicatie
-écht op, en mist de host bijvoorbeeld `ext-redis`, dan klapt de bootstrap en stopt de analyse
-— terwijl dezelfde repo in zijn container probleemloos doorloopt.
+Some projects cannot be analysed on the host. Larastan really boots your Laravel
+application, and if the host lacks, say, `ext-redis`, the bootstrap fails and the analysis
+stops — while the same repository runs fine inside its container.
 
-Met deze variabele zeg je per project waar PHPStan gedraaid moet worden:
+With this variable you say, per project, where PHPStan should run:
 
 ```json
 {
-  "/Users/jij/projecten/admin": {
+  "/Users/you/projects/admin": {
     "command": ["docker", "exec", "-w", "/var/www/html", "admin-app"],
     "workdir": "/var/www/html"
   }
 }
 ```
 
-`command` is het commando dat ervóór komt; `workdir` is het pad waarop diezelfde projectmap
-in die omgeving staat. Dat tweede is geen detail: paden die je meegeeft worden ernaartoe
-vertaald, en de bestandspaden in het antwoord komen terug als host-paden — anders krijg je
-`/var/www/html/app/User.php` terug en kun je dat bestand niet openen.
+`command` is the command that goes in front; `workdir` is the path at which that same
+project directory lives inside that environment. The second one is not a detail: paths you
+pass in are translated to it, and file paths in the response come back as host paths —
+otherwise you get `/var/www/html/app/User.php` back and can't open that file.
+
+`list_projects` shows which environment applies to each project, and with a runner there is
+no need for `vendor/bin/phpstan` on the host. Everything then goes through the runner:
+analysing, but also `diagnose_project`, `clear_result_cache` and `generate_baseline`. Only
+`unmatched_ignores` does not work with a runner (see there).
 
-`list_projects` vermeldt per project welke omgeving geldt, en met een runner hoeft er op de
-host geen `vendor/bin/phpstan` te staan.
+`workdir` is a POSIX path, even when the host is Windows: the environment is a Linux
+container or WSL. The project key may be written in your platform's form
+(`C:\Users\you\admin` or `C:/Users/you/admin`, with or without a trailing slash); it is
+compared after resolving symlinks, just like the `project` argument itself.
 
-**Het commando komt uit de serverconfiguratie, nooit uit een tool-aanroep.** Net als de roots
-is dit iets wat een mens één keer vastlegt: een model kiest alleen een project, en of daar
-een omgeving bij hoort ligt dan al vast. Zou een aanroeper het commando mogen meegeven, dan
-bepaalt die wat er uitgevoerd wordt en is de whitelist zinloos.
+**The command comes from the server configuration, never from a tool call.** Like the roots,
+this is something a human sets once: a model only picks a project, and whether an
+environment belongs to it is already decided. If a caller could pass in the command, the
+caller would decide what gets executed and the whitelist would be pointless.
 
-### Waarom die lijst verplicht is
+### Why that list is required
 
-PHPStan is geen passieve parser. Het laadt de autoloader van het project, voert
-`bootstrapFiles` uit de configuratie uit en laadt extensies als PHP-code. "Analyseer map X"
-betekent daarmee "voer de PHP-code uit die in X's configuratie staat" — en het pad komt van
-een taalmodel. De lijst met roots maakt expliciet en menselijk vastgesteld wat binnen bereik
-ligt.
+PHPStan is not a passive parser. It loads the project's autoloader, executes
+`bootstrapFiles` from the configuration and loads extensions as PHP code. "Analyse directory
+X" therefore means "execute the PHP code that X's configuration points to" — and the path
+comes from a language model. The list of roots makes what is in reach explicit and decided
+by a human.
 
-### `PHPSTAN_MCP_MEMORY_LIMIT` (optioneel)
+### `PHPSTAN_MCP_MEMORY_LIMIT` (optional)
 
-Klapt PHPStan op de PHP-geheugenlimiet, dan kan een aanroep `memoryLimit` meegeven — maar
-dat gebeurt pas nadat de analyse al mislukt is. Met deze variabele leg je de standaard één
-keer vast, naast je roots:
+If PHPStan runs into the PHP memory limit, a call can pass `memoryLimit` — but only after
+the analysis has already failed. With this variable you set the default once, next to your
+roots:
 
 ```
 PHPSTAN_MCP_MEMORY_LIMIT=2G
 ```
 
-Dat wordt `--memory-limit=2G` op elke aanroep die zelf niets meegeeft; een `memoryLimit` in
-de aanroep gaat vóór. Toegestaan is wat PHPStan zelf accepteert: een getal in bytes,
-optioneel met `K`, `M` of `G`, of `-1` voor onbeperkt. Iets anders wordt geweigerd met een
-melding in plaats van doorgegeven, want PHPStan zou er per analyse op klappen.
+That becomes `--memory-limit=2G` on every call that doesn't pass one itself; a `memoryLimit`
+in the call takes precedence. Allowed is whatever PHPStan itself accepts: a number of bytes,
+optionally with `K`, `M` or `G`, or `-1` for unlimited. Anything else is rejected with a
+message instead of passed on, because PHPStan would crash on it for every analysis.
 
-Dit is de enige manier om het bij de server vast te leggen. PHPStan kent er geen
-`phpstan.neon`-parameter voor (`Unexpected item 'parameters › memoryLimit'`) en ook geen
-eigen env-variabele; het alternatief is `memory_limit` in je `php.ini`, en dat geldt dan
-voor élke PHP-CLI op je machine.
+This is the only way to set it at the server level. PHPStan has no `phpstan.neon` parameter
+for it (`Unexpected item 'parameters › memoryLimit'`) and no env variable of its own; the
+alternative is `memory_limit` in your `php.ini`, which then applies to *every* PHP CLI on
+your machine.
 
-Heeft één project meer nodig dan de rest, zet het dan bij dat project in
-`PHPSTAN_MCP_PROJECTS` in plaats van deze waarde voor iedereen op te hogen — met
-`PHPSTAN_MCP_MAX_PARALLEL=2` is een machinebrede 4G twee keer 4G.
+If one project needs more than the rest, set it for that project in `PHPSTAN_MCP_PROJECTS`
+instead of raising this value for everyone — with `PHPSTAN_MCP_MAX_PARALLEL=2`, a
+machine-wide 4G is two times 4G.
 
-### `PHPSTAN_MCP_PROJECTS` (optioneel)
+### `PHPSTAN_MCP_PROJECTS` (optional)
 
-Standaarden voor één project, als JSON — of onder `projects` in het configbestand:
+Defaults for a single project, as JSON — or under `projects` in the config file:
 
 ```json
 {
-  "/Users/jij/projecten/shop": {
+  "/Users/you/projects/shop": {
     "memoryLimit": "4G",
     "timeoutSeconds": 900,
     "config": "phpstan-ci.neon"
@@ -346,222 +378,251 @@ Standaarden voor één project, als JSON — of onder `projects` in het configbe
 }
 ```
 
-| Sleutel | Betekenis |
+| Key | Meaning |
 | --- | --- |
-| `memoryLimit` | `--memory-limit` voor dit project, in dezelfde vorm als `PHPSTAN_MCP_MEMORY_LIMIT` |
-| `timeoutSeconds` | timeout voor dit project, van 1 tot en met 1800 |
-| `config` | configbestand binnen het project, als PHPStan dat niet zelf vindt |
+| `memoryLimit` | `--memory-limit` for this project, in the same form as `PHPSTAN_MCP_MEMORY_LIMIT` |
+| `timeoutSeconds` | timeout for this project, from 1 up to and including 1800 |
+| `config` | config file inside the project, if PHPStan doesn't find it by itself |
 
-De volgorde is steeds dezelfde: wat de aanroep meegeeft, dan de standaard van het project,
-dan die van de hele server. Een standaard is dus geen plafond.
+The order is always the same: what the call passes, then the project default, then the
+server-wide one. A default is therefore not a ceiling.
 
-`config` gaat door dezelfde padcontrole als een `config` uit een aanroep en moet binnen het
-project liggen; een neon kan PHP-code laten uitvoeren. Hij telt overal als dé config van het
-project: bij de melding dat er een baseline meedoet en bij `unmatched_ignores`.
+`config` goes through the same path check as a `config` from a call and must lie inside the
+project; a neon file can cause PHP code to be executed. It counts everywhere as *the* config
+of the project: for the notice that a baseline is included and for `unmatched_ignores`.
 
-Een onbekende sleutel wordt geweigerd, niet genegeerd: `memorylimit` met een kleine l zou
-anders stil niets doen. `list_projects` en `server_config` tonen welke standaarden er gelden,
-en een kapotte waarde staat daar als probleem bij — de lijst met projecten blijft werken.
+An unknown key is rejected, not ignored: `memorylimit` with a lowercase l would otherwise
+silently do nothing. `list_projects` and `server_config` show which defaults apply, and a
+broken value is listed there as a problem — the project list keeps working.
 
 ## Tools
 
-Elke tool verwacht een expliciet `project`-pad. De server heeft geen "huidig project": dat
-zou toestand zijn die het model niet in zijn context ziet staan, met stilzwijgend het
-verkeerde project als gevolg.
+Every tool expects an explicit `project` path. The server has no "current project": that
+would be state the model doesn't see in its context, with the wrong project silently
+analysed as a result.
 
 ### `list_projects`
 
-Somt de projecten op die binnen bereik liggen, met per project of PHPStan geïnstalleerd is
-en welk configbestand er ligt. Begin hier — het `path` uit het resultaat is wat de andere
-tools als `project` verwachten.
+Lists the projects that are in reach, with for each project whether PHPStan is installed and
+which config file it has. Start here — the `path` from the result is what the other tools
+expect as `project`.
 
 ### `analyse_project`
 
-| Argument | Verplicht | Betekenis |
+| Argument | Required | Meaning |
 | --- | --- | --- |
-| `project` | ja | absoluut pad naar de projectroot |
-| `paths` | nee | paden binnen het project; leeg betekent: volg `phpstan.neon` |
-| `level` | nee | level-override, `0` t/m `10` of `max` |
-| `config` | nee | ander configbestand, bijv. `phpstan-strict.neon`; moet binnen het project liggen |
-| `memoryLimit` | nee | bijv. `1G`, als PHPStan op de PHP-geheugenlimiet klapt |
-| `timeoutSeconds` | nee | standaard 300 |
-| `identifiers` | nee | alleen deze identifiers in de pagina, bijv. `["argument.type"]` |
-| `offset` / `limit` | nee | welk deel van de bevindingen je terugkrijgt |
-
-`config` gaat door dezelfde padcontrole als `project`. Dat is geen formaliteit: een `.neon`
-kan `bootstrapFiles` en extensies aanwijzen, dus een vrij te kiezen configpad zou een route
-zijn om willekeurige PHP-code te laten uitvoeren langs de whitelist heen.
-
-`identifiers` filtert alleen de *pagina*; de samenvatting blijft over alles tellen, zodat
-zichtbaar blijft wat je wegliet. Een waarde matcht exact (`argument.type`) of als groep
-(`missingType` matcht `missingType.return` en `missingType.parameter`, maar `argument` matcht
-niet `argumentx.iets`).
+| `project` | yes | absolute path to the project root |
+| `paths` | no | paths inside the project; empty means: follow `phpstan.neon` |
+| `level` | no | level override, `0` to `10` or `max` |
+| `config` | no | a different config file, e.g. `phpstan-strict.neon`; must lie inside the project |
+| `memoryLimit` | no | e.g. `1G`, if PHPStan hits the PHP memory limit |
+| `timeoutSeconds` | no | 300 by default |
+| `identifiers` | no | only these identifiers in the page, e.g. `["argument.type"]` |
+| `offset` / `limit` | no | which part of the findings you get back |
+| `runId` | no | from an earlier response: the next page from the same result (see [What you get back](#what-you-get-back)) |
+
+`config` goes through the same path check as `project`. That is not a formality: a `.neon`
+can point to `bootstrapFiles` and extensions, so a freely chosen config path would be a way
+to have arbitrary PHP code executed around the whitelist.
+
+`identifiers` only filters the *page*; the summary keeps counting everything, so you can
+still see what you left out. A value matches exactly (`argument.type`) or as a group
+(`missingType` matches `missingType.return` and `missingType.parameter`, but `argument` does
+not match `argumentx.something`).
 
 ### `analyse_file`
 
-Zelfde argumenten, plus een verplichte `path` — één bestand of map binnen het project. Het
-pad mag relatief aan de projectroot zijn of absoluut, maar moet er wel binnen liggen.
+Same arguments, plus a required `path` — a single file or directory inside the project. The
+path may be relative to the project root or absolute, but it has to lie inside it.
 
 ### `analyse_changed`
 
-Analyseert de PHP-bestanden die volgens git gewijzigd zijn. Bedoeld om te zien of een eigen
-wijziging fouten oplevert, zonder het hele project door te rekenen — en zonder dat het
-antwoord volloopt met wat er al jaren stond.
+Analyses the PHP files that git considers changed. Meant for checking whether your own
+change introduces errors, without analysing the whole project — and without the response
+filling up with what has been there for years.
 
-| Argument | Verplicht | Betekenis |
+| Argument | Required | Meaning |
 | --- | --- | --- |
-| `project` | ja | absoluut pad naar de projectroot |
-| `base` | nee | commit, branch of tag om tegen te vergelijken (standaard `HEAD`) |
-| `staged` | nee | alleen wat gestaged is (`git diff --cached`), voor een check vóór een commit |
-| `onlyChangedLines` | nee | alleen bevindingen op regels die gewijzigd zijn |
-
-Verder dezelfde argumenten als `analyse_project`, op `paths` na. Met `base=main` krijg je de
-hele branch in plaats van alleen je onopgeslagen werk.
-
-Elke bevinding zegt met `onChangedLine` of hij op een gewijzigde regel staat; in de tekst
-staat er een `+` voor. Een gewijzigd bestand bevat vaak ook fouten die er al stonden, en
-zonder dat onderscheid ga je die repareren of stop je te vroeg. Let wel: een bevinding op een
-ongewijzigde regel kan nog steeds uit je wijziging volgen — een aangepaste signatuur geeft
-fouten bij de aanroepen, en die regels heb je niet aangeraakt.
-
-Twee dingen die het meeneemt en die je makkelijk mist: **nieuwe bestanden die nog niet aan
-git toegevoegd zijn** (`git diff` kent die niet, dus er is een tweede uitvraag voor) en
-**niets uit `resources/views`** — een `.blade.php` eindigt op `.php`, maar is een template
-die PHPStan bij een normale run nooit ziet, omdat de config die map niet in `paths` noemt.
-
-Elk pad dat git noemt gaat door dezelfde controle als een pad dat het model zelf geeft. Wat
-daar niet doorkomt — een kapotte symlink, een bestand dat buiten het project uitwijst — komt
-als "overgeslagen" bij het antwoord te staan in plaats van er stil uit te vallen.
-
-Staat het project niet onder git, dan zegt de tool dat en verwijst hij naar `analyse_project`
-met expliciete `paths`.
+| `project` | yes | absolute path to the project root |
+| `base` | no | commit, branch or tag to compare against (`HEAD` by default) |
+| `staged` | no | only what is staged (`git diff --cached`), for a check before a commit |
+| `onlyChangedLines` | no | only findings on lines that were changed |
+
+Otherwise the same arguments as `analyse_project`, except `paths`. With `base=main` you get
+the whole branch instead of just your uncommitted work.
+
+Each finding says with `onChangedLine` whether it is on a changed line; in the text it is
+prefixed with a `+`. A changed file often also contains errors that were already there, and
+without that distinction you either start fixing those or stop too early. Keep in mind: a
+finding on an unchanged line can still follow from your change — a modified signature causes
+errors at the call sites, and you didn't touch those lines.
+
+Two things it includes that are easy to miss: **new files not yet added to git** (`git diff`
+doesn't know them, so there is a second query for them) and **nothing from
+`resources/views`** — a `.blade.php` ends in `.php`, but it is a template that PHPStan never
+sees in a normal run, because the config doesn't list that directory in `paths`.
+
+Every path git reports goes through the same check as a path the model supplies itself.
+Whatever doesn't pass — a broken symlink, a file pointing outside the project — is listed as
+"skipped" in the response instead of silently dropping out.
+
+If the project is not under git, the tool says so and points to `analyse_project` with
+explicit `paths`.
+
+**What the change hides** is listed under "Ter info" (for your information): new
+`@phpstan-ignore` comments (with file, line, identifier and reason) and ignored errors added
+to a baseline that is included — even if no PHP file changed otherwise. An ignore whose reason
+is the only thing that changed does not count as new. The notice doesn't pass judgement: an
+ignore can be justified, the point is that it doesn't happen silently. Ignored errors that
+disappeared from the baseline are listed too.
 
 ### `server_config`
 
-Geeft terug waarmee déze server draait: de projectmappen die binnen bereik liggen, de
-standaard geheugenlimiet, hoeveel analyses er tegelijk mogen, waar de tijdelijke bestanden
-heen gaan en of schrijvende tools aanstaan.
+Returns what *this* server is running with: the project directories in reach, the default
+memory limit, how many analyses may run at once, where temporary files go and whether
+writing tools are enabled.
 
 ```
-phpstan-mcp 0.7.1
+phpstan-mcp 0.15.0
 
 Projectmappen:
-  /Users/jij/projecten
-  /bestaat/niet  — bestaat niet
+  /Users/you/projects
+  /does/not/exist  — bestaat niet
 
 Geheugenlimiet:      2G
 Tegelijk:            2
 Tijdelijke map:      project
 Schrijvende tools:   uit
+Eigen omgeving:      geen
+
+Standaarden per project (een tool-argument gaat voor):
+  /Users/you/projects/shop: geheugen 4G, timeout 900s
 ```
 
-Die informatie stond tot nu toe alleen in de opstartregel op stderr — zichtbaar in je
-clientlog, onzichtbaar voor het model. Een geweigerde instelling wordt gemeld in plaats van
-weggelaten: staat `PHPSTAN_MCP_MAX_PARALLEL` op onzin, dan is dat veld `null` en staat de
-reden onder "Geweigerde instellingen", terwijl de rest gewoon leesbaar blijft.
+Until now that information was only in the startup line on stderr — visible in your client
+log, invisible to the model. A rejected setting is reported instead of omitted: if
+`PHPSTAN_MCP_MAX_PARALLEL` is set to nonsense, that field is `null` and the reason appears
+under "Geweigerde instellingen" (rejected settings), while the rest stays readable.
 
-Heeft een project eigen standaarden (`PHPSTAN_MCP_PROJECTS`), dan staan die er per project
-onder.
+If a project has its own defaults (`PHPSTAN_MCP_PROJECTS`), they are listed per project.
 
-Let op wat er *niet* in staat: dit is een vaste lijst van instellingen en geen doorgeefluik
-naar de omgeving. In dezelfde omgeving zitten tokens; die horen niet in een
-toolantwoord.
+Note what is *not* in there: this is a fixed list of settings and not a pass-through to the
+environment. The same environment holds tokens; those don't belong in a tool response.
 
 ### `diagnose_project`
 
-Vraagt PHPStan zelf om zijn opstelling: PHP- en PHPStan-versie, de configs die
-Composer-pakketten meebrengen (zoals Larastan) en of de turbo-extensie aanstaat. Draait geen
-analyse.
+Asks PHPStan itself for its setup: PHP and PHPStan version, the configs that Composer
+packages bring along (such as Larastan) and whether the turbo extension is enabled. Does not
+run an analysis.
+
+Use this when one project behaves differently from another, before you start doubting the
+code. That is not theoretical: this is how it turned out that one project had a dependency
+(`laravel/pao`) that intercepted PHPStan's output.
 
-Gebruik dit als een project zich anders gedraagt dan een ander project, vóórdat je aan de
-code gaat twijfelen. Dat is niet theoretisch: hiermee bleek dat één project een dependency
-had (`laravel/pao`) die de uitvoer van PHPStan onderschepte.
+Below PHPStan's own text comes the configuration as PHPStan ends up using it:
+
+```
+Uiteindelijke configuratie, volgens PHPStan zelf:
+  Level:            10
+  Paden:            app, tests
+  Uitgesloten:      geen
+  Negeerregels:     1312 (verouderde worden níet gemeld; unmatched_ignores zoekt ze op)
+  Tijdelijke map:   /tmp/phpstan-mcp/cms-0d03c8f34a81/phpstan
+  Bootstrap:        vendor/larastan/larastan/bootstrap.php
+```
+
+The level shows up here even when it is set in a shared config from `vendor/`, and the temp
+directory is the one `clear_result_cache` clears. If the application doesn't boot (Larastan
+without the extensions the app needs), this part is missing, with the reason stated.
 
 ### `clear_result_cache`
 
-Leegt PHPStans resultcache, zodat de volgende analyse alles opnieuw doorrekent. Nuttig als
-een uitslag niet klopt met de code — bijvoorbeeld na een wijziging aan een extensie of een
-geïncludeerde config.
+Clears PHPStan's result cache, so the next analysis recomputes everything. Useful when a
+result doesn't match the code — for example after a change to an extension or an included
+config.
 
-Die cache ligt standaard **niet** in het project maar in de tijdelijke map van het systeem
-(`sys_get_temp_dir()/phpstan`), en wordt dan gedeeld met elk ander project dat geen eigen
-`tmpDir` zet. Bovendien volgt die map `TMPDIR`, dus wat de server leegt hoeft niet dezelfde
-map te zijn als wat je terminal gebruikt. Het antwoord noemt daarom de map die geleegd is:
+By default that cache does **not** live in the project but in the system temp directory
+(`sys_get_temp_dir()/phpstan`), and is then shared with every other project that doesn't set
+its own `tmpDir`. On top of that, the directory follows `TMPDIR`, so what the server clears
+need not be the same directory your terminal uses. The response therefore names the directory
+that was cleared:
 
 ```
 Result cache cleared from directory:
 /var/tmp/phpstan
 ```
 
-Wil je per project een eigen cache, zet dan `tmpDir` in je `phpstan.neon`.
+If you want a separate cache per project, set `tmpDir` in your `phpstan.neon`.
 
 ### `baseline_summary`
 
-Leest de `phpstan-baseline*.neon` van een project en telt wat er genegeerd wordt, per
-identifier en per bestand. Draait geen analyse, dus het antwoord is er meteen.
+Reads a project's `phpstan-baseline*.neon` and counts what is being ignored, per identifier
+and per file. Does not run an analysis, so the answer is immediate.
+
+Note the distinction: what is in here is exactly what `analyse_project` does *not* report. A
+project that includes its baseline only reports the errors that are new — PHPStan already
+makes that comparison itself.
 
-Let op het onderscheid: wat hier in staat is precies wat `analyse_project` *niet* meldt. Een
-project dat zijn baseline includet, rapporteert alleen de fouten die er nieuw bij komen —
-die vergelijking maakt PHPStan zelf al.
+With `path` (e.g. `"app/Models/User.php"`) you also get the entries for that one file: per
+entry the identifier, the count and the pattern. That file doesn't have to exist any more —
+it is precisely a deleted file that the entries doing nothing belong to.
 
 ### `unmatched_ignores`
 
-Zoekt de negeerregels die niets meer doen: baseline-regels voor fouten die allang opgelost
-zijn, en regels waarvan de `count` hoger is dan wat er nog voorkomt. Veel projecten zetten
-`reportUnmatchedIgnoredErrors: false`, en dan groeit dat ongemerkt — op één project bleken
-554 van de 2116 baseline-regels niets meer te matchen.
+Finds the ignore rules that no longer do anything: baseline entries for errors that were
+fixed long ago, and entries whose `count` is higher than what still occurs. Many projects set
+`reportUnmatchedIgnoredErrors: false`, and then this grows unnoticed — on one project, 554 of
+the 2116 baseline entries turned out to match nothing any more.
 
-| Argument | Verplicht | Betekenis |
+| Argument | Required | Meaning |
 | --- | --- | --- |
-| `project` | ja | absoluut pad naar de projectroot |
-| `memoryLimit` | nee | dit is een volledige analyse, dus die kan meer nodig hebben |
-| `timeoutSeconds` | nee | standaard 300 |
-| `offset` / `limit` | nee | welk deel van de regels je terugkrijgt |
+| `project` | yes | absolute path to the project root |
+| `memoryLimit` | no | this is a full analysis, so it may need more |
+| `timeoutSeconds` | no | 300 by default |
+| `offset` / `limit` | no | which part of the entries you get back |
 
-Dit is een volledige analyse, met een tijdelijke config die die van het project includet en
-de vlag omzet. Die config staat in de tijdelijke map van de server en niet in het project,
-dus er verandert niets aan je repository. PHPStans resultcache blijft bruikbaar: de vlag
-verandert niets aan wat er geanalyseerd wordt, dus de volgende gewone analyse is net zo snel.
+This is a full analysis, with a temporary config that includes the project's config and flips
+the flag. That config lives in the server's temp directory and not in the project, so nothing
+in your repository changes. PHPStan's result cache stays usable: the flag doesn't change what
+is analysed, so the next regular analysis is just as fast.
 
-Per regel staat erbij of hij uit de baseline komt. Patronen zonder pad komen apart; die staan
-in `ignoreErrors` van je config of van een config die een pakket meebrengt, en daar helpt een
-nieuwe baseline niet.
+Each entry says whether it comes from the baseline. Patterns without a path are listed
+separately; they live in `ignoreErrors` of your config or of a config a package brings along,
+and a new baseline doesn't help there.
 
-Er is bewust geen `level` en geen `paths`: op een ander niveau zijn het andere fouten, en bij
-een deel van het project lijkt alles daarbuiten verouderd.
+There is deliberately no `level` and no `paths`: on a different level the errors are
+different, and with only part of the project, everything outside it looks stale.
 
-Werkt niet op een project met een eigen uitvoeringsomgeving (`PHPSTAN_MCP_RUNNERS`): de
-tijdelijke config staat op de host en is in een container niet te zien. De tool zegt dat met
-reden `unsupported_with_runner`.
+Does not work on a project with its own execution environment (`PHPSTAN_MCP_RUNNERS`): the
+temporary config lives on the host and can't be seen inside a container. The tool says so
+with the reason `unsupported_with_runner`.
 
-### `generate_baseline` (alleen met schrijfrechten)
+### `generate_baseline` (only with write access)
 
-Zet alle huidige fouten in een baseline, zodat een volgende analyse alleen meldt wat er nieuw
-bij komt. Bedoeld om een bestaand project onder PHPStan te krijgen — niet om fouten weg te
-werken.
+Puts all current errors into a baseline, so that the next analysis only reports what is new.
+Meant for bringing an existing project under PHPStan — not for making errors go away.
 
-Deze tool bestaat alleen als de server met `PHPSTAN_MCP_ALLOW_WRITES=1` gestart is:
+This tool only exists if the server was started with `PHPSTAN_MCP_ALLOW_WRITES=1`:
 
 ```bash
 claude mcp add phpstan --scope user \
-  --env PHPSTAN_MCP_ROOTS=/pad/naar/projecten \
+  --env PHPSTAN_MCP_ROOTS=/path/to/projects \
   --env PHPSTAN_MCP_ALLOW_WRITES=1 \
   -- phpstan-mcp-mx
 ```
 
-Zonder die variabele wordt hij niet geregistreerd — hij staat dan dus ook niet in de
-toollijst, in plaats van dat hij bestaat en bij elke aanroep weigert. Alle andere tools
-blijven read-only.
+Without that variable it isn't registered — so it doesn't appear in the tool list at all,
+rather than existing and refusing every call. All other tools stay read-only.
 
-| Argument | Verplicht | Betekenis |
+| Argument | Required | Meaning |
 | --- | --- | --- |
-| `project` | ja | absoluut pad naar de projectroot |
-| `file` | nee | doelbestand binnen het project (standaard `phpstan-baseline.neon`) |
-| `allowEmpty` | nee | ook schrijven als er niets te negeren valt |
+| `project` | yes | absolute path to the project root |
+| `file` | no | target file inside the project (`phpstan-baseline.neon` by default) |
+| `allowEmpty` | no | write even if there is nothing to ignore |
 
-Verder dezelfde `paths`, `level`, `config` en `memoryLimit` als een analyse. Het antwoord
-zegt erbij wat er nog moet gebeuren, want een baseline die nergens ingesloten wordt doet
-niets:
+Otherwise the same `paths`, `level`, `config` and `memoryLimit` as an analysis. The response
+says what still needs to happen, because a baseline that isn't included anywhere does
+nothing:
 
 ```
 5 fout(en) in phpstan-baseline.neon gezet.
@@ -575,23 +636,37 @@ includes:
 
 ## Prompts
 
-Twee werkpatronen die alleen bestaande tools combineren. Een prompt en geen tool, omdat een
-tool context kost in elke sessie en een prompt alleen als je hem kiest.
-
-- **`phpstan_wijziging_nakijken`** — je eigen wijziging nakijken met `analyse_changed`,
-  beginnen bij de bevindingen op gewijzigde regels, en herhalen tot het schoon is (zonder
-  `runId`, anders zie je de uitslag van vóór je reparatie).
-- **`phpstan_level_verhogen`** — wat een level hoger kost: twee tellingen met `limit: 1` en
-  het verschil per soort. Het level staat vaak in een gedeelde config in `vendor/`, en
-  `ignore.*`-bevindingen tellen niet mee: dat zijn inline `@phpstan-ignore`-regels die op een
-  ander level niets te negeren hebben.
-
-Beide nemen een optioneel `project`; de tweede ook een doel-`level`.
-
-## Als een tool mislukt
-
-Een mislukte aanroep geeft twee blokken terug: de melding in gewone taal, en een JSON-blok
-met velden waarop je kunt sturen.
+Workflows that only combine existing tools. A prompt rather than a tool, because a tool costs
+context in every session and a prompt only when you pick it. Every guardrail in the texts
+comes from a trial run on a real project that went wrong without that sentence.
+
+- **`phpstan_wijziging_nakijken`** (review your change) — review your own change with
+  `analyse_changed`, start with the findings on changed lines, and repeat until it is clean
+  (without `runId`, otherwise you see the result from before your fix). With `base` (e.g.
+  `main`) for a whole branch before a PR.
+- **`phpstan_level_verhogen`** (raise the level) — what one level higher costs: two counts
+  with `limit: 1` and the difference per kind. The level is often set in a shared config in
+  `vendor/`, and `ignore.*` findings don't count: those are inline `@phpstan-ignore` comments
+  that have nothing to ignore on a different level.
+- **`phpstan_baseline_afbouwen`** (shrink the baseline) — what in the baseline is stale
+  (`unmatched_ignores`), what a new baseline would hide (`analyse_project`), and the cheapest
+  real reduction. Cleaning up and hiding stay two separate things: `generate_baseline` is only
+  suggested when there is nothing to hide, and never called on its own initiative.
+- **`phpstan_soort_wegwerken`** (clear one kind) — a clean-up round for one identifier or a
+  group such as `missingType`, with the `runId` within the round and without `runId` after
+  every fix. Without `identifier` the model picks a kind: first what can be fixed at the
+  source, otherwise a kind that sits in one or two files.
+- **`phpstan_projecten_vergelijken`** (compare projects) — two projects side by side
+  (`diagnose_project`, level, baseline, runners and defaults), showing only the differences.
+  If no difference explains the behaviour, a stale result cache is the next suspect.
+
+All prompts take an optional `project` (for the comparison, `projectA` and `projectB`), and a
+client that supports completion gets a picklist from `list_projects` there.
+
+## When a tool fails
+
+A failed call returns two blocks: the message in plain language, and a JSON block with fields
+you can act on.
 
 ```json
 {
@@ -604,20 +679,20 @@ met velden waarop je kunt sturen.
 }
 ```
 
-`reason` komt uit een gesloten verzameling, zodat je erop kunt matchen zonder de tekst te
-lezen: `no_roots_configured`, `project_outside_roots`, `project_not_found`,
-`path_outside_project`, `path_not_found`, `phpstan_missing`, `config_missing`,
-`bootstrap_failed`, `baseline_unreadable`, `invalid_setting`, `memory_limit`, `timeout`,
-`cancelled`, `git_missing`, `not_a_git_repository`, `unknown_base`, `unsupported_with_runner`,
-`unusable_output` en `phpstan_failed`.
+`reason` comes from a closed set, so you can match on it without reading the text:
+`no_roots_configured`, `project_outside_roots`, `project_not_found`, `path_outside_project`,
+`path_not_found`, `phpstan_missing`, `config_missing`, `bootstrap_failed`,
+`baseline_unreadable`, `invalid_setting`, `memory_limit`, `timeout`, `cancelled`,
+`git_missing`, `not_a_git_repository`, `unknown_base`, `unsupported_with_runner`,
+`unusable_output` and `phpstan_failed`.
 
-De velden staan bewust in `content` en niet in `structuredContent`: dat laatste wordt door
-MCP-clients gevalideerd tegen het schema van het *geslaagde* antwoord.
+The fields are deliberately in `content` and not in `structuredContent`: MCP clients validate
+the latter against the schema of the *successful* response.
 
-## Wat je terugkrijgt
+## What you get back
 
-Een analyse levert eerst tellingen over álle bevindingen en daarna één pagina met de
-bevindingen zelf (standaard 50, hoogstens 500):
+An analysis first returns counts over *all* findings and then one page with the findings
+themselves (50 by default, 500 at most):
 
 ```
 25 bevinding(en) in 11 bestand(en).
@@ -635,43 +710,43 @@ src/Support/Filters/DealFilters.php
   42  argument.type  Parameter #1 $id expects int, string given.
 ```
 
-Bij meer resultaten eindigt de tekst met de letterlijke vervolgaanroep:
+When there are more results, the text ends with the literal follow-up call:
 
 ```
 Nog 12 bevinding(en). Roep dezelfde tool opnieuw aan met offset=50 en runId="kX3v9aQp"; dan
 komt de rest uit dit resultaat in plaats van uit een nieuwe analyse.
 ```
 
-Met die `runId` komt de volgende pagina uit hetzelfde resultaat. Zonder zou elke pagina een
-nieuwe analyse zijn, en wie tussendoor een bestand aanpast krijgt dan pagina's met
-verschillende totalen. Alleen `offset`, `limit`, `identifiers` en `onlyChangedLines` mogen
-anders zijn. Hoort de `runId` bij andere argumenten, is hij verlopen (na tien minuten) of
-onbekend, dan volgt een nieuwe analyse met een melding erbij in plaats van een fout.
+With that `runId`, the next page comes from the same result. Without it, every page would be a
+new analysis, and if you change a file in between you get pages with different totals. Only
+`offset`, `limit`, `identifiers` and `onlyChangedLines` may differ. If the `runId` belongs to
+different arguments, has expired (after ten minutes) or is unknown, a new analysis follows
+with a notice instead of an error.
 
-Een pagina uit een eerder resultaat noemt hoe oud dat resultaat is. Analyseer na een
-reparatie dus zónder `runId`: anders zie je de uitslag van vóór de reparatie.
+A page from an earlier result states how old that result is. So after a fix, analyse
+*without* `runId`: otherwise you see the result from before the fix.
 
-### Annuleren
+### Cancelling
 
-Annuleert je client het verzoek, dan wordt de hele procesgroep van PHPStan opgeruimd in
-plaats van dat hij doorrekent voor een antwoord dat niemand meer leest. Een analyse die nog
-in de rij stond wordt niet meer gestart.
+If your client cancels the request, PHPStan's whole process group is cleaned up instead of
+it computing on for an answer nobody will read. An analysis still waiting in the queue is not
+started.
 
-### Als de analyse niet volledig is
+### When the analysis is incomplete
 
-PHPStan kan geldige JSON teruggeven en er tegelijk op stderr bij zeggen dat hij het niet
-heeft afgemaakt. Dat komt bovenaan het antwoord te staan, vóór alles:
+PHPStan can return valid JSON and at the same time say on stderr that it didn't finish. That
+goes at the very top of the response, before anything else:
 
 ```
 LET OP — PHPStan meldde dit naast het resultaat:
 - Result is incomplete because of severe errors.
 ```
 
-Dat onderscheid is wezenlijk: zonder die regel is een lege uitslag niet te onderscheiden van
-een schone. Staat er een waarschuwing, dan leest het antwoord ook niet meer "Geen
-bevindingen" maar "Verder geen bevindingen".
+That distinction is essential: without that line, an empty result can't be told apart from a
+clean one. When there is a warning, the response also no longer reads "Geen bevindingen" (no
+findings) but "Verder geen bevindingen" (no further findings).
 
-Doet er een baseline mee, dan staat dat er ook bij:
+If a baseline is included, that is stated too:
 
 ```
 Ter info:
@@ -679,12 +754,12 @@ Ter info:
   rapport. Gebruik baseline_summary om te zien wat er in staat.
 ```
 
-Dat is het verschil tussen "geen bevindingen" en "geen bevindingen, plus duizend die niet
-gemeld worden". De check kijkt of je config het bestand echt includeert — een baseline die
-naast `phpstan.neon` ligt zonder erin te staan, doet niets.
+That is the difference between "no findings" and "no findings, plus a thousand that aren't
+reported". The check looks at whether your config really includes the file — a baseline
+sitting next to `phpstan.neon` without being included does nothing.
 
-PHPStans eigen aanwijzingen bij het lezen van bevindingen staan apart in `instructions` en
-worden onder het rapport getoond:
+PHPStan's own guidance for reading findings is kept separately in `instructions` and shown
+below the report:
 
 ```
 PHPStan zegt hierbij:
@@ -692,45 +767,54 @@ PHPStan zegt hierbij:
   Do not add type casts just to silence errors.
 ```
 
-Dat blok is elke run hetzelfde en zegt niets over déze analyse, dus het telt niet mee als
-waarschuwing — en het wordt niet afgekapt, want een half blok aanwijzingen helpt niemand.
+That block is the same every run and says nothing about *this* analysis, so it doesn't count
+as a warning — and it isn't truncated, because half a block of guidance helps nobody.
 
-Het `warnings`-veld staat los van `generalErrors`: dat tweede is PHPStans eigen
-`errors`-array uit de JSON. Beide lijsten zijn begrensd op tien meldingen van elk hoogstens
-1000 tekens — een mislukte Laravel-bootstrap levert anders een lap tekst op die het hele
-antwoord vult. Hoeveel er weggelaten is staat in `omitted`, en in de tekst als "nog N niet
-getoond".
+The `warnings` field is separate from `generalErrors`: the latter is PHPStan's own `errors`
+array from the JSON. Both lists are capped at ten messages of at most 1000 characters each —
+a failed Laravel bootstrap otherwise produces a wall of text that fills the whole response.
+How many were left out is in `omitted`, and in the text as "nog N niet getoond" (N more not
+shown).
 
-## Vereisten
+## Requirements
 
-- Node 20 of nieuwer
-- PHPStan geïnstalleerd in het project zelf (`vendor/bin/phpstan`); de server brengt geen
-  eigen PHPStan mee, want de versie en de extensies horen bij het project
+- Node 20 or newer
+- PHPStan installed in the project itself (`vendor/bin/phpstan`); the server doesn't bring
+  its own PHPStan, because the version and the extensions belong to the project
 
-## Bekende scherpe randen
+## Known sharp edges
 
-- **De PHP-geheugenlimiet.** PHPStan klapt daar met een groot project makkelijk overheen;
-  `memoryLimit: "1G"` lost dat meestal op. De crash komt terug als een gewone fout, met
-  PHPStans eigen uitleg erbij.
-- **Larastan start je Laravel-applicatie.** Lukt dat niet — ontbrekende `.env`, database niet
-  bereikbaar — dan faalt de analyse met de uitleg van Larastan zelf.
-- **Analyses in hetzelfde project draaien na elkaar,** omdat PHPStans resultcache in het
-  project ligt. Verschillende projecten draaien wel tegelijk.
+- **The PHP memory limit.** PHPStan easily exceeds it on a large project;
+  `memoryLimit: "1G"` usually solves that. The crash comes back as a regular error, with
+  PHPStan's own explanation attached.
+- **Larastan boots your Laravel application.** If that fails — missing `.env`, database not
+  reachable — the analysis fails with Larastan's own explanation.
+- **Analyses in the same project run one after another,** because they share one result cache
+  (per project, in the temp directory — not in the project itself). Different projects do run
+  in parallel.
+- **A stale result cache** can make PHPStan crash with a message that seems to make no sense.
+  After a `composer update` that no longer happens, because the cache directory follows
+  `composer.lock`; if it happens some other way anyway, `clear_result_cache` fixes it. The
+  error message itself points to it.
+- **If it works in your terminal but not through the client,** the server is running with a
+  different environment. The Claude app, for example, starts it without `TMPDIR`, and then the
+  per-project cache lives under `/tmp/phpstan-mcp/` instead of under your shell's temp
+  directory.
 
-## Ontwikkelen
+## Development
 
 ```bash
 npm run build        # tsc → dist/
-npm run typecheck    # inclusief de tests
+npm run typecheck    # including the tests
 npm run lint
 npm test
-npm run inspect      # MCP Inspector tegen de gebouwde server
+npm run inspect      # MCP Inspector against the built server
 ```
 
-Dezelfde vier stappen draaien in CI op Node 24, en nog een keer bij een release. `engines`
-belooft `>=20`; die ondergrens is bij het opzetten van CI eenmalig in Docker nagelopen en
-draait niet mee bij elke build.
+The same four steps run in CI on Node 24, and once more on a release. `engines` promises
+`>=20`; that lower bound was checked once in Docker when CI was set up and does not run with
+every build.
 
-## Licentie
+## License
 
 MIT