Business Sales and Inventory Assistant

Intelligent command-line (CLI) virtual assistant designed to assist with querying and analyzing business information, inventory, and sales for a clothing store. The system uses the Model Context Protocol (MCP) with the FastMCP library and the LangChain framework, integrating local data from an Excel spreadsheet with external resources, such as web search and real-time currency exchange rates.

How It Works

The project is structured into two main parts connected through the Model Context Protocol (MCP):

1. MCP Server (server.py): Centralizes business tools, performing read and aggregation operations on an Excel spreadsheet, as well as queries to external APIs.

2. Client/Agent (agente.py): Initializes the MCP server via subprocess (stdio), exposes the tools to the LLM (gpt-4o-mini from OpenAI), and manages the assistant's reasoning flow.

Communication Flow

Usuário (CLI) <──> main.py
                     │
                     ▼
             agente.py (Agente LangChain / GPT-4o-Mini)
                     │
         (Comunicação via MCP - stdio)
                     │
                     ▼
             server.py (Servidor FastMCP)
        ┌────────────┼────────────┐
        ▼            ▼            ▼
 Planilha Excel    Tavily API   Frankfurter API
(estoque_vendas)  (Busca Web)  (Cotação de Moedas)

Related MCP server: mcp-data-lens

Features

The assistant has access to local and external tools to answer questions in natural language:

Business Tools (Local Data)

• consulta_estoque: Returns the complete list of products and the current calculated stock (Quantity Purchased - Quantity Sold).

• estoque_baixo: Lists products with calculated stock equal to or below 15 units.

• consulta_faturamento: Calculates and returns the total accumulated revenue (Sale Price × Quantity Sold).

• produto_mais_vendido: Identifies and details the product with the highest number of units sold.

• vendas_por_cor: Groups and displays total sales grouped by product color.

• vendas_por_marca: Groups and displays total sales grouped by product brand.

Utility Tools (External APIs)

• pesquisa_web: Performs internet searches via the Tavily API to answer questions about external or up-to-date data.

• consultar_cotacao: Retrieves the real-time exchange rate between two currencies using the Frankfurter API.

Project Structure

Assistente_empresarial_v1/
├── .env.example             # Modelo das variáveis de ambiente necessárias
├── .gitignore               # Arquivos ignorados pelo Git
├── agente.py                # Inicialização do agente e conexão com o cliente MCP
├── estoque_vendas.xlsx      # Planilha de dados (fonte de dados de estoque e vendas)
├── main.py                  # Ponto de entrada da aplicação (loop interativo da CLI)
├── requirements.txt         # Lista de dependências do Python
└── server.py                # Definição das ferramentas e inicialização do servidor FastMCP

Prerequisites

• Python 3.10 or higher

• OpenAI API key (for the LLM model)

• Tavily API key (for internet searches)

Installation and Setup

1. Clone or navigate to the repository

Navigate to the project directory:

cd Assistente_empresarial_v1

2. Create and activate the virtual environment (Recommended)

python -m venv venv

Activation on Windows (PowerShell):

.\venv\Scripts\Activate.ps1

Activation on Linux/macOS:

source venv/bin/activate

3. Install the dependencies

pip install -r requirements.txt

4. Configure the environment variables

Create a .env file in the project root based on .env.example:

copy .env.example .env

Open the .env file and enter your OpenAI and Tavily credentials:

OPENAI_API_KEY=sua_chave_da_openai_aqui
TAVILY_API_KEY=sua_chave_da_tavily_aqui

How to Run

With the virtual environment activated and the variables configured, run the application entry point:

python main.py

The assistant will start the interactive terminal. You will see the input prompt:

Bem_vindo ao Assistente Empresarial
Digite 'sair' caso queira sair

oque temos para hoje: 

Example Questions

You can ask things like:

• "Which products are low in stock?"

• "What was the company's total revenue?"

• "Which brand sold the most?"

• "What is the dollar to real exchange rate today?"

• "Which color sells the most?"