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:
Top comments (0)