Skip to main content
Glama

Mercadinho Mercantes Multi-Agent AI Assistant

Mercadinho Mercantes - Multi-Agent AI Assistant

Python Streamlit MCP OpenAI

A multi-agent AI system for Mercadinho Mercantes, a Brazilian retail chain. This system provides intelligent customer service through specialized AI agents that handle product inquiries, sales assistance, customer management, and store operations.

🏪 About Mercadinho Mercantes

Mercadinho Mercantes is a Brazilian retail company with multiple locations. This AI assistant system enhances customer experience by providing product recommendations, promotional information, and appointment scheduling.

✨ Features

🤖 Multi-Agent Architecture

  • Reception Agent: Welcomes customers and directs them to appropriate services

  • Sales Agent: Handles product inquiries, recommendations, and sales assistance

  • Customer Maintenance Agent: Manages customer accounts and special discounts

🛍️ Core Functionality

  • Product catalog browsing

  • Store information lookup

  • Promotional system (store-specific)

  • Customer management and loyalty benefits

  • Appointment scheduling for store visits and product reservations

  • Special discounts for registered customers

🛠️ Technical Features

  • MCP (Model Context Protocol) integration for tool calling

  • Streamlit UI for interactive chat

  • Real-time chat with AI agents

  • Tool usage visualization

  • Session management

🚀 Quick Start

Prerequisites

  • Python 3.8 or higher

  • OpenAI API key

  • Git

Installation

  1. Clone the repository

    git clone <repository-url> cd mcp_mercadinho
  2. Install dependencies

    pip install -r requirements.txt
  3. Set up environment variables

    export OPENAI_API_KEY="your_openai_api_key_here"

    Or create a .env file:

    echo "OPENAI_API_KEY=your_openai_api_key_here" > .env
  4. Database setup

    • The application requires a pre-existing loja_sistema.db SQLite database with the correct schema. If you do not have this file, please request the schema or a setup script from the project maintainer. (The setup script is not included in this repository.)

Running the Application

  1. Start the MCP server (in one terminal):

    python server.py

    (By default, runs with stdio transport for local development.)

  2. Launch the Streamlit client (in another terminal):

    streamlit run chat_multi_agent_client.py
  3. Open your browser and navigate to the URL shown in the Streamlit output (typically http://localhost:8501)

🏗️ Architecture

System Components

┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Streamlit UI │◄──►│ Multi-Agent │◄──►│ MCP Server │ │ (Frontend) │ │ System │ │ (Backend) │ └─────────────────┘ └──────────────────┘ └─────────────────┘ │ ▼ ┌──────────────────┐ │ OpenAI GPT-4 │ │ (LLM Backend) │ └──────────────────┘

Agent Roles

Reception Agent (RecepcaoAssistente)

  • Purpose: Initial customer contact and routing

  • Responsibilities:

    • Welcome customers to Mercadinho Mercantes

    • Present company information and website

    • Route customers to specialized agents

    • Handle general inquiries

Sales Agent (VendasAssistente)

  • Purpose: Product sales and recommendations

  • Responsibilities:

    • Show available products and inventory

    • Provide product recommendations

    • Handle promotional offers

    • Schedule store visits

    • Process sales inquiries

Customer Maintenance Agent (ManutencaoSocioAssistente)

  • Purpose: Existing customer support and loyalty management

  • Responsibilities:

    • Verify customer membership status

    • Apply special discounts for members

    • Handle product reservations

    • Manage customer accounts

Available Tools (MCP Functions)

Tool

Description

Parameters

get_produtos_disponiveis()

Retrieve available products

None

get_lojas()

Get store locations and information

None

get_categorias_produtos_promocao_por_loja(id_loja)

Get categories with promotions for a store

id_loja: int

get_promocao_por_loja(id_loja)

Get product promotions for a store

id_loja: int

get_info_cliente(cliente_id, nome)

Get customer information

cliente_id: int, nome: str

reservar_pedido_com_desconto(id_loja, id_cliente, data_hora)

Reserve order with discount

id_loja: int, id_cliente: int, data_hora: str

agenda_visita_para_compra(id_loja, data_hora)

Schedule store visit

id_loja: int, data_hora: str

📊 Data Structure (Example)

Products

  • Fields: produto_id, nome, descricao, categoria_id, valor

Stores

  • Fields: loja_id, nome, cidade, estado, bairro

Customers

  • Fields: cliente_id, nome, sobrenome, cliente_socio, cidade, estado, cep, rua, numero, bairro, complemento

🎯 Usage Examples

Product Inquiry

User: "What products do you have available?" Agent: [Shows product catalog with prices and availability]

Store Visit Scheduling

User: "I want to visit a store to see the PlayStation 5" Agent: [Finds nearest store, checks promotions, schedules visit]

Customer Discount Check

User: "My name is John Lennon, do I have any special discounts?" Agent: [Verifies membership, applies special pricing]

🔧 Configuration

Environment Variables

  • OPENAI_API_KEY: Your OpenAI API key for GPT-4 access

Model Settings

  • Model: GPT-4-1106-preview

  • Temperature: 0 (deterministic responses)

  • Tool Choice: Auto

  • Parallel Tool Calls: Disabled

🛡️ Security Considerations

  • API keys should be stored securely in environment variables

  • Never commit API keys to version control

  • Use .env files for local development

  • Consider implementing rate limiting for production use

🤝 Contributing

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

🔮 Future Enhancements

  • Integration with real inventory systems

  • Payment processing capabilities

  • Multi-language support (Portuguese/English)

  • Mobile app development

  • Advanced analytics and reporting

  • Integration with CRM systems


Built with ❤️ for Mercadinho Mercantes

-
security - not tested
F
license - not found
-
quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A sophisticated MCP server that provides intelligent customer service for a Brazilian retail chain through multiple specialized AI agents that handle product inquiries, sales assistance, customer management, and store operations.

  1. 🏪 About Mercadinho Mercantes
    1. ✨ Features
      1. 🤖 Multi-Agent Architecture
      2. 🛍️ Core Functionality
      3. 🛠️ Technical Features
    2. 🚀 Quick Start
      1. Prerequisites
      2. Installation
      3. Running the Application
    3. 🏗️ Architecture
      1. System Components
      2. Agent Roles
      3. Available Tools (MCP Functions)
    4. 📊 Data Structure (Example)
      1. Products
      2. Stores
      3. Customers
    5. 🎯 Usage Examples
      1. Product Inquiry
      2. Store Visit Scheduling
      3. Customer Discount Check
    6. 🔧 Configuration
      1. Environment Variables
      2. Model Settings
    7. 🛡️ Security Considerations
      1. 🤝 Contributing
        1. 📝 License
          1. 🆘 Support
            1. 🔮 Future Enhancements

              Related MCP Servers

              • -
                security
                F
                license
                -
                quality
                MCP server that enables AI assistants to perform SEO automation tasks including keyword research, SERP analysis, and competitor analysis through Google Ads API integration.
                Last updated -
                1
              • -
                security
                F
                license
                -
                quality
                An advanced MCP server that implements sophisticated sequential thinking using a coordinated team of specialized AI agents (Planner, Researcher, Analyzer, Critic, Synthesizer) to deeply analyze problems and provide high-quality, structured reasoning.
                Last updated -
                1
                246
                • Linux
                • Apple
              • A
                security
                A
                license
                A
                quality
                An MCP server that allows AI assistants to utilize human capabilities by sending requests to humans and receiving their responses through a Streamlit UI.
                Last updated -
                7
                43
                MIT License

              View all related MCP servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/lennonconstantino/mcp_mercadinho'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server