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)
• AI Agent Skills for guided extension development (architecture, coding, testing, deployment, and more)

📋 Prerequisites

Before installing, make sure you have:

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

   npm install -g @adobe/aio-cli
   

4. 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": {
      "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": {
      "command": "node",
      "args": [
        "/Users/yourname/projects/commerce-extensibility-tools/index.js"
      ]
    }
  }
}

Example (Windows):

{
  "mcpServers": {
    "commerce-extensibility": {
      "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 2 prompts:

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

Adobe I/O Configuration

Commerce Integration

Documentation Search

Feedback & Support

MCP Prompts

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

🤖 AI Agent Skills

The project includes 7 AI agent skills bundled with the Integration Starter Kit (dist/integration-starter-kit/skills/). These skills provide specialized, role-based guidance that AI assistants can follow to deliver expert-level help at every stage of extension development.

Available Skills

How Skills Work

Each skill is a structured markdown file (SKILL.md) with YAML frontmatter that defines the skill's name, description, role, and workflow. When an AI agent reads a skill, it adopts the defined persona and follows the prescribed procedures.

Skills are designed to work together in a development workflow:

Product Manager → Architect → Developer → Tester → DevOps Engineer → Technical Writer

The AGENTS.md file in the Integration Starter Kit acts as the master orchestrator, referencing all skills and coordinating handoffs between them.

Installing Skills

Copy the skills and supporting files to your Commerce project:

# From your Commerce project directory
cp -r /path/to/commerce-extensibility-tools/dist/integration-starter-kit/skills/ skills/
cp /path/to/commerce-extensibility-tools/dist/integration-starter-kit/AGENTS.md AGENTS.md

# Optional: copy reference schemas and examples
cp -r /path/to/commerce-extensibility-tools/dist/integration-starter-kit/references/ references/
cp -r /path/to/commerce-extensibility-tools/dist/integration-starter-kit/examples/ examples/

Skills are used automatically by AI assistants that support the AGENTS.md convention (Cursor, Claude Code, GitHub Copilot, etc.). You can also reference individual skills directly by pointing your AI assistant to the relevant SKILL.md file.

📚 Documentation Search (RAG System)

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

Available Documentation Indexes

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

"Teach me about Commerce webhooks"
→ AI uses: search prompt

"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

# Deep search Commerce documentation
/search "How do webhooks work in Adobe Commerce?"

# Provide feedback about your experience
/feedback

Agentic Documentation Search

The search prompt performs iterative, interactive documentation research across Adobe Commerce docs. It searches multiple times with refined queries, fetches linked pages for full content, and presents findings with code examples and doc links. When topics are broad, it asks clarifying questions and lets you choose which areas to explore.

Usage:

/search "How do webhooks work in Adobe Commerce?"
/search "storefront drop-in customization"
/search "event subscriptions and commerce events"

Feedback Collection

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

1. Collect Feedback: The AI will ask you about your experience, any errors encountered, issues faced, or suggestions for improvement
2. Automatic History Collection: The conversation history is automatically collected from the current chat session
3. IMS Authentication: Uses your Adobe IMS token (from aio auth login) for secure upload
4. Local Backup: Chat history is saved locally in a chats/ folder with timestamp-based filenames
5. 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:

1. Open Cursor Settings (Cmd+, or Ctrl+,)
2. Search for "MCP"
3. Verify commerce-extensibility 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

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

Targeting a Non-Production Environment (Maintainers Only)

By default, the documentation search and feedback tools query the production endpoint. The environment is selected from the aio CLI setting cli.env:

To point the tools at the dev/stage RAG, set the CLI environment and re-authenticate:

aio config set cli.env stage
aio auth login --force

To switch back to production:

aio config set cli.env prod
aio auth login --force

⚠️ This repoints your entire aio CLI environment, not just this MCP server. Every other aio command and tool that reads cli.env will now target stage. If you set stage and forget, the docs search will silently query dev; conversely, leaving it unset means you always hit prod even when you expect dev. When a query returns unexpected results, check aio config get cli.env first — a mismatched environment is the most common cause.

Note: Most users should leave cli.env unset and use the default production endpoint.

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:

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 (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
│   │   ├── search.json
│   │   └── handlers/
│   │       ├── feedback.js
│   │       └── search.js
│   └── utils/                  # Utility functions
│
├── dist/                       # Distributable Assets
│   └── integration-starter-kit/
│       ├── AGENTS.md           # Master orchestrator for AI agents
│       ├── skills/             # AI Agent Skills (7 skills)
│       │   ├── product-manager/SKILL.md
│       │   ├── architect/SKILL.md
│       │   ├── developer/SKILL.md
│       │   ├── tester/SKILL.md
│       │   ├── devops-engineer/SKILL.md
│       │   ├── technical-writer/SKILL.md
│       │   └── tutor/SKILL.md
│       ├── references/         # JSON schemas for architecture, requirements, etc.
│       └── examples/           # Example configurations and templates
│
└── 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 2 prompts with custom inputs
• Inspect tool schemas and descriptions
• Monitor server logs and responses
• Debug connectivity issues

Feedback Upload Issues

If feedback upload fails:

1. Authentication: Ensure you've run aio auth login - the feedback service requires IMS authentication
2. Network Connectivity: Ensure you have internet access and the server endpoint is reachable
3. Local Files: Check the chats/ folder in your current directory - chat history is always saved locally even if upload fails
4. Rate Limiting: If you see a 429 error, wait a moment and try again
5. 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

Adobe Commerce App Builder MCP License Terms. See LICENSE for details. Use is subject to the Adobe Enterprise Licensing terms at adobe.com/legal/terms/enterprise-licensing.