Read AGENTS.md before proposing features, and follow the existing project roadmap. Manual IDE code generators are deprecated and maintenance-only. Prioritize PHP-independent capabilities, AI-assisted development, inspections, and analysis. The portability roadmap excludes code creation.
Repository development skills live in .agents/skills; the skills under skills/ are bundled for users working on Magento applications.
- Check out this repository.
- Open the project in IntelliJ IDEA.
- Make sure that you are on the latest develop branch (for example
5.4.0-develop). - Import the Gradle project from
build.gradle.kts. - Use JDK 25 for both the project SDK and the Gradle JVM.
- In the Gradle tool window, run
Tasks > Intellij platform > runIde. - The task launches a PhpStorm sandbox with the plugin installed. Make sure that the plugin is enabled and indexing is finished before testing features.
Use ./gradlew runIntellijIdea to launch the shared plugin in an IntelliJ IDEA
sandbox. To use an installed IDEA distribution, pass
-PideaPlatformLocalPath=/absolute/path/to/idea. This launches a desktop IDE;
coreTest below runs the separate headless IDEA test application. The same local
IDEA property is supported by coreTest and verifyPlugin -PverifyIntellijIdea=true.
To use an extracted IDE distribution, pass -PplatformLocalPath=/path/to/ide. Windows CI uses the pinned PhpStorm Windows ZIP through this option.
To run ./gradlew test, also install PHP CLI and add php (php.exe on Windows) to PATH. The run-configuration tests launch PHP to verify interpreter settings and command arguments. CI installs PHP 8.4 on Linux, Windows, and macOS.
Shared XML/JSON/project features are registered in src/main/resources/META-INF/plugin.xml. JavaScript-backed features (including RequireJS and Knockout integration in XML/HTML/JSON) are registered in optional withJs.xml; PHP and shared MCP features use withPhp.xml and withMcp.xml, respectively. JavaScript support is optional across IDEs; CSS and image plugins are not required by the shared layer. Integrations that need both PHP and MCP or GraphQL use the optional content-module descriptors in modules/php-mcp/src/main/resources/ and modules/php-graphql/src/main/resources/. Each descriptor declares dependencies on the main plugin and both required plugins. Implementation classes stay in the main plugin JAR; the descriptor modules are packaged separately in lib/modules/.
Run ./gradlew verifyPlugin -PverifyWebStorm=true -PverifyIntellijIdea=true --max-workers=1 --no-parallel after changing these boundaries. This checks the configured PhpStorm, WebStorm, and IntelliJ IDEA versions; also exercise the affected behavior in both IDEs. CI runs the verifier and retains its reports, and publication requires verification to pass.
./gradlew coreTestThis separate test task launches an IntelliJ IDEA test application with JavaScript,
PHP, CSS, and GraphQL disabled. PhpStorm treats its own language plugins as
essential, so disabling them in a PhpStorm sandbox does not establish this boundary.
The tests assert actual loaded plugins and classloader isolation, shared XML
completion registration, active-only reindexing, all eight shared query types, and
XML diagnostics, and literal UI template navigation (attributes, item values,
vendor/theme candidates, and live renames). Literal template lookup is shared;
JavaScript property extraction and dynamic region/component resolution remain in
withJs.xml. Candidate files do not establish Magento's effective theme fallback
or configuration merge. The tests use the existing repository fixture and require
no PHP CLI.
The dedicated test-intellij-idea CI job runs this independently of the ordinary
PhpStorm and WebStorm jobs and uploads its own test reports.
To use an installed IntelliJ IDEA distribution instead of downloading one:
./gradlew coreTest -PcorePlatformLocalPath=/absolute/path/to/ideamagento_diagnostics is registered by the shared desktop MCP toolset and reuses
the same file-scoped runner as HCE. Its help lists the two initial rules, scope,
resource limits, default severities, XML suppression, and incomplete states.
A focused HTTP contract verifies discovery and diagnostic source evidence.
The ui_template inspection query exposes the shared literal template resolver
to both desktop MCP and HCE. Its required templatePath parameter accepts aliases
such as Vendor_Module/widget; results include normalized paths, sorted file
candidates and explicit truncation at 20. Candidates do not establish effective
Magento theme fallback. The HTTP/HCE contracts share
src/test/resources/mcp/ui-template-query.json, including missing modules,
normalization, bounds and live updates.
./gradlew mcpE2eTestThis starts the real bundled JetBrains MCP server in the headless IDE test application, opens an authenticated localhost HTTP session, and sends initialize, notifications/initialized, tools/list, and tools/call requests with the JDK HTTP client. It keeps the server's event stream open and deletes the session during teardown. No AI Assistant, model, API key, manually running IDE, browser, Docker installation, or Magento installation is required. JDK 25 and PHP CLI on PATH are required; Gradle downloads the IDE/test dependencies on the first run.
Each test owns a temporary project and an isolated server session. The suite covers published tool names/descriptions and typed schemas, project routing, actual JSON-RPC and tool errors, Docker-directory wrapper priority, Magento-directory fallback, magerun command paging/search/help, caching, and native MCP configuration. Magerun probes use the production process runner and a local PHP metadata fixture that records arguments, working directory, and environment. The Docker wrapper test uses a local clinotty shim on POSIX systems; it verifies the adapter and never contacts Docker. These fixtures test the plugin's API and runtime invocation, not a particular installed magerun release or container image.
Compatibility workflows now call magento_compatibility through the HTTP endpoint instead of injecting MCP call context or invoking the SDK transport adapter. Local release HTTP fixtures make preparation, progress, cancellation, persistence, and PHP/XML analysis repeatable without external downloads. Pure service tests remain for detailed validation and cache edge cases. Project routing can return plain-text tool errors, while invalid argument types can return JSON-RPC errors before the plugin runs; the tests verify both forms.
The HTTP suites also run with ./gradlew test, so the existing Linux, Windows, and macOS CI jobs exercise them. To run only the CLI/magerun HTTP scenarios:
./gradlew mcpE2eTest --tests '*MagentoMcpHttpTest'Reports are written to build/reports/tests/mcpE2eTest/index.html (or build/reports/tests/test/index.html when using test). The installed IDE's MCP settings and open projects are not used.
Run ./gradlew test --tests '*MagentoExternalDiscoveryMcpTest' for the first-call discovery regression. Unlike the authorized-session fixtures, this test starts the sandbox's global MCP server, selects VIA_ROUTER in McpToolFilterSettings with its default filter, and uses an independent JDK HTTP client against /stream without a private-session token. It sends initialize, opens the event stream, sends notifications/initialized, and immediately requests tools/list. The project has disabled Magento integration, no configured root, and no installed Magento skills. The test restores the sandbox server settings afterward.
Observed on 2026-11-15 with PhpStorm PS-263.7307.215 and plugin 2026.3.6-p1:
- The first
tools/listreturned exactlyexecute_tool,magento_intelligence, andmagento_skills. - Direct
magento_intelligencewithtool: "configure_magento_project"and routedexecute_toolwithcommand: "magento_intelligence --tool configure_magento_project"and the currentprojectPathreturned identical configuration descriptions and argument schemas. - Direct and routed
magento_skills --mode statusreturned the same three missing skills. Discovery and recovery responses left the project settings and instruction/skill files unchanged. - Routed calls that encountered disabled support or an unconfigured root returned both setup-discovery invocation forms and the current
projectPath.
The plugin registers its discovery toolsets through META-INF/withMcp.xml; their McpToolset.alwaysIncluded() overrides keep them directly visible in router mode. The global endpoint uses settings-based session options and filtering; the test does not force visibility through a Magento-only filter. No plugin-owned omission reproduced. A client that exposes only execute_tool to the model despite receiving this three-tool wire list is applying a later client/session exposure policy. The reported Codex omission was not reproduced in this external HTTP test; this test does not inspect Codex's internal model tool selection. Compare that client's own tools/list trace before attributing an omission to it.
The inspected JetBrains build provides mcpToolsProvider, mcpToolset, mcpToolFilterProvider, and mcpManagedSessionSupport extension points, but no extension point for appending plugin discovery hints to the router description. UniversalToolset.execute_tool declares the fixed description “Universal tool executor that can invoke specific IDE MCP tool dynamically.” Its displayDescription(toolName) belongs to UniversalToolset and does not aggregate other plugins' discovery hints. Keep discovery hints in Magento tool descriptions/responses; do not replace or mutate the platform-owned router descriptor. Recheck the SDK when targeting a newer IDE build.
To additionally test compatibility preparation against official release archives:
MAGENTO_MCP_REAL_RELEASE_TEST=true ./gradlew mcpE2eTest --tests '*MagentoCompatibilityCommandsTest.testHttpMcpWithActualMagentoReleases'This opt-in test downloads release sources into a temporary IDE test cache; routine tests need no external network once Gradle dependencies are cached.
- Build a new version of the plugin
- Install the newly created archive/jar file from disk for testing
- Publish
If you are a new GitHub user, we recommend that you create your own free github account. This will allow you to collaborate with the Magento 2 development team, fork this project and send pull requests.
- Search current listed issues (open or closed) for similar proposals of intended contribution before starting work on a new contribution.
- Review and sign the Contributor License Agreement (CLA) if this is your first time contributing. You only need to sign the CLA once.
- Create and test your work.
- Fork this repository and create a pull request.
- Once your contribution is received the Magento 2 development team will review the contribution and collaborate with you as needed.
The module_dependencies query shares native module indexing, XML/JSON PSI, and
PSI-cached snapshots between desktop IDEs and HCE. Its fixture is
src/test/resources/mcp/module-dependencies-query.json. Focused checks:
./gradlew mcpE2eTest --tests '*MagentoMcpHttpTest.testModuleDependenciesOverHttp' --tests '*MagentoMcpHttpTest.testInspectionReportsIndexingAndUnavailableCapabilityOverHttp'
./gradlew coreTest -PideaPlatformLocalPath='/path/to/IntelliJ IDEA.app/Contents'
./gradlew uiTest --tests '*MagentoInspectionUiTest'The first command is the PhpStorm HTTP baseline; the second disables PHP and JavaScript in IntelliJ IDEA; the third exercises WebStorm without PHP. Actual HCE transport and live filesystem updates are verified separately by the standalone HCE runtime suite. These checks do not run Composer or validate installed module state, version satisfaction, effective order, or PHP.