販売・在庫管理アシスタント

衣料品店の販売情報、在庫、売上データの照会・分析を支援するインテリジェントなコマンドラインインターフェース（CLI）アシスタントです。本システムはModel Context Protocol（MCP）をFastMCPライブラリおよびLangChainフレームワークとともに利用し、Excelスプレッドシートのローカルデータと、ウェブ検索やリアルタイム為替レートなどの外部リソースを統合します。

仕組み

本プロジェクトは、Model Context Protocol（MCP）によって接続される2つの主要コンポーネントで構成されています：

1. MCPサーバー（server.py）：ビジネスツールを一元管理し、Excelスプレッドシートに対する読み取り・集計操作や、外部APIへの問い合わせを実行します。

2. クライアント／エージェント（agente.py）：サブプロセス（stdio）を介してMCPサーバーを起動し、LLM（OpenAIの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：全製品のリストと、計算された現在の在庫数（仕入数量 - 販売数量）を返します。

• estoque_baixo：計算された在庫数が15単位以下の製品をリストアップします。

• consulta_faturamento：累計売上高（販売価格 × 販売数量）を計算して返します。

• produto_mais_vendido：販売数量が最も多い製品を特定し、その詳細を表示します。

• vendas_por_cor：製品の色別に販売数をグループ化して表示します。

• vendas_por_marca：製品のブランド別に販売数をグループ化して表示します。

ユーティリティツール（外部API）

• pesquisa_web：Tavily APIを使用してウェブ検索を実行し、外部データや最新情報に関する質問に回答します。

• consultar_cotacao：Frankfurter APIを使用して、2つの通貨間のリアルタイム為替レートを取得します。

プロジェクト構造

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: 

質問例

次のような質問ができます：

• 「在庫が少ない製品はどれですか？」

• 「会社の総売上高はいくらですか？」

• 「最も売れているブランドはどれですか？」

• 「今日のドルからレアルへの為替レートはいくらですか？」

• 「最も売れている色はどれですか？」