Adobe Commerce Extensibility Tools

MCP (Model Context Protocol) server providing AI-powered tools for Adobe Commerce App Builder extension development. Works with Cursor IDE and other MCP-compatible AI assistants.

🎯 What This Does

This MCP server gives your AI assistant (like Cursor) direct access to Adobe Commerce development tools:

• Deploy and manage Adobe I/O applications
• Subscribe to Commerce events
• Search Commerce documentation with AI-powered RAG
• Configure Adobe I/O projects

📋 Prerequisites

Before installing, make sure you have:

1. Cursor IDE (or another MCP-compatible IDE)
2. Node.js 18+ (LTS recommended)
3. Adobe I/O CLI installed globally:

   npm install -g @adobe/aio-cli

4. Adobe IMS authentication (required for documentation search):

   npm install -g @adobe/aio-cli
   aio auth login

🚀 Installation

Step 1: Clone and Install

# Clone this repository
git clone https://github.com/adobe-commerce/commerce-extensibility-tools.git
cd commerce-extensibility-tools

# Install dependencies
npm install

Step 2: Configure Cursor IDE

Create or update .cursor/mcp.json in your Commerce project directory (not globally):

{
  "mcpServers": {
    "commerce-extensibility-tools": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/commerce-extensibility-tools/index.js"
      ],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Important: Replace /ABSOLUTE/PATH/TO/ with the actual path where you cloned this repository.

Example (macOS/Linux):

{
  "mcpServers": {
    "commerce-extensibility-tools": {
      "command": "node",
      "args": [
        "/Users/yourname/projects/commerce-extensibility-tools/index.js"
      ]
    }
  }
}

Example (Windows):

{
  "mcpServers": {
    "commerce-extensibility-tools": {
      "command": "node",
      "args": [
        "C:\\Users\\yourname\\projects\\commerce-extensibility-tools\\index.js"
      ]
    }
  }
}

Step 3: Copy AI Rules (Optional but Recommended)

Copy the Cursor rules to your project for better AI assistance:

# From your Commerce project directory
cp -r /path/to/commerce-extensibility-tools/rules/Cursor/ .cursor/rules/

These rules teach the AI assistant about Adobe Commerce best practices and workflows.

Step 4: Restart Cursor

Completely quit and restart Cursor IDE to load the MCP server.

Step 5: Verify Installation

In Cursor, you should see the MCP server active. Test it by asking:

"Can you show me the available Adobe Commerce tools?"

🛠️ Available Tools

The MCP server provides 10 tools:

Adobe I/O Application Management

| Tool | Description | |------|-------------| | aio-app-deploy | Deploy Adobe I/O App to runtime (entire app or specific actions) | | aio-app-dev | Start local development server for testing | | aio-app-use | Configure runtime namespace for current project | | aio-dev-invoke | Invoke runtime actions locally during development |

Adobe I/O Configuration

| Tool | Description | |------|-------------| | aio-login | Authenticate with Adobe I/O (OAuth2 flow) | | aio-where | Show current Adobe I/O configuration (org/project/workspace) | | aio-configure-global | Manage global Adobe I/O configuration |

Commerce Integration

| Tool | Description | |------|-------------| | onboard | Configure Adobe I/O event providers and Commerce Events module | | commerce-event-subscribe | Subscribe to Commerce events (products, customers, orders, etc.) |

Documentation Search

| Tool | Description | |------|-------------| | search-commerce-docs | Search Commerce and App Builder documentation using AI-powered RAG |

📚 Documentation Search (RAG System)

The search-commerce-docs tool provides intelligent documentation search powered by Azure RAG with automatic index selection:

Available Documentation Indexes

| Index | Content | Auto-Selected Keywords | |-------|---------|----------------------| | commerce-storefront-docs | Edge Delivery Services, drop-ins, storefront components | storefront, drop-in, EDS, product listing, checkout | | commerce-extensibility-docs | Webhooks, events, extensions, integrations | webhook, event, extension, API mesh, GraphQL | | commerce-core-docs | Core Commerce (catalog, customers, orders) | catalog, product, customer, order, inventory | | app-builder-docs | App Builder, runtime actions, UI extensions | app builder, runtime action, React Spectrum |

How It Works

1. Automatic Authentication: Uses your aio CLI token (from aio auth login)
2. Intelligent Index Selection: Automatically selects the best documentation index based on your query keywords
3. IMS Authentication: Secure authentication via Adobe IMS
4. AI-Powered Search: Semantic search across comprehensive documentation
5. Instant Results: Returns top 5 most relevant results in ~2 seconds

Usage in Cursor

Automatic Index Selection (Recommended): Simply ask natural language questions and the tool will automatically search the right documentation:

"How do I use Edge Delivery Services drop-ins for product listing?"
→ Auto-selects: commerce-storefront-docs

"How do I create a webhook in Adobe Commerce?"
→ Auto-selects: commerce-extensibility-docs

"How to configure product catalog settings?"
→ Auto-selects: commerce-core-docs

"What are App Builder runtime action best practices?"
→ Auto-selects: app-builder-docs

Explicit Index Selection (Advanced): You can also specify which index to search:

"Search commerce-storefront-docs for authentication drop-in"
"Using app-builder-docs, how do I deploy runtime actions?"

The AI will automatically use the search tool and provide relevant documentation from the most appropriate index.

💡 Usage

Once installed, you can use the tools in two ways:

Option 1: Natural Language (Recommended)

Ask Cursor in natural language and it will automatically use the right tool:

"Deploy my Adobe Commerce extension to production"
→ AI uses: aio-app-deploy

"Start the local development server"
→ AI uses: aio-app-dev

"Subscribe to product save events in Commerce"
→ AI uses: commerce-event-subscribe

"How do I handle Commerce webhooks?"
→ AI uses: search-commerce-docs

"Show me my current Adobe I/O workspace"
→ AI uses: aio-where

Option 2: Direct Tool Commands

You can also invoke tools directly using slash commands:

# Deploy your Adobe Commerce extension
/aio-app-deploy

# Start local development server
/aio-app-dev

# Invoke a runtime action locally
/aio-dev-invoke

# Search Commerce documentation
/search-commerce-docs "How to subscribe to Commerce events"

# Configure event providers
/onboard

# Subscribe to Commerce events
/commerce-event-subscribe

# Show current Adobe I/O configuration
/aio-where

# Login to Adobe I/O
/aio-login

🔧 Troubleshooting

MCP Server Not Loading

Check Cursor MCP Settings:

1. Open Cursor Settings (Cmd+, or Ctrl+,)
2. Search for "MCP"
3. Verify commerce-extensibility-tools server is listed
4. Check for any error messages

Verify mcp.json:

# Check if file exists in your project
cat .cursor/mcp.json

# Verify the path is correct and absolute
ls -la /path/to/commerce-extensibility-tools/index.js

Authentication Errors

The documentation search tool requires Adobe IMS authentication:

# Login to Adobe I/O (will open browser)
aio auth login

# Verify you're logged in
aio where

# Test token retrieval
aio auth login --bare

If you encounter authentication errors, try logging out and back in:

aio auth logout
aio auth login

Advanced Configuration

Custom APIM Endpoint (Optional)

By default, the documentation search uses the production Azure API Management endpoint. For testing or development purposes, you can override this with the APIM_URL environment variable.

To use a custom endpoint, add it to your Cursor MCP configuration:

{
  "mcpServers": {
    "commerce-extensibility-tools": {
      "command": "node",
      "args": ["/path/to/commerce-extensibility-tools/index.js"],
      "env": {
        "NODE_ENV": "production",
        "APIM_URL": "https://your-custom-apim-endpoint.azure-api.net"
      }
    }
  }
}

Note: Most users should use the default production endpoint and do not need to set this variable.

Tool Not Found

If Cursor can't find a specific tool:

1. Restart Cursor completely (Quit and reopen)
2. Check MCP server logs in Cursor's developer console
3. Verify installation:

   cd commerce-extensibility-tools
   npm install
   node index.js
   # Should start without errors

Path Issues (Windows)

On Windows, use forward slashes or escaped backslashes:

// ✅ Good
"args": ["C:/Users/yourname/projects/commerce-extensibility-tools/index.js"]

// ✅ Also good
"args": ["C:\\Users\\yourname\\projects\\commerce-extensibility-tools\\index.js"]

// ❌ Bad
"args": ["C:\Users\yourname\projects\commerce-extensibility-tools\index.js"]

📁 Project Structure

commerce-extensibility-tools/
├── index.js                    # MCP server entry point
├── package.json                # Dependencies and configuration
├── README.md                   # This file
│
├── src/                        # MCP Server Implementation
│   ├── server.js               # MCP server core
│   ├── tools/                  # Tool implementations (10 tools)
│   │   ├── aio-app-deploy.js
│   │   ├── aio-app-dev.js
│   │   ├── aio-app-use.js
│   │   ├── aio-configure-global.js
│   │   ├── aio-dev-invoke.js
│   │   ├── aio-login.js
│   │   ├── aio-where.js
│   │   ├── onboard.js
│   │   ├── commerce-event-subscribe.js
│   │   └── search-commerce-docs.js
│   ├── schemas/                # JSON schema definitions
│   └── utils/                  # Utility functions
│
└── rules/                      # AI Assistant Rules
    ├── Cursor/                 # Cursor IDE rules (19 files)
    │   ├── main-orchestrator.mdc
    │   ├── adobe-commerce-basics.mdc
    │   ├── app-builder-technical-guide.mdc
    │   └── ... (16 more)
    ├── Claude/                 # Claude AI rules
    ├── Copilot/                # GitHub Copilot rules
    └── Gemini/                 # Google Gemini rules

🧪 Testing

Test the MCP server using the MCP Inspector:

# Run the inspector
npm test

# Or manually
npx @modelcontextprotocol/inspector node index.js

The inspector provides a web UI to:

• Test all 10 tools with custom inputs
• Inspect tool schemas and descriptions
• Monitor server logs and responses
• Debug connectivity issues

📖 Documentation

• Adobe Developer App Builder - App Builder documentation
• Adobe Commerce Developer - Commerce developer resources
• Model Context Protocol - MCP specification
• Cursor IDE - Cursor documentation

🔐 Security & Privacy

• IMS Authentication: All API calls use Adobe IMS OAuth2 tokens
• No Data Storage: MCP server doesn't store any credentials or data
• Local Execution: All tools run locally on your machine
• Secure Communication: Documentation search uses HTTPS with token validation

🆘 Support

For issues and questions:

• Adobe I/O CLI: Adobe Developer Documentation
• Adobe Commerce: Adobe Commerce Developer Documentation
• MCP Protocol: Model Context Protocol
• Cursor IDE: Cursor Documentation

🤝 Contributing

This is a distribution repository. Active development happens in a private repository.

For issues or suggestions, please contact the Adobe Commerce extensibility team.

📄 License

Apache License, Version 2.0. See LICENSE for details.

🆕 Version 2.0 Alpha - Enhanced Documentation Search

For Alpha/Beta Testers

Breaking Change: Version 2.0+ requires Adobe IMS authentication and uses an enhanced backend.

Installation

npm install -g @adobe-commerce/commerce-extensibility-tools@alpha

Prerequisites

1. Install Adobe I/O CLI (if not already installed):

   npm install -g @adobe/aio-cli

2. Authenticate with Adobe IMS:

   aio auth login

What's New

• Enhanced documentation search with improved relevance
• Intelligent automatic index selection across 4 documentation sets
• Better integration with Adobe IMS authentication
• Improved search performance (~2s response time)

For Production Users (v1.x)

Continue using the stable version:

npm install -g @adobe-commerce/commerce-extensibility-tools@^1.6.0

Migration Timeline

• Now - Beta Period: Internal testing with select partners
• TBD: GA release of v2.0 (replaces v1.x as default)

For detailed migration instructions, see MIGRATION_GUIDE.md.

Compatibility: Adobe Commerce PaaS & SaaS | App Builder Framework | Node.js 18+
Version: 2.0.0-alpha.1
Last Updated: 2025-11-25