MCP Mercadinho

🚀 Mercadinho Mercantes - Multi-Agent AI Assistant

A sophisticated multi - agent AI system designed for Mercadinho Mercantes, a Brazilian retail chain. It offers intelligent customer service via multiple specialized AI agents, handling product inquiries, sales assistance, customer management, and store operations.

🚀 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
   

Running the Application

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

   mcp run server.py --transport sse
   

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)

✨ Features

🤖 Multi - Agent Architecture

• Reception Agent: Greets customers and directs them to relevant services.
• Sales Agent: Handles product inquiries, provides recommendations, and offers sales assistance.
• Customer Maintenance Agent: Manages existing customer accounts and special discounts.

🛍️ Core Functionality

• Product Catalog: Browse available products with pricing and inventory information.
• Store Information: Find store locations and contact details.
• Promotional System: Access store - specific promotions and discounts.
• Customer Management: Track customer profiles and loyalty benefits.
• Appointment Scheduling: Book store visits and product reservations.
• Special Discounts: Exclusive offers for registered customers.

🛠️ Technical Features

• MCP Integration: Model Context Protocol for tool calling.
• Streamlit UI: A modern and responsive web interface.
• Real - time Chat: Interactive conversation with AI agents.
• Tool Visualization: Transparent view of AI tool usage.
• Session Management: Persistent conversation history.

🏪 About Mercadinho Mercantes

Mercadinho Mercantes is a well - known Brazilian retail company with multiple stores across São Paulo and Rio de Janeiro. Our AI assistant system enhances the customer experience by providing personalized product recommendations, promotional information, and seamless appointment scheduling.

🏗️ 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 appropriate 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)

📊 Data Structure

Products

• Categories: Hortifruit, Electronics
• Information: ID, name, category, price, quantity
• Examples: Bananas, Apples, PlayStation 5, LED TV

Stores

• Locations: São Paulo (Parelheiros, Mooca), Guarujá, Santo André, Rio de Janeiro (Ipanema, Nova Iguaçu)
• Information: ID, name, city, state

Customers

• Types: Regular customers, Members (with special discounts)
• Information: ID, name, associated store, discount eligibility

💻 Usage Examples

Basic Usage

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

Advanced Usage

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

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

⚠️ Important Note

API keys should be stored securely in environment variables. Never commit API keys to version control. Use .env files for local development and 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:

• Check the [Issues](https://github.com/your - repo/issues) page.
• Contact the development team.
• Visit Mercadinho Mercantes.

🔮 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