Enables secure storage of API keys and environment variables through .env files.
Used for version control and installation of the application.
Integrates with OpenAI's GPT-4 model to power the multi-agent AI system, enabling intelligent customer service for Mercadinho Mercantes.
Referenced as a product example in the store's inventory that customers can inquire about and schedule store visits to see.
Uses Python 3.8+ as the backend language for the MCP server implementation.
Provides a modern, responsive web interface for customer interaction with the AI agents through real-time chat.
Mercadinho Mercantes - Multi-Agent AI Assistant
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
Clone the repository
git clone <repository-url> cd mcp_mercadinhoInstall dependencies
pip install -r requirements.txtSet 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" > .envDatabase 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
Start the MCP server (in one terminal):
python server.py(By default, runs with stdio transport for local development.)
Launch the Streamlit client (in another terminal):
streamlit run chat_multi_agent_client.pyOpen your browser and navigate to the URL shown in the Streamlit output (typically
http://localhost:8501
)
🏗️ Architecture
System Components
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 |
| Retrieve available products | None |
| Get store locations and information | None |
| Get categories with promotions for a store |
|
| Get product promotions for a store |
|
| Get customer information |
|
| Reserve order with discount |
|
| Schedule store visit |
|
📊 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
Store Visit Scheduling
Customer Discount Check
🔧 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 developmentConsider implementing rate limiting for production use
🤝 Contributing
Fork the repository
Create a feature branch (
git checkout -b feature/amazing-feature
)Commit your changes (
git commit -m 'Add amazing feature'
)Push to the branch (
git push origin feature/amazing-feature
)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 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
This server cannot be installed
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.
Related MCP Servers
- -securityFlicense-qualityMCP 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
- -securityAlicense-qualityA Model Context Protocol (MCP) server that provides AI-powered customer support using Cursor AI and Glama.ai integration.Last updated -3MIT License
- -securityFlicense-qualityAn 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 -1246
- AsecurityAlicenseAqualityAn 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 -743MIT License