Agento - Magento MCP AI Assistant Agent

A powerful AI assistant for Magento 2 that helps you interact with your store's data using natural language queries.

The Full AgentoAI bundle includes the following modules:

1. Agento AI Core
2. Magento MCP server for store owners and developers
3. Magento AI Image and Video Generation Solution

Features

1. Natural Language to SQL

• Convert natural language questions into SQL queries
• Execute SELECT and DESCRIBE queries safely
• No DDL and DML commands are allowed by default however you can change it
• Open chat in new window

2. Token Usage Analytics

• Real-time token usage tracking
• Cost calculation based on model type
• Detailed statistics for:
  • Current message tokens (prompt, completion, total)
  • Session cumulative tokens
  • Cost breakdown per request
  • Total session cost
• Support for different OpenAI models with respective pricing:
  • GPT-3.5 Turbo
  • GPT-4
  • GPT-4 Turbo
  • GPT-4 32k

3. Session Management

• Persistent conversation history
• Session-based context maintenance
• Automatic session cleanup
• Session ID tracking for debugging

4. Security Features

• API key configuration
• Query validation
• Safe SQL execution
• Session-based authentication

5. Error Handling

• Clear error messages
• Automatic error fixing suggestions
• SQL error analysis
• Table structure inspection

6. Architecture

• Decoupled OpenAI service for better maintainability
• Clean separation of concerns
• Extensible design
• Easy to customize and extend

7. CLI AI Agent (genaker:agento:llm)

A dual-mode command-line AI agent for operators and developers.

Chat / Query mode — ask natural language questions answered by the AI using SQL and file tools:

bin/magento genaker:agento:llm "How many customers registered this month?"
bin/magento genaker:agento:llm   # interactive REPL

Analyzer mode — autonomous ReAct agent that investigates the full installation and produces a structured report (security / performance / config / DB):

bin/magento genaker:agento:llm --focus=security
bin/magento genaker:agento:llm --focus=all --report=/tmp/audit.txt

Available tools: get_magento_info, execute_sql_query, describe_table, grep_files, read_file, run_magento_cli, ask_user (bidirectional — AI can ask the operator questions mid-analysis), plus any tools from registered MCP servers (prefixed mcp__{server}__{tool}).

Documentation:

• doc/MAGENTO_AI_QUERY_ANALYZER.md — CLI modes, options, analyzer focus, report format
• doc/TOOLS_AND_LLM.md — How tools work with the LLM: ReAct loop, tool call resolution, conversation flow, all tools in detail
• doc/DATABASE_TOOLS_DOCUMENTATION.md — Tool API reference, custom tools, examples
• doc/ADDING_TOOLS.md — How to add new tools: step-by-step guide with data flow, DI registration, and unit test examples

Tools Overview

| Tool | Purpose | |------|---------| | get_magento_info | Snapshot: version, PHP, modules, DB size, product/order/customer counts | | execute_sql_query | Run SELECT/DESCRIBE/SHOW against Magento DB (auto-limited, safe by default) | | describe_table | Get table structure before querying | | grep_files | Search codebase for patterns (regex) | | read_file | Read file contents with optional line range | | run_magento_cli | Run whitelisted commands: indexer:status, cache:status, module:status, etc. | | ask_user | Ask the operator a question mid-analysis (interactive only) |

The AI uses a ReAct (Reasoning + Acting) loop: it calls tools to gather data, then synthesizes a final answer. See doc/TOOLS_AND_LLM.md for the full flow.

Documentation Index

All technical documentation is in the doc/ folder:

| File | Description | |------|-------------| | MAGENTO_AI_QUERY_ANALYZER.md | CLI command modes, options, analyzer focus areas, report format | | TOOLS_AND_LLM.md | How tools integrate with the LLM: ReAct loop, tool call resolution, conversation flow | | DATABASE_TOOLS_DOCUMENTATION.md | Full tool API reference, custom tool examples | | ADDING_TOOLS.md | Step-by-step guide to adding new tools (interface, DI, tests) | | MCP_INTEGRATION.md | MCP server integration: register any MCP server via di.xml, built-in mock server for testing | | EXTENDING_DATABASE_TOOLS.md | Advanced tool extension patterns | | TEST_SUITE_SUMMARY.md | Unit test suite overview and coverage | | TEST_README.md | How to run the test suite | | LLM_SERVICE_TESTS.md | LLM service integration test details |

8. Customer Service Chatbot

• AI-powered customer-facing chatbot for your storefront
• Dual theme support (Hyva & Standard Magento)
• Response caching for common questions
• Customizable interface and suggested questions
• Mobile responsive design

8. Product Chat with RAG

• AI-powered product assistant in the admin panel
• Retrieval Augmented Generation (RAG) for accurate product information
• Maintains conversation history for context
• Displays formatted content with images and links
• Processes Markdown formatting for better readability
• Stop words removal for optimized token usage
• Token usage tracking and statistics
• Responsive chat interface with modern styling

Installation

1. Install the module using Composer:

composer require genaker/magento-mcp-ai

2. Enable the module:

bin/magento module:enable Genaker_MagentoMcpAi

3. Run setup upgrade:

bin/magento setup:upgrade

4. Clear cache:

bin/magento cache:clean

Configuration

1. API Keys

• Navigate to Stores > Configuration > Genaker > Magento MCP AI
• Enter your OpenAI API key
• Save configuration

2. AI Rules

• Configure custom rules for the AI assistant
• Define query generation behavior
• Set response formatting rules

3. Model Selection & Custom Model Override

• Default Model: Set the default AI model in Stores > Configuration > Genaker > Magento MCP AI > General Configuration > Default AI Model.
• Custom Model (Override): If you set a value in the Custom Model (Override) field, this model will be used for all AI requests, overriding the default model. Leave it blank to use the default model.
• Priority Order:
  1. If Custom Model (Override) is set, it is always used.
  2. If not, the Default AI Model is used.
  3. If both are empty, the fallback is gpt-3.5-turbo.

Example:

• Set Custom Model (Override) to mistral-7b-instruct to use that model for all requests, even if the default is set to gpt-4.
• Leave Custom Model (Override) blank to use the default model selection logic.

4. Documentation

• Add store-specific documentation
• Include table structures
• Document custom attributes

5. Database Connection

• Configure custom database connection in app/etc/env.php:

'db' => [
    'ai_connection' => [
        'host' => 'your_host',
        'dbname' => 'your_database',
        'username' => 'your_username',
        'password' => 'your_password'
    ]
]

• you can add aditional read only connection or with user has read only prevelegy:

Database Configuration

Adding a Read-Only MySQL User

To create a read-only MySQL user for Magento, follow these steps:

1. Connect to MySQL as root:

mysql -u root -p

2. Create a new read-only user (replace username and password with your desired values):

CREATE USER 'username'@'localhost' IDENTIFIED BY 'password';

3. Grant read-only privileges to the Magento database (replace magento_db with your database name):

GRANT SELECT ON magento_db.* TO 'username'@'localhost';

4. For remote access (if needed), create the user with host '%':

CREATE USER 'username'@'%' IDENTIFIED BY 'password';
GRANT SELECT ON magento_db.* TO 'username'@'%';

5. Flush privileges to apply changes:

FLUSH PRIVILEGES;

6. Verify the user's privileges:

SHOW GRANTS FOR 'username'@'localhost';

Using the Read-Only User in env.php

Add the read-only user credentials to your app/etc/env.php file:

'db' => [
    'connection' => [
        'default' => [
            'host' => 'localhost',
            'dbname' => 'magento_db',
            'username' => 'readonly_user',
            'password' => 'your_password',
            'model' => 'mysql4',
            'engine' => 'innodb',
            'initStatements' => 'SET NAMES utf8;',
            'active' => '1'
        ],
        'ai_connection' => [
            'host' => 'localhost',
            'dbname' => 'magento_db',
            'username' => 'readonly_user',
            'password' => 'your_password',
            'model' => 'mysql4',
            'engine' => 'innodb',
            'initStatements' => 'SET NAMES utf8;',
            'active' => '1'
        ]
    ]
]

Security Considerations

1. Always use strong passwords
2. Restrict access to specific IP addresses if possible
3. Regularly audit user privileges
4. Consider using SSL for remote connections
5. Monitor database access logs

Usage

1. Accessing the Assistant

• Navigate to Marketing > AI Assistant > MCP AI Assistant
• Or use the direct URL: /admin/magentomcpai/chat/index

2. Making Queries

• Type your question in natural language
• The assistant will convert it to SQL
• View results in the table below
• Export results to CSV if needed

3. Managing Conversations

• Use the "Clear" button to start a new conversation
• Export chat history using "Save Chat"
• Open chat in new window for better visibility

4. Monitoring Token Usage

• Vie