rawan-77/genai-sales-insights-agent

GenAI Sales Insights Agent + MCP Dataset Preview Server

A two-part GenAI engineering project demonstrating:

1. An LLM-powered insights agent that analyzes financial sales data using Python, Pandas, and OpenAI models, producing fully formatted HTML business reports.
2. A minimal MCP (Model Context Protocol) server implemented in Node.js that exposes the dataset as a callable tool (dataset_preview) for agent-based workflows.

---

Overview

This repository contains:

1. AI Insights Agent (Python)

A pipeline that:

• Loads structured sales data
• Performs quantitative analysis with Pandas
• Builds a summary that captures core metrics
• Sends the summary to an LLM
• Receives structured HTML insights
• Generates a clean, styled report preview

2. MCP Server (Node.js)

A lightweight Model Context Protocol server exposing a single tool: dataset_preview

This tool:

• Reads the same sales CSV from the Python project
• Returns the first 8 lines, formatted as text
• Allows an AI agent to “inspect” enterprise datasets before reasoning over them

---

Architecture Rationale

Enterprises rarely allow LLMs direct filesystem access. Instead, they rely on:

• Tool-based access
• Strict interfaces
• Auditable data flow
• Separation of reasoning and data layers

This project follows that pattern:

Python Agent: Reasoning Layer

Performs analysis, generates summaries, produces HTML insights.

MCP Server: Data Access Layer

Exposes structured, restricted access to the dataset through a tool.

---

Repository Structure

genai-sales-insights-agent/ │ ├── ai_insights_agent/ │ ├── data/ │ │ └── sales_sample.csv │ ├── sales_insights_agent.py │ ├── sales_insights_report.html │ ├── requirements.txt │ └── .env (ignored) │ └── mcp_insights_server/ ├── index.mjs ├── package.json └── package-lock.json

---

AI Insights Agent (Python)

How it works

1. Load Data
   The script loads and parses financial sales data (regions, products, revenue, cost, units_sold).

2. Generate Pandas Summary
   The agent computes:

   • Statistical summaries
   • Profit calculations
   • Revenue/profit grouped by region
   • Revenue/profit grouped by product

3. Send Prompt to LLM
   The summary is passed to an OpenAI model (gpt-4o-mini) with strict instructions to output HTML only.

4. Generate HTML Report
   The returned HTML fragment is inserted into a styled template.
   The final file: sales_insights_report.html

This produces a clean, readable dashboard-like insights page similar to what an internal analytics team might generate.

---

MCP Server (Node.js)

The MCP (Model Context Protocol) allows LLM-based agents to call tools through a standard interface.

This is meant to simulate how internal GenAI agents can safely inspect datasets before using them as context.

This project demonstrates the simplest working version of such a tool.

---

Running the Project

1. Run the Python Insights Agent

pip install -r requirements.txt

Create .env:

OPENAI_API_KEY=your_key_here

Run the script:

python sales_insights_agent.py

Outputs:

• HTML insights printed to console
• sales_insights_report.html generated

Note:

• A sample output file is included in the repo

2. Run the MCP Server

cd mcp_insights_server npm install npm start

Starts a minimal MCP server over STDIO with the dataset_preview tool available.

Author

Rawan Morshed