SafeCart-AI

Track: 01 — AI Growth & Agentic Commerce

Problema: Pronto la gente no comprará chateando con el bot de un comerciante: pedirán a su propio agente de IA que compre por ellos. Los comerciantes necesitan una forma segura de permitir que un agente de IA navegue por su catálogo y gaste dinero en nombre de un cliente. Este proyecto proporciona esa capa de confianza que falta.

Qué hace

SafeCart-AI expone el catálogo de productos de un comerciante a cualquier agente de IA compatible con MCP (como Claude) a través del Model Context Protocol.

El agente puede navegar por los productos y solicitar compras, pero cada compra debe pasar por un motor de políticas antes de que se cree el pedido en modo de prueba de Razorpay.

El motor de políticas aplica:

• Explicabilidad — el agente debe proporcionar un motivo significativo para la compra.

• Gasto limitado — las compras están controladas por límites por transacción y un tope de gasto por sesión.

• Control de acceso — las compras de importe medio se envían para aprobación humana en lugar de ejecutarse automáticamente.

• Registro de auditoría — los intentos de compra se registran con qué se solicitó, por qué se solicitó y qué decidió el sistema.

• Gestión controlada de fallos — las solicitudes no válidas, como productos sin stock, se rechazan con una explicación clara.

Related MCP server: agent-commerce-mcp-server

Arquitectura

AI Agent (Claude, etc.)
        │
        │ MCP tools:
        │ browse_products
        │ get_product_details
        │ request_purchase
        │ get_audit_trail
        ▼
  mcp_server.py
        │
        ▼
    policy.py ──────────────► SQLite audit log
        │                       logs/audit.db
        │
        │ approved requests
        ▼
razorpay_client.py ────────► Razorpay Test-Mode Orders API

dashboard.py (Flask)
        │
        └────────────────────► Human approve/reject UI

Por qué este diseño

La integración de pagos está deliberadamente separada del motor de políticas.

razorpay_client.py solo se llama después de que la capa de políticas apruebe una solicitud de compra. Esto mantiene la lógica de decisión separada de la integración de pagos y hace que la decisión de compra sea explicable y auditable.

El proyecto está diseñado en torno al principio:

La IA puede solicitar una compra, la política decide si está permitida y las compras de mayor riesgo pueden requerir aprobación humana.

Reglas de la política

La demo actual utiliza los siguientes límites:

Estos valores se pueden ajustar en policy.py.

El agente también debe proporcionar un motivo de compra significativo. Las solicitudes con un motivo ausente o muy corto se rechazan.

Estructura del proyecto

agent-commerce-gateway/
│
├── mcp_server.py
├── policy.py
├── razorpay_client.py
├── dashboard.py
├── test_agent.py
├── requirements.txt
├── README.md
├── .env.example
│
├── data/
│   └── products.json
│
├── templates/
│   └── dashboard.html
│
└── logs/
    └── audit.db

Archivos principales

Configuración

1. Crear un entorno virtual

Windows:

python -m venv venv
venv\Scripts\activate

Linux/macOS:

python3 -m venv venv
source venv/bin/activate

2. Instalar las dependencias

pip install -r requirements.txt

3. Configurar el modo de prueba de Razorpay

Crea un archivo .env a partir de .env.example y añade tus credenciales de Razorpay en MODO DE PRUEBA:

RAZORPAY_KEY_ID=your_test_key_id
RAZORPAY_KEY_SECRET=your_test_key_secret

Nunca hagas commit de .env ni de credenciales reales a GitHub.

Ejecutar el proyecto

1. Iniciar el servidor MCP

python mcp_server.py

Esto inicia el servidor al que se conecta un agente de IA compatible con MCP.

2. Conectar un agente de IA

Para Claude Desktop, añade el servidor MCP a tu configuración de Claude Desktop:

{
  "mcpServers": {
    "agent-commerce-gateway": {
      "command": "python",
      "args": [
        "/absolute/path/to/mcp_server.py"
      ]
    }
  }
}

Reemplaza /absolute/path/to/mcp_server.py por la ruta real en tu ordenador.

Reinicia Claude Desktop después de guardar la configuración.

A continuación, puedes pedirle al agente de IA conectado:

Browse this merchant's products.

o:

Buy me the wireless earbuds because I need them for online classes.

3. Iniciar el panel

Abre otra terminal:

python dashboard.py

A continuación, abre:

http://localhost:5001

El panel se utiliza para ver el registro de auditoría y revisar las compras que requieren aprobación humana.

Cómo funciona el flujo de compra

Ejemplo 1 — Compra aprobada automáticamente

Supón que el usuario pide:

Buy me the Wireless Earbuds because I need them for online classes.

La IA envía una solicitud de compra con el producto, la cantidad y el motivo.

Si el total está dentro del límite de aprobación automática:

Purchase Request
       ↓
Policy Check
       ↓
Approved
       ↓
Razorpay Test Order

Ejemplo 2 — Aprobación humana

Supón que el usuario solicita el Mechanical Keyboard con un precio de ₹3,499.

Al estar por encima del límite de aprobación automática pero dentro del rango de revisión humana:

Purchase Request
       ↓
Policy Check
       ↓
Pending Human Approval
       ↓
Dashboard
       ↓
Human Approves / Rejects

Nota sobre el prototipo: La implementación actual registra la aprobación del panel en la base de datos de auditoría. Una implementación de producción debería conectar esa aprobación con el paso posterior de creación del pedido en Razorpay.

Ejemplo 3 — Rechazo controlado

Si un producto solicitado no tiene stock:

Purchase Request
       ↓
Policy Check
       ↓
Out of Stock
       ↓
Rejected
       ↓
Clear Explanation

El sistema no falla silenciosamente ni continúa con el pago.

Herramientas MCP

El servidor MCP expone cuatro herramientas principales:

browse_products()

Devuelve el catálogo de productos actual del comerciante.

get_product_details(product_id)

Devuelve información detallada de un producto específico.

request_purchase(product_id, quantity, reason)

Solicita una compra en nombre del usuario. El motor de políticas evalúa la solicitud antes de que se cree cualquier pedido de Razorpay.

get_audit_trail()

Devuelve los intentos de compra y sus decisiones para la sesión actual.

Registro de auditoría

Cada intento de compra se almacena en SQLite.

El registro de auditoría incluye:

• Marca de tiempo

• ID de sesión

• ID de producto

• Nombre del producto

• Precio

• Cantidad

• Motivo de la compra

• Decisión

• Explicación de la decisión

Esto permite comprender:

¿Qué solicitó la IA? ¿Por qué lo solicitó? ¿Qué decidió el sistema?

Guion de la demo

Para la demostración del proyecto:

1. Conecta el servidor MCP al agente de IA.

2. Pide al agente de IA que navegue por el catálogo del comerciante.

3. Solicita los Wireless Earbuds (p001, ₹1,499) con un motivo claro.

4. Muestra que la compra se aprueba automáticamente y que se crea un pedido de prueba de Razorpay.

5. Solicita el Mechanical Keyboard (p003, ₹3,499).

6. Muestra que requiere aprobación humana a través del panel.

7. Solicita la 4K Webcam (p005).

8. Muestra que la solicitud de producto sin stock se rechaza de forma controlada.

9. Muestra el registro de auditoría completo.

Pruebas

Se incluye un agente de prueba para ejercitar el flujo principal de MCP.

Ejecuta:

python test_agent.py

El script de prueba demuestra:

• Conexión MCP

• Navegación por el catálogo de productos

• Compra de bajo importe

• Compra de importe medio

• Compra de producto sin stock

• Recuperación del registro de auditoría

Qué falló y cómo se resolvió

1. Motivos de compra no válidos

La capa de políticas exige un motivo significativo para cada compra. Las solicitudes con un motivo ausente o muy corto se rechazan en lugar de permitir una compra sin explicación.

2. Productos sin stock

Una solicitud de producto sin stock se gestiona dentro de la capa de políticas y se devuelve como un rechazo claro en lugar de provocar un fallo de la aplicación.

3. Fallo de Razorpay

La creación de pedidos de Razorpay se encapsula por separado de la decisión de la política. Si la creación del pedido de prueba falla después de una aprobación de la política, el servidor MCP captura la excepción y devuelve un resultado payment_error claro en lugar de fallar.

4. Límites de gasto

Los totales de compra se verifican tanto contra los límites por transacción como contra el tope de gasto de la sesión antes de la aprobación.

Limitaciones / Próximos pasos

Este es un prototipo diseñado para el alcance del hackathon/la demo.

• La identidad de sesión está simplificada: la implementación actual usa un ID de sesión por ejecución del servidor. Un sistema de producción debería asociar las solicitudes con identidades autenticadas de agente y de usuario.

• Los umbrales de la política son estáticos: una versión de producción podría ajustar los límites utilizando el historial de confianza del agente, las preferencias del usuario, las puntuaciones de riesgo o las reglas del comerciante.

• Solo pagos en modo de prueba: el proyecto crea pedidos de Razorpay en modo de prueba y no implementa un flujo completo de captura de pagos reales.

• Autenticación del panel: el panel Flask actual está pensado para la demostración y debería usar autenticación y autorización en producción.

• Ejecución de la aprobación humana: el prototipo actual registra una aprobación humana en la base de datos de auditoría; una implementación de producción debería conectar la acción de aprobación con el paso posterior de ejecución del pago/pedido.

• Seguridad del prototipo: el despliegue en producción requeriría una validación, autenticación y autorización más sólidas, una gestión segura de las sesiones y protección contra agentes maliciosos o comprometidos.

Alcance futuro

Las posibles mejoras futuras incluyen:

• Autenticación de agentes y gestión de identidades

• Límites de gasto específicos por usuario

• Puntuación de riesgo dinámica

• Puntuación de confianza/reputación del agente

• Umbrales de política adaptativos

• Webhooks de estado de pago

• Flujo completo de captura de pagos

• Autenticación segura del panel

• Detección de fraude

• Analítica avanzada

• Pruebas automatizadas más completas

🏆 Propuesta en una frase

SafeCart-AI es una pasarela de comercio MCP controlada por políticas que permite a los agentes de IA comprar en nombre de los usuarios, aplicando límites de gasto explicables, aprobación humana para compras arriesgadas y un registro de auditoría completo.

Principio fundamental

AI Agent
   ↓
Request Purchase
   ↓
Policy Engine
   ↓
┌──────────────┬─────────────────┬──────────────┐
│              │                 │
Approved    Human Review       Rejected
│              │                 │
↓              ↓                 ↓
Razorpay    Dashboard         No Payment
Test Order  Approval
│              │
└──────────────┴─────────────────┐
                                 ↓
                           Audit Trail

La IA solicita. La política decide. Los humanos controlan el riesgo. El pago se ejecuta solo tras la autorización.