Merge pull request #2690 from vitaliyboykocontributor/mcp-stuff

MCP enhancements

Author: VitaliyBoyko

CHANGELOG.md

@@ -31,6 +31,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0).
   `find_acl_or_menu`
 - Magento MCP CLI environment discovery for AI agents. The `describe_magento_cli_environment` tool exposes project-local wrapper commands, including Mark Shust Docker-style `bin/*` scripts such as `bin/magento` and `bin/n98-magerun2`, so agents can prefer those wrappers over global binaries.
 
+### Fixed
+
+- Illegal char <|> [#2669](https://github.com/magento/magento2-phpstorm-plugin/issues/2669)
+
 ## 2026.1.1
 
 ### Added

README.md

@@ -5,7 +5,7 @@
 </p>
 
 <!-- Plugin description -->
-# Magento 2 and Adobe Commerce Support
+# Magento 2 and Adobe Commerce
 
 <table align="center" style="border-collapse: collapse; width: 100%; text-align: center;">
   <caption style="font-size: 1.2em; margin-bottom: 10px;">
@@ -66,7 +66,7 @@
 
 1. Go to `Settings > Preferences` in the PhpStorm IDE
 2. Navigate to `Plugins`
-3. Click the `Browse repositories...` button and search for "Magento 2 and Adobe Commerce Support"
+3. Click the `Browse repositories...` button and search for "Magento 2 and Adobe Commerce"
 4. Install the plugin and restart PhpStorm
 5. Go to `Settings > Preferences > Languages & Frameworks > PHP > Frameworks > Magento` in the PhpStorm IDE
 6. Check `Enable` and click the `OK` button
@@ -103,17 +103,18 @@ Available query and inspection tools:
 * `find_layout_entities`: finds layout handles, block names, and container names by exact or partial value such as `catalog_product_view`, `product.info.main`, or `checkout`.
 * `find_ui_component`: finds UI component XML definitions by exact or partial component file name such as `product_form`, `sales_order_grid`, or `category_form` without the `.xml` extension.
 * `find_acl_or_menu`: finds ACL resource IDs and admin menu entries by exact or partial identifier such as `Magento_Catalog::catalog` or `Foo_Bar::manage_items`.
-* `describe_magento_cli_environment`: detects project-local CLI wrappers such as Mark Shust Docker scripts under `bin/`, returns the exact command paths an agent should use, and includes example invocations for Magento CLI, PHP, Composer, and `n98-magerun`.
+* `describe_magento_cli_environment`: detects project-local CLI wrappers such as Mark Shust Docker scripts under project-level or Magento-root `bin/`, returns the exact command paths an agent should use, and includes example invocations for Magento CLI, PHP, Composer, `n98-magerun`, and stack lifecycle commands such as `./bin/start`.
 
 Notes:
 
 * The IDE MCP server must be enabled in the JetBrains IDE.
+* Only one JetBrains IDE instance should have the MCP server enabled at a time so the configured MCP port stays free; if another IDE is already using that port, the MCP server will not start correctly.
 * The IDE MCP server entry must be added to the agent MCP configuration.
 * MCP tools work against the currently opened IDE project.
 * Magento plugin support must be enabled for the project.
 * Indexing must be finished before MCP queries and generators can run.
 * Category EAV attribute generation creates both the data patch and `view/adminhtml/ui_component/category_form.xml`.
-* `describe_magento_cli_environment` detects project-local wrappers such as Mark Shust Docker scripts under `bin/` and returns the exact command paths an agent should use.
+* `describe_magento_cli_environment` detects project-local wrappers such as Mark Shust Docker scripts under project-level or Magento-root `bin/` and returns the exact command paths an agent should use, including stack lifecycle wrappers such as `bin/start`, `bin/stop`, and `bin/restart`.
 
 ### MCP CLI wrapper configuration
 
@@ -123,13 +124,15 @@ If your Magento project uses local wrapper scripts such as Mark Shust Docker com
 
 Use a comma-separated list of relative paths, for example:
 
-`bin/magento, bin/n98-magerun2, bin/cli`
+`bin/magento, bin/n98-magerun2, bin/cli, bin/start`
 
 Agent usage pattern:
 
 1. Call `describe_magento_cli_environment`.
-2. Use the returned wrapper path exactly, for example `./bin/magento cache:flush` or `./bin/n98-magerun2 sys:info`.
-3. Prefer the wrapper over global binaries because these scripts often enter Docker containers or a project-specific runtime.
+2. Use the returned wrapper path exactly, for example `./bin/magento cache:flush`, `./bin/n98-magerun2 sys:info`, or `./bin/start`.
+3. Keep Magento code edits and generators under the configured Magento root.
+4. If the tool reports a wrapper outside that root, still run it from the returned project-relative path; that is valid for nested Magento roots.
+5. Prefer the wrapper over global binaries because these scripts often enter Docker containers or a project-specific runtime.
 
 ## Setting up development environment
 

gradle.properties

@@ -1,5 +1,5 @@
 pluginGroup = com.magento.idea.magento2plugin
-pluginName = Magento 2 and Adobe Commerce Support
+pluginName = Magento 2 and Adobe Commerce
 pluginRepositoryUrl = https://github.com/magento/magento2-phpstorm-plugin
 pluginVersion = 2026.2.0
 pluginSinceBuild = 261.21525.38

settings.gradle.kts

@@ -3,7 +3,7 @@
  * See COPYING.txt for license details.
  */
 
-rootProject.name = "Magento 2 and Adobe Commerce Support"
+rootProject.name = "Magento 2 and Adobe Commerce"
 
 plugins {
     id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0"

src/main/java/com/magento/idea/magento2plugin/init/ConfigurationManager.java

@@ -239,7 +239,7 @@ private static void showPopup(Project project, String message, Function<Notifica
         Runnable runnable = () -> {
             notifyGlobally(
                     project,
-                    "Magento 2 and Adobe Commerce Support",
+                    "Magento 2 and Adobe Commerce",
                     message,
                     NotificationType.INFORMATION,
                     actions
@@ -250,7 +250,7 @@ private static void showPopup(Project project, String message, Function<Notifica
 
     public static void notifyGlobally(@Nullable Project project, String title, String message, NotificationType notificationType, Function<Notification, AnAction>... actions) {
         Notification notification = new Notification(
-                "Magento 2 and Adobe Commerce Support",
+                "Magento 2 and Adobe Commerce",
                 title,
                 message,
                 notificationType

src/main/java/com/magento/idea/magento2plugin/reference/provider/PhpClassReferenceProvider.java

@@ -20,6 +20,7 @@
 import com.magento.idea.magento2plugin.util.RegExUtil;
 import java.util.ArrayList;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.List;
 import java.util.Locale;
 import java.util.regex.Matcher;
@@ -51,33 +52,33 @@ public class PhpClassReferenceProvider extends PsiReferenceProvider {
         String namespacePart;
         final List<PsiReference> psiReferences = new ArrayList<>();
 
-        for (int i = 0; i < fqnParts.length - 1; i++) {
-            namespacePart = fqnParts[i];
-            namespace.append('\\');
-            namespace.append(namespacePart);
-
-            final String namespaceId = namespace
-                    .toString()
-                    .toLowerCase(Locale.ROOT);
-
-            final Collection<PhpNamespace> references = hasNamespaceInIndex(
-                    namespaceId,
-                    element.getProject()
-            ) ? phpIndex.getNamespacesByName(namespaceId) : new ArrayList<>();
-
-            if (!references.isEmpty()) {
-                final TextRange range = new TextRange(
-                        origValue.indexOf(classFQN) + namespace.toString().lastIndexOf(92),
-                        origValue.indexOf(classFQN) + namespace.toString().lastIndexOf(92)
-                                + namespacePart.length()
-                );
-                psiReferences.add(new PolyVariantReferenceBase(element, range, references));
+        try {
+            for (int i = 0; i < fqnParts.length - 1; i++) {
+                namespacePart = fqnParts[i];
+                namespace.append('\\');
+                namespace.append(namespacePart);
+
+                final String namespaceId = namespace
+                        .toString()
+                        .toLowerCase(Locale.ROOT);
+
+                final Collection<PhpNamespace> references = hasNamespaceInIndex(
+                        namespaceId,
+                        element.getProject()
+                ) ? getNamespacesByName(phpIndex, namespaceId) : Collections.emptyList();
+
+                if (!references.isEmpty()) {
+                    final TextRange range = new TextRange(
+                            origValue.indexOf(classFQN) + namespace.toString().lastIndexOf(92),
+                            origValue.indexOf(classFQN) + namespace.toString().lastIndexOf(92)
+                                    + namespacePart.length()
+                    );
+                    psiReferences.add(new PolyVariantReferenceBase(element, range, references));
+                }
             }
-        }
-        final String className = classFQN.substring(classFQN.lastIndexOf(92) + 1);
 
-        try {
-            final Collection<PhpClass> classes = phpIndex.getAnyByFQN(classFQN);
+            final String className = classFQN.substring(classFQN.lastIndexOf(92) + 1);
+            final Collection<PhpClass> classes = getClassesByFqn(phpIndex, classFQN);
 
             if (!classes.isEmpty()) {
                 final TextRange range = new TextRange(
@@ -93,6 +94,20 @@ public class PhpClassReferenceProvider extends PsiReferenceProvider {
         return psiReferences.toArray(new PsiReference[0]);
     }
 
+    protected Collection<PhpNamespace> getNamespacesByName(
+            final @NotNull PhpIndex phpIndex,
+            final @NotNull String namespaceId
+    ) {
+        return phpIndex.getNamespacesByName(namespaceId);
+    }
+
+    protected Collection<PhpClass> getClassesByFqn(
+            final @NotNull PhpIndex phpIndex,
+            final @NotNull String classFqn
+    ) {
+        return phpIndex.getAnyByFQN(classFqn);
+    }
+
     /**
      * Check if php namespace index has specified identifier.
      *
@@ -101,7 +116,7 @@ public class PhpClassReferenceProvider extends PsiReferenceProvider {
      *
      * @return boolean
      */
-    private boolean hasNamespaceInIndex(
+    protected boolean hasNamespaceInIndex(
             final @NotNull String namespaceIdentifier,
             final @NotNull Project project
     ) {

src/main/kotlin/com/magento/idea/magento2plugin/mcp/MagentoBlockCommands.kt

@@ -22,7 +22,7 @@ internal object MagentoBlockCommands {
                 resolveRequest(project, moduleName, blockClassFqn)
             }
         } catch (_: ReadAction.CannotReadException) {
-            return "The request was cancelled by a pending write action. Retry."
+            return MagentoMcpReadActionSupport.cancellationMessage()
         } catch (exception: BlockValidationException) {
             return exception.message ?: "Block creation request is invalid."
         }

src/main/kotlin/com/magento/idea/magento2plugin/mcp/MagentoCliCommandCommands.kt

@@ -45,7 +45,7 @@ internal object MagentoCliCommandCommands {
                 )
             }
         } catch (_: ReadAction.CannotReadException) {
-            return "The request was cancelled by a pending write action. Retry."
+            return MagentoMcpReadActionSupport.cancellationMessage()
         } catch (exception: CliCommandValidationException) {
             return exception.message ?: "CLI command creation request is invalid."
         }