Supercharging Adobe Commerce development: introducing the adobe-commerce-docs-mcp server

Jigar Karangiya — Tue, 02 Jun 2026 06:36:26 +0000

If you write code for Adobe Commerce or Magento 2, you spend a lot of time waiting. Build times are slow, static content deployment takes forever, but the real time sink is documentation. The EAV architecture, nested XML layouts, and ever-changing GraphQL mutations mean you are constantly Alt-Tabbing to a browser to double check a syntax pattern.

Every time you leave your IDE to search the Experience League portal, you lose your train of thought. You copy error codes, dig through unrelated search results, and try to find a working code snippet. It is exhausting.

I wanted my coding assistant to just know this stuff without making me look it up. That is why I configured this MCP server.

The adobe-commerce-docs-mcp package connects your IDE directly to the official Adobe documentation. It works with Cursor, Claude Desktop, VS Code, and Windsurf, pulling raw markdown docs right into your chat context.

The architecture: bridging AI and docs

Instead of relying on web search or stale training data, the server queries the live Adobe Experience League site. It indexes the content locally, caches pages, and handles queries via the MCP protocol.

1. BM25 search ranking

The server parses the official Adobe sitemap and ranks pages using BM25 relevance scoring. This is the same search algorithm databases use to weigh search term frequency against document length. It means your assistant gets the most relevant setup guide first, not just the page that mentions a keyword the most.

2. Synonyms and fuzzy matching

You do not have to query exact terminology. The search engine maps Magento specific synonyms:

graphql searches also find pages with gql
module searches also match extension
cloud searches match ece

It also corrects simple typos like chekout or catlog to checkout and catalog.

3. Local caching

Network requests are slow, so the server uses two layers of caching:

An in-memory cache for recent queries.
A persistent file cache on your disk. Sitemap data lasts 24 hours, while downloaded markdown pages last 7 days. This makes subsequent queries instant and saves API calls.

Nine built-in tools

The server registers nine tools that your assistant can run.

Tool	What it does
search_adobe_commerce_docs	Searches the indexed sitemap with synonym expansion.
get_doc_content	Pulls clean markdown content of a page.
get_code_examples	Extracts only the code blocks, skipping long text to save tokens.
get_page_toc	Fetches heading titles so the model can inspect page structure first.
get_related_docs	Finds sibling or related pages in the documentation tree.
lookup_error_code	Queries specific error codes like MDVA-43395.
multi_page_search	Runs up to five queries at once and combines unique results.
list_doc_sections	Lists all root categories of the documentation.
refresh_sitemap	Force refreshes the cached sitemap index.

Configured resources

Resources are static URIs the model can browse. You can query:

commerce://sections: Lists sections.
commerce://stats: Shows cache sizes and index counts.
commerce://docs/{section}: Shows page lists for a specific category.

Ready prompts

The server exposes built-in prompts to handle common workflows:

troubleshoot-commerce-error: Helps resolve issues from log outputs.
explain-commerce-concept: Walkthroughs of things like plugins or dependency injection.
commerce-code-review: Audits files against Adobe Commerce standards.
commerce-upgrade-guide: Planning advice for version upgrades.

Installation and setup

You do not need to clone the repo or build the files yourself. The server runs via npx.

One-click config for Cursor

If you use Cursor, open your terminal and run this installer:

bash <(curl -sS https://raw.githubusercontent.com/jigarkkarangiya/adobe-commerce-docs-mcp/main/setup-cursor.sh)

This script adds the configuration to your settings file automatically.

Manual config

You can also add it manually. Edit your settings file depending on the application:

Cursor (mcp.json)

{
  "mcpServers": {
    "adobe-commerce-docs": {
      "command": "npx",
      "args": [
        "-y",
        "adobe-commerce-docs-mcp"
      ]
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "adobe-commerce-docs": {
      "command": "npx",
      "args": [
        "-y",
        "adobe-commerce-docs-mcp"
      ]
    }
  }
}

Environment variables

You can change default behaviors by setting environment variables in your configuration:

SITEMAP_URL overrides the default Experience League source link.
CACHE_DIR specifies the directory for cached files, which defaults to ~/.cache/adobe-commerce-docs-mcp.
SITEMAP_CACHE_TTL_MS controls sitemap refresh frequency, defaulting to 24 hours.
PAGE_DISK_CACHE_TTL_MS controls page cache lifetime, defaulting to 7 days.
MAX_CONTENT_LENGTH limits output length to 15,000 characters to keep context size manageable.
PORT changes the port if you run the server using HTTP mode with the --http flag.

Example prompts

Once active, you can query your assistant using natural language.

If you ask: "Find code examples for creating a custom GraphQL mutation in Magento 2.4," the model runs search_adobe_commerce_docs, locates the mutation guide, and calls get_code_examples to output the XML and PHP schemas.

If you ask: "I am getting error MDVA-43395 during deployment. Check what this is and how to fix it," the model uses lookup_error_code to inspect the knowledge base entry and details the steps required to resolve the issue.

If you ask: "Review this plugin configuration in di.xml and tell me if it matches best practice," the model pulls up guidelines using the commerce-code-review template to audit your configuration against official standards.

Getting started

This package helps you stay in your editor and avoid losing focus. If you want to check it out or contribute, the source code and packages are available on GitHub and NPM:

Patch to Debug Blocks and Containers in Magento 2

Jigar Karangiya — Thu, 11 Apr 2024 08:18:39 +0000

Hello Devs,
In this tutorial, we will see how to add comments in the page HTML which shows block and template container names.

Magento provides template hints but its design is too confusing and frustrating. It hurts when you have limited hours to complete your task and are stuck in finding which PHTML file is rendering and which block is responsible for the logic.

Today, I will share a patch I created to show comments in the page source. It will not affect the front end and not be visible to customers.

Please do not use this in the production environment, use it only in your local setup.

You can check comments inside the developer tool of the between and starting of the HTML element.

Let’s check how.

Download my patch from the URL below and put it inside the m2-hotfixes/ or Root Directory.

Patch download link : https://gist.github.com/jigarkkarangiya/7a99ffd0049b90e7622e2a5e83c9219c

It will show the comment on the page below :

That’s it. Now you can easily debug which .phtml file and which block is responsible for rendering the content.

I hope this article helped you to find what you were looking for.

Bookmark it for your future reference. Do comment below if you have any other questions on that.

Do share this trick with your team.

Thank you. Happy Desiging !!

DEV Community: Jigar Karangiya