# genaker/agento-ai

> Magento MCP AI Assistant - A powerful AI assistant for Magento 2 that helps with store data queries and management

`composer require genaker/agento-ai`

Canonical URL: https://packagento.com/genaker/agento-ai

## At a glance

- **Vendor**: genaker (https://packagento.com/genaker.md)
- **Latest version**: 18 — released 2026-02-25
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/genaker/agento-ai and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require genaker/agento-ai:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

Magento MCP AI Assistant - A powerful AI assistant for Magento 2 that helps with store data queries and management

## README

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

**Documentation:**
- [MAGENTO_AI_QUERY_ANALYZER.md](MAGENTO_AI_QUERY_ANALYZER.md) — CLI modes, options, analyzer focus, report format
- [TOOLS_AND_LLM.md](TOOLS_AND_LLM.md) — How tools work with the LLM: ReAct loop, tool call resolution, conversation flow, all tools in detail
- [DATABASE_TOOLS_DOCUMENTATION.md](DATABASE_TOOLS_DOCUMENTATION.md) — Tool API reference, custom tools, 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 [TOOLS_AND_LLM.md](TOOLS_AND_LLM.md) for the full flow.

#### 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:
```bash
composer require genaker/magento-mcp-ai
```

2. Enable the module:
```bash
bin/magento module:enable Genaker_MagentoMcpAi
```

3. Run setup upgrade:
```bash
bin/magento setup:upgrade
```

4. Clear cache:
```bash
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

_(README truncated for .md surface. Full README on https://packagento.com/genaker/agento-ai.)_

## Recent Versions

| Version | Released |
|---|---|
| 18 | 2026-02-25 |
| 17 | 2025-12-10 |
| 16 | 2025-10-13 |
| 15 | 2025-08-26 |
| 13 | 2025-08-14 |
| 14 | 2025-08-14 |
| 12 | 2025-08-13 |
| 11 | 2025-08-08 |

## Dependencies

### Require

| Package | Constraint |
|---|---|
| php | >=8.0.0 |

## Quality

Latest release (18) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | 1 | 1 |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Fail | 775 | 44 errors, 731 warnings (ruleset: Magento2) — 323 auto-fixable with phpcbf |
| PHPMD | Warning | 195 | 195 rule violations (MissingImport:55, CyclomaticComplexity:25, NPathComplexity:24, ExcessiveMethodLength:22, UnusedLocalVariable:19) |
| Cpd | Pass | 0 |  |
| Composer validate | Pass | 0 |  |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 129 | 129 | – | – |
| 2.4.8 | – | 129 | 129 | – |
| 2.4.9 | – | – | 132 | 132 |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 22 | 22 | – | – |
| 2.4.8 | – | 23 | 23 | – |
| 2.4.9 | – | – | Error | Error |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Error | Error | – | – |
| 2.4.8 | – | Error | not tested | – |
| 2.4.9 | – | – | Error | Error |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["genaker/agento-ai"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

genaker is a Magento 2 vendor on Packagento. See https://packagento.com/genaker.md for their full catalogue.