판매 및 재고 비즈니스 어시스턴트

의류 매장의 상업 정보, 재고 및 판매에 대한 조회와 분석을 지원하도록 설계된 지능형 명령줄(CLI) 가상 비서입니다. 이 시스템은 FastMCP 라이브러리와 LangChain 프레임워크를 기반으로 MCP(Model Context Protocol)를 사용하여 Excel 스프레드시트의 로컬 데이터를 웹 검색 및 실시간 환율 조회와 같은 외부 리소스와 통합합니다.

작동 방식

이 프로젝트는 MCP(Model Context Protocol)로 연결된 두 가지 주요 부분으로 구성됩니다:

1. MCP 서버(server.py): 비즈니스 도구를 중앙 집중화하여 Excel 스프레드시트에서 읽기 및 집계 작업을 수행하고 외부 API를 쿼리합니다.

2. 클라이언트/에이전트(agente.py): 하위 프로세스(stdio)를 통해 MCP 서버를 초기화하고, 도구를 OpenAI의 LLM(gpt-4o-mini)에 노출하며 어시스턴트의 추론 흐름을 관리합니다.

통신 흐름

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

기능

이 어시스턴트는 자연어 질문에 응답하기 위해 로컬 및 외부 도구에 접근할 수 있습니다:

비즈니스 도구(로컬 데이터)

• consulta_estoque: 전체 제품 목록과 계산된 현재 재고(Quantidade Comprada - Quantidade Vendida)를 반환합니다.

• estoque_baixo: 계산된 재고가 15개 이하인 제품을 나열합니다.

• consulta_faturamento: 누적 총 매출(판매 가격 × 판매 수량)을 계산하여 반환합니다.

• produto_mais_vendido: 가장 많이 판매된 제품을 식별하고 상세 정보를 제공합니다.

• vendas_por_cor: 제품 색상별로 판매 합계를 그룹화하여 표시합니다.

• vendas_por_marca: 제품 브랜드별로 판매 합계를 그룹화하여 표시합니다.

유틸리티 도구(외부 API)

• pesquisa_web: Tavily API를 통해 인터넷 검색을 수행하여 외부 또는 최신 데이터에 대한 질문에 응답합니다.

• consultar_cotacao: Frankfurter API를 사용하여 두 통화 간의 실시간 환율을 얻습니다.

프로젝트 구조

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

사전 요구 사항

• Python 3.10 이상

• OpenAI API 키(LLM 모델용)

• Tavily API 키(인터넷 검색용)

설치 및 구성

1. 저장소 복제 또는 이동

프로젝트 디렉터리로 이동합니다:

cd Assistente_empresarial_v1

2. 가상 환경 생성 및 활성화(권장)

python -m venv venv

Windows(PowerShell)에서 활성화:

.\venv\Scripts\Activate.ps1

Linux/macOS에서 활성화:

source venv/bin/activate

3. 종속성 설치

pip install -r requirements.txt

4. 환경 변수 구성

.env.example을 기반으로 프로젝트 루트에 .env 파일을 생성합니다:

copy .env.example .env

.env 파일을 열고 OpenAI 및 Tavily 자격 증명을 입력합니다:

OPENAI_API_KEY=sua_chave_da_openai_aqui
TAVILY_API_KEY=sua_chave_da_tavily_aqui

실행 방법

가상 환경이 활성화되고 변수가 구성된 상태에서 애플리케이션의 진입점을 실행합니다:

python main.py

어시스턴트가 대화형 터미널을 시작합니다. 입력 프롬프트가 표시됩니다:

Bem_vindo ao Assistente Empresarial
Digite 'sair' caso queira sair

oque temos para hoje: 

질문 예시

다음과 같은 질문을 할 수 있습니다:

• "어떤 제품의 재고가 부족한가요?"

• "회사의 총 매출은 얼마인가요?"

• "가장 많이 판매된 브랜드는 무엇인가요?"

• "오늘 달러-레알 환율은 얼마인가요?"

• "가장 많이 판매되는 색상은 무엇인가요?"