Merge pull request #569 from mulesoft/W-20701354-acb-troubleshooting-update-feature-branch

W-20701354 Updating troubleshooting topics

Author: Cristian-Venticinque

modules/ROOT/assets/images/icon-gear.png

@@ -112,6 +112,7 @@
 ** xref:troubleshoot-authentication-errors.adoc[]
 ** xref:troubleshoot-implementation-errors.adoc[]
 ** xref:troubleshoot-deploy-errors.adoc[]
+** xref:troubleshoot-mcp-server.adoc[]
 
 * xref:acb-reference.adoc[Reference]
 ** xref:ref-connectors.adoc[Connectors]

modules/ROOT/assets/images/icon-restart-mcp-server.png

@@ -10,18 +10,18 @@ If results are still inconsistent, verify that your project context and Mulesoft
 
 == Troubleshoot Mulesoft Vibes Access Errors
 
-If you can't open Mulesoft Vibes, verify the following:
+If you can't open MuleSoft Vibes, verify the following:
 
 * You are logged in to Anypoint Platform from the IDE. For more information, see xref:start-acb.adoc#log-in-to-anypoint-platform-from-the-ide[Log in to Anypoint Platform from the IDE].
 * You have the xref:start-configure-permissions.adoc#permissions[required Anypoint Code Builder permissions], including:
 ** *Mule Developer Generative AI User*
-* You have the required permissions for the tools in the MuleSoft MCP Server that Mulesoft Vibes uses to generate accurate responses.  
+* You have the required permissions for the tools in the MuleSoft MCP Server that MuleSoft Vibes uses to generate accurate responses.  
 
 [[required-permissions]]
-=== Required Permissions for Mulesoft Vibes
+=== Required Permissions for MuleSoft Vibes
 
-Mulesoft Vibes always uses the permissions of the logged-in Anypoint Platform user.  
-Mulesoft Vibes cannot perform any action that the user does not already have permission to perform.
+MuleSoft Vibes always uses the permissions of the logged-in Anypoint Platform user.  
+MuleSoft Vibes can't perform any action that the user doesn't already have permission to perform.
 
 Here are the permissions required across capabilities in the MuleSoft MCP Server:
 

modules/ROOT/assets/images/mcp-server-output-dropdown.png

@@ -0,0 +1,94 @@
+= MCP Server Issues
+:page-deployment-options: cloud-ide, desktop-ide
+
+include::reuse::partial$beta-banner.adoc[tag="anypoint-code-builder"]
+
+When using the MuleSoft MCP Server in Anypoint Code Builder, you might encounter issues that prevent the server from functioning correctly. Follow these troubleshooting steps to diagnose and resolve common MCP server problems.
+
+[[verify-mcp-server]]
+== Verify the MCP Server Is Running
+
+If MuleSoft Vibes isn't responding to commands or tools aren't available, verify that the MuleSoft MCP Server is running:
+
+. Open the MuleSoft Vibes panel in Anypoint Code Builder.
+. Click *Manage MCP Servers*.
+. Click image:anypoint-code-builder::icon-gear.png["",18,18] (Settings) to open the MCP Server settings.
+. In the *Installed* tab, verify that the MuleSoft MCP Server is enabled (toggled on and marked in green).
++
+If the server is disabled, toggle it on to enable it.
++
+image:mcp-server-settings.png["The MCP server panel showing the Settings icon and the Enable toggle.",30%,30%]
+
+[[check-mcp-logs]]
+== Check MCP Server Logs
+
+When the MCP server isn't working as expected, check the logs to identify the cause:
+
+//step to open output panel:
+include::partial$acb-reusable-steps.adoc[tags="open-output-panel"]
+. From the dropdown list in the Output panel, select *Anypoint Code Builder - MCP Server*.
++
+image:mcp-server-output-dropdown.png["The outputs panel showing the MCP Server selected in the dropdown menu."]
+
+. Review the logged information for errors or warnings.
++
+The logs provide details about server operations, tool executions, and any errors that occur.
+
+You can also check the *Tasks* section in the Output panel for additional errors or warnings related to MCP server operations.
+
+[[restart-mcp-server]]
+== Restart the MCP Server
+
+If the MCP server stops responding or behaves unexpectedly, restart it:
+
+. Open the MuleSoft Vibes panel in Anypoint Code Builder.
+. Click *Manage MCP Servers*.
+. Click image:anypoint-code-builder::icon-gear.png["",18,18] (Settings) to open the MCP Server settings.
+. In the *Installed* tab, locate the MuleSoft MCP Server.
+. Click image:anypoint-code-builder::icon-restart-mcp-server.png["",18,18] (Restart Server).
++
+When the server restarts successfully, you see a confirmation message in the Output panel.
+
+If restarting doesn't resolve the issue, try disabling and then re-enabling the server.
+
+[[validate-mcp-server]]
+== Validate MCP Server Configuration
+
+You can validate whether the MCP server is running correctly by using third-party tools:
+
+. In the MCP Server settings, select *Configure MCP Servers* to view the server configuration.
+. Use an API client like Postman to send test requests to the MCP server endpoint.
+. Verify that the server responds correctly to your requests.
+
+If the server doesn't respond, check that the configuration in the `a4d_mcp_settings.json` file is correct.
+
+[[mcp-tools-unavailable]]
+== MCP Server Tools Are Unavailable
+
+If MCP server tools aren't appearing or aren't responding:
+
+. Verify that the MuleSoft MCP Server is enabled in the *Installed* tab of the MCP Server settings.
+. Check that the tools are enabled for the server:
++
+.. In the *Installed* tab, select the MuleSoft MCP Server to expand its details.
+.. Verify that the required tools are listed and enabled.
+. Restart the MCP server.
+. If the issue persists, check the MCP server logs for errors.
+
+[[mcp-timeout]]
+== MCP Server Request Timeout
+
+If requests to the MCP server are timing out:
+
+. Open the MCP Server settings.
+. In the *Installed* tab, select the MuleSoft MCP Server.
+. Locate the *Request Timeout* setting.
+. Increase the timeout value to allow more time for the server to respond.
+
+For complex operations, a longer timeout might be required.
+
+== See Also
+
+* xref:a4d-mcp-server.adoc[]
+* xref:troubleshooting.adoc[]
+* xref:troubleshoot-generative-ai.adoc[]

modules/ROOT/assets/images/mcp-server-settings.png

@@ -63,7 +63,7 @@ Workspace: Configure Workspace Trust Settings
 ----
 . Review and adjust the workspace settings, as needed.
 
-== Incomplete Flow
+== Incomplete Flow or Corrupted XML
 
 If a flow lacks a component or contains only a trigger, such as an HTTP Listener operation or the Scheduler, an error similar to the following appears in the *Problems* panel and from the configuration XML: 
 
@@ -78,3 +78,4 @@ To address this issue, add processing components or connector operations to your
 // Pointer to component reference:
 include::partial$acb-component-info.adoc[tags="note-component-ref"]
 
+This error can also occur if XML tags in the configuration file are corrupted or not properly closed. If you've already added components and the error persists, check the configuration XML for unclosed tags. To prevent XML corruption, save your work frequently and use source control management (SCM) to back up your projects.

modules/ROOT/nav.adoc

@@ -61,3 +61,19 @@ This request is _not_ from MuleSoft or Anypoint Code Builder:
 image::troubleshoot-download-java-notification.png["Notification showing a request to download and install a JDK to compile a project"]
 
 Instead of using this feature, you can use the command *Download Mule Runtime and Java Versions*. See xref:anypoint-code-builder::int-versions.adoc[].
+
+[[reinstall-mule-runtime]]
+== Reinstall Mule Runtime
+
+If your Mule runtime installation becomes corrupted, you can force a reinstallation:
+
+. Close Anypoint Code Builder.
+. Navigate to your Mule runtimes directory: `${user.home}/AnypointCodeBuilder/runtimes`.
+. Remove or rename the folder for the runtime version you want to reinstall (for example, `mule-4.6.0`).
+. Open Anypoint Code Builder.
+. Select the Mule runtime version from *Project Properties*.
++
+The IDE downloads and reinstalls the selected version. For details on selecting versions, see xref:int-versions.adoc#project-version-mule-java[Select Mule and Java Versions for a Project].
+
+[NOTE]
+Your projects and other installed runtimes are not affected.

modules/ROOT/pages/troubleshoot-generative-ai.adoc

@@ -15,6 +15,7 @@ Troubleshoot errors and warnings you receive when using Anypoint Code Builder:
 * xref:troubleshoot-implementation-errors.adoc[]
 * xref:troubleshoot-mule-runtime-errors.adoc[]
 * xref:troubleshoot-loading-errors.adoc[]
+* xref:troubleshoot-mcp-server.adoc[]
 +
 For other issues and workarounds, see xref:acb-release-notes.adoc#known-issues[Known Issues] in the Anypoint Code Builder Release Notes.
 
@@ -140,3 +141,33 @@ The configuration sidebar also displays validation messages at the node level.
 Field-level errors appear inline during component configuration.
 
 Hover over a component with a red dot to view error details in the canvas.
+
+[[clean-reinstall]]
+== Perform a Clean Reinstallation
+
+If you experience persistent issues that other troubleshooting steps don't resolve, perform a clean reinstallation of Anypoint Extension Pack:
+
+. Close VS Code completely.
+. Uninstall Anypoint Extension Pack:
++
+.. Open VS Code.
+.. From the Activity Bar, open the *Extensions* panel.
+.. Find and select *Anypoint Extension Pack*.
+.. Click *Uninstall*.
+.. Close VS Code.
+. Delete the `anypoint-code-builder` folder from your user directory:
++
+* Mac: `~/AnypointCodeBuilder`
+* Windows: `C:\Users\<username>\AnypointCodeBuilder`
+. Optionally, delete cached extension data from the VS Code extensions folder:
++
+* Mac: `~/.vscode/extensions/`
+* Windows: `C:\Users\<username>\.vscode\extensions\`
++
+Remove any folders starting with `salesforce.mule-dx-` or `mulesoftinc.mule-dx-`.
+. Reopen VS Code and reinstall Anypoint Extension Pack from the Extensions Marketplace.
+
+[NOTE]
+--
+This procedure removes downloaded Mule runtimes and Java versions. You can re-download them after reinstalling.
+--