← All posts

I turned on LSP for Adobe Commerce in Claude Code. It silently did nothing.

intelephense found all twenty-odd references. Claude Code showed none. Why the LSP tool drops results in gitignored files, and the Adobe Commerce-aware MCP server that cut tool calls by more than five times and got every answer right.

On this page · 10 sections
  1. Why I went looking
  2. Why bother with LSP?
  3. Why "just turn it on" wasn't enough
  4. Measure first: a headless benchmark
  5. Debugging the wrong layer, five times
  6. What the PHP LSP benchmark showed
  7. The alternative: an Adobe Commerce-aware MCP server
  8. Instructions didn't change behaviour. Hooks did.
  9. Caveats, stated plainly
  10. What I'd tell another Adobe Commerce team

TL;DR

  • Claude Code's LSP tool runs git check-ignore on every navigation result and silently drops anything gitignored. On an Adobe Commerce (Magento 2) project, that's vendor/ at minimum. On one client project, it was everything.
  • The error you see, "not fully indexed", points at the wrong layer. Run git check-ignore on the file before you debug indexing.
  • For Adobe Commerce wiring questions (plugins, observers, DI), the magento2-lsp MCP server answered every question correctly where Grep got most of them right, with more than five times fewer tool calls at about two fifths lower cost.
  • Instructions in CLAUDE.md didn't change Claude's tool choice. A hook did.

Zero. That's how many times Claude Code had called its LSP tool across about eighty saved sessions on one of my projects, a large Adobe Commerce Cloud marketplace build: a Mirakl connector and more than twenty custom modules installed through Composer into vendor/<client>/. intelephense was installed. The TypeScript server wasn't. Every "who calls this method?" question had been answered by Grep, file by file.

Why I went looking

This didn't start as a tooling experiment. It started with three problems that kept recurring on that project.

Navigation was slow. Questions any Adobe Commerce developer answers in their IDE in seconds, like "who calls this?" or "which class implements this interface?", took Claude a long chain of searches and file reads. On a codebase this size, I'd regularly sit watching it grep its way through vendor/ for something my IDE would find with one click.

Answers were sometimes wrong, or quietly incomplete. A grep that misses one caller doesn't fail. It returns a confident, partial answer. More than once Claude told me it had found every place a method was used, or every plugin on a class, and I caught a missing one later. In a marketplace integration, a missed caller is the difference between a safe refactor and a broken order sync. (In the PHP navigation benchmark further down, Grep gets all ten answers right; those questions are small and direct. The misses came in real sessions, on bigger questions, and they show up again in the wiring benchmark.)

The one that stuck: Claude listed the plugins on an order-sync method and missed one declared in another module's di.xml. I found out when a refactor changed the method's signature and that plugin broke in testing.

It was expensive. Every grep hit that Claude has to check is another file read into context. Long navigation sessions burned through tokens, and on heavy days, through my usage limits, on work that wasn't the actual task.

In a typical navigation-heavy session, roughly half the tool calls were Grep and file reads just to find the code.

A language server should fix all three, because it answers navigation questions from an index instead of from text matches. When I checked, intelephense was already installed. The audit of those sessions explained the rest: Claude had never once called it.

Why bother with LSP?

Grep finds text. A language server finds meaning. For a coding agent, that difference shows up as a bill.

Ask Claude "who calls save() on this repository?" with only Grep, Glob and Read, and it has to work like a junior developer with grep -rn. It searches for the method name, gets every save( in the codebase, and opens file after file to check which class each call actually belongs to. Adobe Commerce makes this worse than most codebases. Method names like execute, save and getById repeat across thousands of classes. Calls go through interfaces resolved by di.xml. And vendor/ holds tens of thousands of PHP files to search through. Every false match costs a Read, and every Read lands in the context window.

A language server has already parsed the code. It knows types, inheritance and which class a variable holds, so it can answer the questions an agent asks most often with one precise call:

  • findReferences: real callers of this exact method on this exact class, not every method that happens to share the name.
  • goToImplementation: the classes that implement an interface, without guessing from file names.
  • hover: a symbol's type and return type, without reading the whole class.
  • documentSymbol: a class's methods and properties as a list, without loading the file into context.

In theory, that means fewer tool calls, fewer tokens and fewer wrong answers caused by a missed or misread grep hit. The baseline numbers below show where the theory should pay off: finding a method's callers or its usages cost Claude well over ten tool calls, where a working language server needs one.

Why "just turn it on" wasn't enough

I turned LSP on properly. I followed the "Setting it up" steps in this guide to LSP in Claude Code, enabled the official php-lsp plugin, and added a "Code Intelligence: prefer LSP over Grep/Glob/Read" section to my global ~/.claude/CLAUDE.md. I skipped ENABLE_LSP_TOOL, because Claude Code 2.1.316 already ships the tool. Plugins are enabled per project in .claude/settings.local.json: php-lsp on the Adobe Commerce projects, typescript-lsp on the TypeScript ones.

Then I went back to work and watched. The plugin was on. The instruction was in CLAUDE.md. Claude still reached for Grep on almost every navigation question, and on the rare occasion it tried LSP, it got nothing back and grepped anyway. So I benchmarked it properly, and the first run showed no improvement at all.

That's when this stopped being a five-minute setup and became a debugging project. Either LSP doesn't help on Adobe Commerce, or my setup was broken. The numbers couldn't tell me which.

It took a couple of evenings. The turning point was running intelephense directly: it returned all twenty-odd references, and Claude Code showed none.

Measure first: a headless benchmark

Going by feel is how you convince yourself a tool helps. I wrote a small Python harness around headless Claude Code instead:

claude -p "$TASK" --output-format stream-json --verbose --max-turns 30 \
  --allowedTools Read,Grep,Glob,LSP \
  --disallowedTools Bash,Agent,Write,Edit,WebFetch,WebSearch \
  --strict-mcp-config --mcp-config '{"mcpServers":{}}' \
  --settings '{"enabledPlugins":{...}}' \
  --append-system-prompt "$PREFER_LSP"

The script parses the stream for tool calls by tool, input tokens, cost and wall time, then checks each answer against a known-correct one. There are five PHP navigation tasks, each run twice per configuration: find a method's callers (T1), find an interface's implementing class (T2), find usages including a webapi.xml reference (T3), work out a return type (T4), and list a class's methods (T5).

The baseline, with LSP off, shows where Grep hurts:

TaskTool callsInput tokensCostTime
T1 callers15–20 (mostly Grep)about 300kabout 20 centsabout 40 s
T2 implementera few100–150kabout 10 cents10–20 s
T3 usage incl. webapi.xmlabout 20about 350kabout 20 centsabout 45 s
T4 return typea fewabout 150kabout 15 centsabout 50 s
T5 list methodsa fewabout 150kabout 15 centsabout 15 s

T1 and T3 are exactly the calls findReferences should replace.

Debugging the wrong layer, five times

1. The index was cold every session

The official plugin starts intelephense with nowhere to store its index. So every session re-indexed tens of thousands of PHP files in vendor/, which took about five minutes. My benchmark sessions last a minute at most. findReferences therefore always answered "LSP server has not fully indexed the workspace", and Claude fell back to Grep. Only documentSymbol, which reads a single file, worked.

I wrote a local plugin, php-lsp-magento, that gives intelephense a persistent index location:

"initializationOptions": {
  "storagePath": "~/.cache/intelephense",
  "globalStoragePath": "~/.cache/intelephense"
}

Reload time dropped from about five minutes to about twenty seconds, and later to about ten. A warm-up script pre-builds the index. A second Adobe Commerce project indexed tens of thousands of files in under five minutes, and the cache for the two projects comes to under 200 MB.

2. The server starts lazily

Claude Code starts the language server on the first LSP call in a session, not at session start. So the first lookup in every session comes back empty. That's annoying, but at least it's predictable.

3. Unclean shutdowns throw the index away

If an intelephense process isn't shut down cleanly, it discards the saved index and forces a full rebuild of about five minutes. Until that rebuild finishes, only hover and documentSymbol work.

4. Missing settings mean no indexing at all

This one's subtle. If the plugin's settings key is absent, Claude Code advertises workspace.configuration: false. If settings is {}, Claude Code answers intelephense's workspace/configuration request with [null, null]. Either way, intelephense never indexes the workspace. It only knows about open files, which explains why hover and documentSymbol worked while findReferences stayed empty.

The fix, in plugin v1.0.3, is a non-empty settings block that does nothing except restate a default:

"settings": {
  "intelephense": { "files": { "maxSize": 1000000 } }
}

5. The real blocker: gitignored results are dropped

Even after all that, references were still empty. So I put a tee wrapper on intelephense's stdin and stdout, and read the raw protocol traffic. intelephense returned all twenty-odd references for the method under test. Inside the same Claude Code session, the LSP tool reported "No references found… not fully indexed".

The cause: Claude Code's LSP tool runs git check-ignore on every location returned by findReferences, goToDefinition, goToImplementation and workspaceSymbol, and silently drops any gitignored file. Setting respectGitignore: false in settings.json doesn't change it; the key isn't in the current settings docs either. hover, documentSymbol and diagnostics aren't filtered, which is why they kept working and kept me looking at indexing.

The marketplace project's .gitignore starts with *, a whitelist style. All of its custom code lives in vendor/<client>/*. Every navigation result was being thrown away before Claude saw it.

git check-ignore -v vendor/<vendor>/<module>/Model/SomeService.php

"Not fully indexed" was the server being blamed for a filter in the client. Check ignore rules before you touch indexing.

What the PHP LSP benchmark showed

RunCorrectTool callsLSP callsGrep callsInput tokensCostTime
Baseline (LSP off)allabout 100about 7about 210kabout 15 centsabout 30 s
LSP on, cold indexallabout 10under 1about 5about 240kabout 15 centsabout 30 s
LSP on, "warm" indexallabout 9under 1about 5about 220kabout 12 centsabout 25 s

The differences between rows are run-to-run noise, because every navigation result was filtered out in all three. The cold run is the instructive one. The "prefer LSP" instruction cost about a seventh more input tokens, because Claude dutifully tried LSP, got nothing, and then grepped anyway. Without the benchmark, I'd have called that an improvement.

How much LSP navigation helps depends entirely on what git ignores:

Projectvendor/app/codeLSP navigation
The marketplace projectignoredignored (.gitignore is *)none
A few other Adobe Commerce projectsignoredtrackedworks inside app/code, misses calls into vendor/

So I turned PHP LSP off on the marketplace project and kept it on for the others. The global CLAUDE.md now says two things. A "No references found" for code under a gitignored path is unreliable, so switch to Grep immediately. And the first call after a lazy start may return only the declaration.

TypeScript doesn't have the problem

typescript-lsp works in my TypeScript projects, because their source is tracked in git. findReferences returned every reference in one project and a handful across a few files in another, matching Grep both times. There are two gotchas. tsserver needs about 7 seconds after the lazy start, and a findReferences inside that window returns only the declaration; Claude once read that as "no usages". And typescript-language-server must be on PATH when Claude starts. Mine was installed under nvm's Node 24, so Claude has to be launched from a shell where nvm is loaded.

The alternative: an Adobe Commerce-aware MCP server

The more useful realisation was that for Adobe Commerce, a PHP call graph is the wrong model anyway. Plugins, observers and DI preferences live in XML. "Who hooks into this?" isn't a find-references question.

magento2-lsp from Mage-OS (npm @mage-os/magento2-lsp 0.1.0, MIT, sponsored by Hyvä) ships two servers. Its LSP server has the same gitignore problem, so it's no use here. Its MCP server, magento2-lsp-mcp, works, because MCP tool results don't pass through the LSP tool's filter.

It exposes magento_get_di_config, magento_resolve_class, magento_get_plugins_for_method, magento_get_event_observers, magento_get_template_overrides, magento_get_class_hierarchy, magento_get_module_overview, magento_get_db_schema, magento_search_symbols, magento_get_class_context and magento_rescan_project. Each takes a filePath inside the project. It doesn't cover webapi.xml routes and ACL, or PHP "find callers".

A smoke test answered four questions in under half a minute, including session start. The index is cached at the project root in .magento2-lsp-cache.json, which is a few tens of MB.

The wiring benchmark: magento2-lsp MCP against Grep

I ran it on the same headless claude -p harness as the PHP benchmark. The baseline allowed Read, Grep and Glob. The MCP run added the server plus a one-line nudge to use magento_* tools first. There were five wiring questions, two runs each, with expected answers checked by hand against the XML and the PHP autoloader:

  • M1: the DI preference for a service interface.
  • M2: every observer on sales_order_place_after (about half a dozen expected, across core and third-party modules).
  • M3: every plugin on Magento\Quote\Model\Quote::addProduct, which needs method-level matching.
  • M4: the REST route and ACL resource for a service method.
  • M5: every event a custom tax module observes.
RunCorrectTool callsInput tokensCostTime
Grep/Read/Glob onlymostabout 20about 280kabout 20 centsabout 40 s
+ magento2-lsp MCPallabout 4about 140kabout 12 centsunder 20 s

That's more than five times fewer tool calls, about two fifths cheaper and about twice as fast, with every answer correct. Per question:

QuestionBaselineWith MCP
M1 DI preferenceright in both runs, a handful of callsright in both runs, a couple of calls
M2 observers on eventright in one of two runs; one run made over a hundred Grep/Glob calls, cost about 50 cents, took about two minutes, and still missed observersright in both runs, a few calls, under 20 s
M3 plugins on methodwrong in both runs, about 30 calls each, missed plugins both timesright in both runs, a few calls, about 20 s
M4 webapi route and ACLright in both runsright in both runs; MCP not used (no webapi tool), no gain
M5 module's eventsright in both runsright in both runs, about the same cost

The wins land exactly on "find everything that hooks into X" questions. Answering those by hand means scanning every di.xml and events.xml across hundreds of modules, then opening each plugin class to check which methods it actually intercepts. Grep does that expensively at best and incompletely at worst. The MCP server answers from a prebuilt index in one call. Where it has no tool, as with M4, it makes no difference.

Instructions didn't change behaviour. Hooks did.

Next I added magento2-lsp-mcp as a local MCP server in several Adobe Commerce projects. I put the cache file into .git/info/exclude where it wasn't already ignored. And I wrote a rule into the global and project CLAUDE.md: use magento_* tools first for DI, plugins, observers, templates, class hierarchy and db_schema, and Grep webapi.xml.

By 5 November Claude was still grepping events.xml and di.xml. The reason was mechanical. The MCP tools were deferred: Claude Code lists their names but needs a ToolSearch call to load their schemas. Against that extra step, Grep looked cheaper, so Grep won. A sentence in CLAUDE.md doesn't change that maths.

So I wrote a guard hook (bash, in global settings; a later one taught me to refuse, not rewrite) that's active only when the project root contains bin/magento:

HookEffect
SessionStart (startup, resume, clear, compact)Injects a reminder to use the magento_* tools, with the one-line ToolSearch command that loads them all
PreToolUse on Grep or BashBlocks searches targeting di.xml, events.xml, crontab.xml or db_schema.xml, and XML greps for <plugin, <preference or <observer, then names the right tool. webapi.xml, acl.xml, PHP code, git diff and Read on a known file stay allowed
PostToolUseFailure on any magento2-lsp toolUnlocks Grep for the rest of that session

There's also a manual escape: add # lsp-fallback: <reason> to the Bash command, and the reason stays visible in the transcript. I tested it live. A grep on events.xml was blocked, and the same grep with the marker went through.

grep -rn "sales_order_place_after" --include=events.xml vendor/ # lsp-fallback: checking a module the index skipped

A guard without an escape hatch is an outage waiting to happen. This one has two.

One line in my global CLAUDE.md also gives each session a papercuts log of what slowed it.

Caveats, stated plainly

  • magento2-lsp is v0.1.0. One answer gave a plugin count that didn't match the plugins it listed, and the module overview shows plugin target classes as "unknown". Check counts before you act on them.
  • The sample is small: five tasks, two runs each. The direction is clear; the exact percentages aren't.
  • I observed the gitignore filtering in Claude Code 2.1.316 and saw it again on 2.1.319. Later versions may behave differently, so run git check-ignore on your own setup before trusting either result.

What I'd tell another Adobe Commerce team

  1. When you see "not fully indexed", run git check-ignore <file> before you debug indexing. The LSP tool drops gitignored results, and every Adobe Commerce project ignores vendor/, so navigation can return nothing while the server works perfectly.
  2. For intelephense under Claude Code, set a non-empty settings object or it never indexes. Persist storagePath, and expect the first call in a session to come back empty.
  3. Benchmark with headless claude -p and stream-json. My cold-index "improvement" was actually worse.
  4. For framework wiring, a domain-aware MCP server beats a generic language server, because in Adobe Commerce the wiring lives in XML.
  5. Enforce tool choice with hooks, and give every hook two ways out: an automatic unlock when the tool fails, and a manual escape marker.

The setup around this is in Claude Code on WSL and my herdr setup.

Written by Vishwas Bhatnagar

Technical Architect. Adobe Commerce, marketplaces and AI-assisted engineering.

More about me →

More