adobe-commerce-docs-mcp

<p align="center">
  <img src="assets/logo.png" alt="Adobe Commerce Docs MCP logo" width="120" height="120">
</p>

# Adobe Commerce Docs MCP Server

[![npm version](https://img.shields.io/npm/v/adobe-commerce-docs-mcp)](https://www.npmjs.com/package/adobe-commerce-docs-mcp)
[![CI](https://github.com/jigarkkarangiya/adobe-commerce-docs-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/jigarkkarangiya/adobe-commerce-docs-mcp/actions)
[![License: Source-Available](https://img.shields.io/badge/License-Source--Available-lightgrey.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 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.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | Yes | Search keywords (e.g., `"graphql product query"`, `"checkout configuration"`) |
| `limit` | number | No | Max results to return (1–50, default: 15) |
| `section` | string | No | Filter by section slug (see [Available Sections](#available-sections)) |

### `get_doc_content`

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `url` | string | Yes | Full URL of the doc page from search results |

### `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.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `url` | string | Yes | Full URL of the doc page |

### `get_page_toc`

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `url` | string | Yes | Full URL of the doc page |

### `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.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `url` | string | Yes | Full URL of the doc page |
| `heading` | string | Yes | Heading text to find (e.g., `"tunnel"`, `"SSH Tunnel Setup"`) |

### `get_related_docs`

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `url` | string | Yes | Full URL of the doc page |
| `limit` | number | No | Max related pages (1–30, default: 10) |

### `lookup_error_code`

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `error` | string | Yes | Error code or message (e.g., `"MDVA-43395"`, `"Unable to serialize value"`) |

### `multi_page_search`

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

| Parameter | Type | Required | Description |
|---|---|---|---|
| `queries` | string[] | Yes | Array of search queries (1–5) |
| `limit_per_query` | number | No | Max results per query (1–20, default: 5) |
| `section` | string | No | Optional section filter for all queries |

### `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:

| Section Slug | Description |
|---|---|
| `commerce-admin` | Admin panel, catalog, customers, orders, stores configuration |
| `commerce-operations` | Installation, upgrade, configuration, CLI tools, patches |
| `commerce-cloud-service` | Cloud infrastructure, deployment, environments |
| `commerce-on-cloud` | Cloud architecture, CLI/branches, CDN & Fastly VCL, dev tools & integrations |
| `commerce-merchant-services` | Live Search, Product Recommendations, Payment Services |
| `commerce-channels` | Amazon Sales Channel, Channel Manager |
| `commerce-knowledge-base` | Troubleshooting articles and known issues |
| `commerce-learn` | Tutorials and video guides |
| `commerce-business-intelligence` | Reporting and analytics |

---

## Resources

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

| URI | Description |
|---|---|
| `commerce://sections` | All documentation sections with page counts |
| `commerce://stats` | Server status: version, uptime, index size |
| `commerce://docs/{section}` | Browse all pages within a section (supports autocomplete) |

---

## Prompts

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

| Prompt | Arguments | Description |
|---|---|---|
| `troubleshoot-commerce-error` | `error_message` | Search Knowledge Base, provide root cause + solution + prevention |
| `explain-commerce-concept` | `topic` | Explain a concept with code examples and best practices from official docs |
| `commerce-code-review` | `code` | Review PHP/XML/JS code against official Commerce coding standards |
| `commerce-upgrade-guide` | `from_version`, `to_version` | Generate upgrade checklist with breaking changes and rollback plan |

---

## Quick Setup for Cursor

### Option A: Automatic Setup Script (Linux / macOS)

Run this single command in your terminal:

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

Or if you have the repo cloned:

```bash
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:

```bash
node --version
```

If you don't have it, install from [nodejs.org](https://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:

| Field | Value |
|---|---|
| **Name** | `adobe-commerce-docs` |
| **Type** | `command` |
| **Command** | `npx -y adobe-commerce-docs-mcp` |

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:

| OS | Path |
|---|---|
| **Linux** | `~/.cursor/mcp.json` |
| **macOS** | `~/.cursor/mcp.json` |
| **Windows** | `%USERPROFILE%\.cursor\mcp.json` |

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

```json
{
  "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:

| OS | Config Path |
|---|---|
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |
| **Linux** | `~/.config/Claude/claude_desktop_config.json` |

```json
{
  "mcpServers": {
    "adobe-commerce-docs": {