Adobe Commerce Docs MCP Server

An MCP (Model Context Protocol) server that gives AI assistants direct access to the official Adobe Commerce / Magento documentation. It indexes the Adobe Experience League sitemap and provides tools, resources, and prompts to search, browse, and read documentation pages — all from within your AI coding assistant.

Features

• 10 tools — search, read pages, browse sections, fetch one section of a long page, find related docs, extract code examples, get page TOC, lookup errors, multi-query search, and refresh
• Structured tool output — every tool returns typed structuredContent (JSON Schema outputSchema) alongside human-readable markdown, so clients can parse results programmatically
• Tool annotations — all tools declare readOnlyHint/openWorldHint/idempotentHint so MCP clients can reduce confirmation friction for safe, read-only operations
• MCP Resources — browsable commerce:// URIs for sections and doc pages, capped at 300 entries per section read to stay context-safe
• MCP Prompts — reusable workflows for troubleshooting, code review, upgrades, and concept explanation
• BM25 search — relevance-ranked results with IDF weighting and document-length normalization
• Synonym expansion — graphql also matches gql, cloud matches ece, module matches extension, and 40+ more
• Fuzzy matching — tolerates typos like chekout → checkout, catlog → catalog
• Smart truncation — cuts at heading boundaries instead of mid-sentence
• Instant cold start — indexes from a sitemap snapshot bundled with the package, then refreshes live in the background — no blocking on a live sitemap fetch to answer your first query
• Persistent cache — disk cache for both sitemap (24h) and page content (7 days), survives restarts
• HTTP transport — --http flag for remote/team deployment via Streamable HTTP
• Docker ready — multi-stage Dockerfile for containerized deployment
• Configurable — all settings tunable via environment variables
• Zero config — just add one line to your MCP config and go

Tools

search_adobe_commerce_docs

BM25-ranked search with synonym expansion and fuzzy matching.

get_doc_content

Fetch the full content of a documentation page as clean markdown.

get_code_examples

Extract only the code blocks from a documentation page. Returns fenced code snippets without surrounding prose — much more token-efficient than fetching the full page.

get_page_toc

Get the heading hierarchy (table of contents) of a page. Useful for understanding structure before fetching the full content.

get_doc_section

Fetch just one section of a page by heading name (case-insensitive, substring match), including its nested subheadings. Use this for long pages where get_doc_content's full-page fetch would truncate before reaching the section you need — check get_page_toc first to find the heading name.

get_related_docs

Find sibling/related pages in the same section of the documentation tree.

lookup_error_code

Search the Knowledge Base for an error code or message. Auto-fetches the top result for immediate answers.

multi_page_search

Search with multiple queries in one call. Returns de-duplicated results — reduces round-trips when researching from multiple angles.

list_doc_sections

List all available documentation sections with page counts. No parameters.

refresh_sitemap

Force-refresh the cached sitemap data, and clear the on-disk page content cache (individually cached per page for up to 7 days) so subsequently fetched pages come back fresh instead of stale. No parameters.

Available Sections

Use these slugs with the section parameter:

Resources

MCP Resources let AI clients browse data directly via URIs — no tool call needed.

Prompts

MCP Prompts are reusable workflows that work across all MCP clients (Cursor, Claude Desktop, VS Code, Windsurf, etc.).

Quick Setup for Cursor

Option A: Automatic Setup Script (Linux / macOS)

Run this single command in your terminal:

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

Or if you have the repo cloned:

bash setup-cursor.sh

The script will:

• Check that Node.js 18+ is installed
• Create or update your ~/.cursor/mcp.json
• Tell you to restart Cursor

Option B: Manual Setup (All Platforms — 3 Steps)

Prerequisites

You need Node.js 18+ installed. Check by running:

node --version

If you don't have it, install from nodejs.org.

Step 1: Open MCP Settings in Cursor

1. Open Cursor
2. Go to Settings (gear icon in bottom-left, or Ctrl + , / Cmd + ,)
3. In the left sidebar, click "MCP"
4. Click "+ Add new MCP server"

Step 2: Add the Server

A dialog will appear. Fill it in:

Click "Add".

Step 3: Verify

You should see adobe-commerce-docs in your MCP list with a green dot (active).

Open any chat in Agent mode and try:

"Search Adobe Commerce docs for checkout configuration"

Option C: Edit Config File Directly

Open (or create) the MCP config file:

Add this JSON (if the file already has other servers, merge the adobe-commerce-docs block into the existing mcpServers object):

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

Restart Cursor after saving.

Setup for Other Tools

Claude Desktop

Add to your Claude Desktop config:

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

VS Code / GitHub Copilot

Add to .vscode/mcp.json in your project root:

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

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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

Usage Examples

Once connected, just ask naturally in any AI chat:

How It Works

┌─────────────┐     ┌──────────────────────────┐     ┌─────────────────────────┐
│  AI Client   │────▶│  MCP Server (v2.0)        │────▶│  Adobe Experience League │
│  (Cursor,    │◀────│                          │◀────│  sitemap.xml + .md pages │
│   Claude,    │     │  10 Tools                │     │                         │
│   VS Code)   │     │  3 Resources             │     └─────────────────────────┘
│              │     │  4 Prompts               │
└─────────────┘     └──────────────────────────┘
                      │
                      ├─ BM25 search with synonym expansion + fuzzy matching
                      ├─ Pre-warms sitemap on startup
                      ├─ Fetches .md endpoints (native markdown)
                      ├─ Memory LRU cache: 100 pages, 1h TTL
                      ├─ Disk page cache: 7-day TTL (survives restarts)
                      └─ Disk sitemap cache: 24h TTL

1. On startup, indexes instantly from a sitemap snapshot bundled with the package (built fresh at every npm publish), then refreshes live from Adobe Experience League in the background — search works immediately instead of blocking on a live ~77MB sitemap fetch, and self-corrects to fully live data within seconds. A valid 24h disk cache skips this and loads straight from disk.
2. Builds an inverted index with BM25 scoring, synonym mappings, and document frequency stats
3. When you search, terms are expanded with synonyms and matched with fuzzy fallback for typos
4. When you ask for page content, fetches the native .md version (clean markdown, no HTML parsing needed)
5. Falls back to HTML fetch + conversion if .md is unavailable
6. Smart truncation cuts at heading boundaries instead of mid-sentence
7. Pages are cached on disk (7 days) and in memory (LRU, 100 pages, 1 hour)

HTTP Transport

For team/remote deployment, run the server in HTTP mode:

npm run start:http
# or
npx adobe-commerce-docs-mcp --http

This starts a Streamable HTTP server on port 3000 (configurable via PORT env var).

Docker

docker build -t adobe-commerce-docs-mcp .
docker run -p 3000:3000 adobe-commerce-docs-mcp

Configuration

All settings are configurable via environment variables:

Troubleshooting

MCP server failed to start

• Verify Node.js 18+ is installed: node --version
• Test the command manually in a terminal:
  Terminal

  Copy

  npx -y adobe-commerce-docs-mcp
  

• If you're behind a corporate proxy, ensure npm can reach the registry:
  Terminal

  Copy

  npm config set registry https://registry.npmjs.org/
  

Green dot doesn't appear in Cursor

• Click the refresh icon next to the server name in MCP settings
• Restart Cursor completely
• Check Cursor's Output panel for error messages

"No results found" for searches

• The sitemap loads on first use (takes a few seconds). Wait and try again.
• Use broader keywords: "checkout" instead of "checkout multishipping step 3"
• Synonym expansion handles many aliases automatically (gql → graphql, ece → cloud, etc.)
• Ask the AI to run refresh_sitemap to reload the latest data

Slow first response

• The first query triggers sitemap loading (~2–5 seconds). Subsequent queries are instant.
• The sitemap is cached on disk for 24 hours, and page content is cached for 7 days, so restarts are fast.

Development

Run from Source

git clone https://github.com/jigarkkarangiya/adobe-commerce-docs-mcp.git
cd adobe-commerce-docs-mcp
npm install
npm run build
npm start

Dev Mode (auto-reload)

npm run dev          # stdio transport
npm run dev:http     # HTTP transport

Run Tests

npm test

Project Structure

adobe-commerce-docs-mcp/
├── src/
│   ├── index.ts          # MCP server: tools, resources, prompts, transport
│   ├── sitemap.ts        # Sitemap loading, BM25 search, synonyms, fuzzy matching
│   ├── content.ts        # Page fetching, markdown/HTML parsing, structured extraction
│   └── config.ts         # Environment variable configuration
├── tests/
│   ├── search.test.ts    # Search, Levenshtein, synonym expansion tests
│   └── content.test.ts   # Content extraction, TOC, smart truncation tests
├── dist/                 # Compiled JS (generated by `npm run build`)
├── .cursor/
│   ├── rules/            # Cursor auto-apply rules for this MCP
│   └── prompts/          # Cursor slash commands (/commerce-search, etc.)
├── .github/workflows/    # CI/CD: build, test, publish
├── Dockerfile            # Multi-stage Docker build for HTTP deployment
├── setup-cursor.sh       # One-command Cursor setup script
├── package.json
├── tsconfig.json
├── LICENSE
└── README.md

Contributing

1. Fork the repo
2. Create a branch: git checkout -b my-feature
3. Make your changes
4. Build and test: npm run build && npm test
5. Commit and push
6. Open a Pull Request

Requirements

• Node.js 18 or later

Find This MCP

Related MCPs

• adobe-commerce-dev-docs-mcp — Adobe Commerce developer docs (developer.adobe.com/commerce)
• aem-live-docs-mcp — AEM / Edge Delivery Services docs (aem.live)
• adobe-app-builder-docs-mcp — Adobe App Builder — serverless, I/O Runtime, Commerce extensibility
• adobe-api-mesh-docs-mcp — Adobe API Mesh — GraphQL gateway & source handlers
• adobe-commerce-kb-mcp — Adobe Commerce Support Knowledge Base — troubleshooting & patches
• adobe-io-events-docs-mcp — Adobe I/O Events — webhooks, journaling & event providers

Changelog

See CHANGELOG.md for what's new, fixed, changed, and improved in each release.

License

Source-Available — All Rights Reserved

The source is public for transparency and evaluation. You may install and run the unmodified package for personal, educational, or internal non-commercial use. Modification, forking, redistribution, and commercial use are not permitted without prior written permission. See LICENSE for full terms.

© 2026 Jigar Karangiya · LinkedIn