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 -1253
- 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 -744MIT License