@adobe-commerce/commerce-extensibility-tools

v2.5.0

Published

9 hours ago

MCP server providing Adobe Commerce extensibility tools for AI-powered development

0High
0Medium
0Low

mcp cursor adobe adobe-commerce app-builder aio deployment ai-tools commerce-extensibility

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
Upload feedback and chat history (with IMS authentication)

📋 Prerequisites

Before installing, make sure you have:

Cursor IDE (or another MCP-compatible IDE)
Node.js 22+ (LTS recommended)
Adobe I/O CLI installed globally:
```
npm install -g @adobe/aio-cli
```
Adobe IMS authentication (required for documentation search and feedback upload):
```
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: Set Up Cursor Commands (Optional but Recommended)

Copy pre-configured Cursor commands to your project for quick access to MCP tools:

# From your Commerce project directory
mkdir -p .cursor/commands
cp /path/to/commerce-extensibility-tools/commands/Cursor/* .cursor/commands/

What this does:

Creates shortcut commands in Cursor IDE (e.g., @search-commerce-docs, @aio-app-deploy)
Provides quick access to all MCP tools without typing full tool names
Makes it easier to discover and use available MCP tools

Available Commands:

@search-commerce-docs - Search Adobe Commerce documentation
@aio-app-deploy - Deploy Adobe I/O App
@aio-app-dev - Start local development server
@aio-app-use - Configure runtime namespace
@aio-configure-global - Change global Adobe I/O config
@aio-dev-invoke - Invoke local runtime action
@aio-login - Log in to Adobe I/O
@aio-where - Show current configuration
@commerce-event-subscribe - Subscribe to Commerce events
@onboard - Configure event providers

Note: Other IDEs (VSCode, Claude Desktop) may support similar command systems in the future. Check the commands/ directory for IDE-specific command files.

Step 5: Restart Cursor

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

Step 6: 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 11 tools and 1 prompt:

Note: All tools support both programmatic use and interactive prompts. Prompts provide a more user-friendly way to interact with tools through natural language.

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 |

Feedback & Support

| Tool | Description | |------|-------------| | upload-chat-history | Uploads chat history and user feedback to the feedback service. Requires IMS authentication via aio auth login. |

MCP Prompts

The MCP server provides the following prompts for enhanced user interaction:

| Prompt | Description | |--------|-------------| | feedback | Collects user feedback about their experience, including errors, issues, suggestions, and general comments. The conversation history is automatically collected, sanitized to remove sensitive data, and uploaded along with the feedback to help improve the service. |

📚 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

Automatic Authentication: Uses your aio CLI token (from aio auth login)
Intelligent Index Selection: Automatically selects the best documentation index based on your query keywords
IMS Authentication: Secure authentication via Adobe IMS
AI-Powered Search: Semantic search across comprehensive documentation
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

"Provide feedback about my experience"
→ AI uses: feedback prompt

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

# Provide feedback about your experience
/feedback

Feedback Collection

The feedback prompt helps collect user feedback to improve the service:

Collect Feedback: The AI will ask you about your experience, any errors encountered, issues faced, or suggestions for improvement
Automatic History Collection: The conversation history is automatically collected from the current chat session
IMS Authentication: Uses your Adobe IMS token (from aio auth login) for secure upload
Local Backup: Chat history is saved locally in a chats/ folder with timestamp-based filenames
Server Upload: Both feedback and chat history are uploaded to the official feedback service

Authentication: The feedback upload requires Adobe IMS authentication. Make sure you've run aio auth login before using the feedback feature.

Data Sanitization: Before uploading, sensitive data is automatically sanitized from the chat history. The following types of sensitive information are removed or replaced with placeholders:

API keys, access tokens, and authentication credentials → Replaced with [API_KEY], [TOKEN], etc.
Passwords, secret keys, and private keys → Replaced with [PASSWORD], [SECRET], etc.
Personal Identifiable Information (PII): email addresses, phone numbers, addresses, SSNs → Replaced with [EMAIL], [PHONE], [ADDRESS], etc.
Credit card numbers and bank account information → Replaced with [CREDIT_CARD], [ACCOUNT_NUMBER], etc.
Internal IP addresses, hostnames, or infrastructure details → Replaced with [IP_ADDRESS], [HOSTNAME], etc.
Any other confidential or proprietary information → Replaced with appropriate placeholders

Example - Before and After Sanitization:

Before (Original Chat):

[USER]
I'm having trouble with my API key: sk_live_51H8k2jK3mN9pQrS7tUvWxYz1234567890
Can you help me deploy my app? My email is [email protected]
The server is at 192.168.1.100:8080

[ASSISTANT]
I can help you deploy. First, let's check your configuration.

After (Sanitized for Upload):

[USER]
I'm having trouble with my API key: [API_KEY]
Can you help me deploy my app? My email is [EMAIL]
The server is at [IP_ADDRESS]

[ASSISTANT]
I can help you deploy. First, let's check your configuration.

Data Privacy: Chat history is saved locally in the chats/ folder with timestamp-based filenames for your records. The sanitized version is uploaded to the feedback service.

🔧 Troubleshooting

MCP Server Not Loading

Check Cursor MCP Settings:

Open Cursor Settings (Cmd+, or Ctrl+,)
Search for "MCP"
Verify commerce-extensibility-tools server is listed
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

Both the documentation search and feedback upload tools require Adobe IMS authentication:

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

# Verify you're logged in
aio where

If you encounter authentication errors (401 Unauthorized), try logging out and back in:

aio auth logout
aio auth login

Advanced Configuration

Custom Front Door Endpoint (Optional)

By default, the documentation search uses the production Azure Front Door endpoint with WAF protection. For testing or development purposes, you can override this with the FRONT_DOOR_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",
        "FRONT_DOOR_URL": "https://your-custom-front-door-endpoint.a02.azurefd.net"
      }
    }
  }
}

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

Security: The production endpoint is protected by Azure Front Door with:

Web Application Firewall (WAF) with Microsoft Default RuleSet 2.1 and Bot Manager RuleSet 1.0
Geo-blocking for US embargoed countries (Cuba, Iran, North Korea, Syria, Crimea, Luhansk, Donetsk)
DDoS protection at the edge
APIM backend locked down to only accept traffic from Front Door

Tool Not Found

If Cursor can't find a specific tool:

Restart Cursor completely (Quit and reopen)
Check MCP server logs in Cursor's developer console

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 (11 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
│   │   └── upload-chat-history.js
│   ├── schemas/                # JSON schema definitions
│   ├── prompts/                # MCP prompt definitions and handlers
│   │   ├── index.js
│   │   ├── feedback.json
│   │   └── handlers/
│   │       └── feedback.js
│   └── 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 11 tools and 1 prompt with custom inputs
Inspect tool schemas and descriptions
Monitor server logs and responses
Debug connectivity issues

Feedback Upload Issues

If feedback upload fails:

Authentication: Ensure you've run aio auth login - the feedback service requires IMS authentication
Network Connectivity: Ensure you have internet access and the server endpoint is reachable
Local Files: Check the chats/ folder in your current directory - chat history is always saved locally even if upload fails
Rate Limiting: If you see a 429 error, wait a moment and try again
Server Response: Review the error message for specific server-side issues

📖 Documentation

AI Coding Tools for Extensions - Complete setup and usage guide
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: Documentation search and feedback upload 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: All API calls use HTTPS with token validation
Local Backup: Chat history is saved locally in chats/ folder before upload

🆘 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.