Mercadinho Mercantes - Multi-Agent AI Assistant

You set up an MCP-powered multi-agent assistant for Mercadinho Mercantes to handle product inquiries, promotions, scheduling, and loyalty management via an interactive Streamlit UI and a backend MCP server. This server coordinates specialized AI agents to improve customer service and store operations in real time.

How to use

Connect to the MCP server through the interactive UI to start conversations with the Reception, Sales, and Customer Maintenance agents. Use the UI to browse the product catalog, view store locations and promotions, check or apply member discounts, and schedule store visits or product reservations. The system uses the Model Context Protocol to call tools and present real-time results and visualizations of tool usage, so you can see upcoming promotions, available products, and appointment availability as you chat.

How to install

Prerequisites you need before installation are Python 3.8 or higher, an OpenAI API key, and Git.

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, obtain the schema or a setup script from the project maintainer. The setup script is not included in this flow.

5. Run the MCP server

python server.py

(The server runs with stdio transport by default for local development.)

6. Start the Streamlit client

streamlit run chat_multi_agent_client.py

7. Open the application in your browser

http://localhost:8501

## Additional notes

If you need to verify the system is ready, check that the MCP server process is running and reachable by the Streamlit client, and that the OpenAI API key is valid. Ensure the required database exists and the API key has permission to access the GPT-4 backend.

## Configuration

Environment variables and server configuration are used to control access to OpenAI services and the local MCP server. Set OPENAI\_API\_KEY to your API key and keep it secure in environment variables or a .env file for local development.

## Security considerations

Store API keys securely in environment variables and do not commit them to version control. Use a .env file for local development and consider implementing rate limiting and access controls for production use.

## Troubleshooting

Common issues include a missing loja\_sistema.db database, invalid OpenAI API key, or the Streamlit UI failing to connect to the MCP server. Verify the database file, confirm the API key is set, and check logs from server.py and the Streamlit client for errors.

## Notes

This setup uses a local MCP server (stdio transport) and a Streamlit-based client to provide real-time, multi-agent interactions for Mercadinho Mercantes. Tools are invoked via MCP functions to retrieve products, stores, promotions, customer data, and scheduling information.

## Available tools

### get\_produtos\_disponiveis

Retrieve available products from the catalog including names, descriptions, categories, and prices.

### get\_lojas

Fetch store locations and basic information such as city, state, and neighborhood.

### get\_categorias\_produtos\_promocao\_por\_loja

Get product categories that have promotions for a specific store, identified by id\_loja.

### get\_promocao\_por\_loja

Retrieve current promotions available at a specific store, identified by id\_loja.

### get\_info\_cliente

Obtain customer information based on customer ID and name.

### reservar\_pedido\_com\_desconto

Reserve an order with a discount for a given store and customer at a specified date/time.

### agenda\_visita\_para\_compra

Schedule a store visit for a purchase at a specified date/time for a given store.