From 91bbad87f7ad32156bab7e7aa4fabfc5e4dda85f Mon Sep 17 00:00:00 2001
From: Paolo Pangallo <154351366+PaoloPangallo@users.noreply.github.com>
Date: Wed, 14 Oct 2026 12:51:43 +0200
Subject: [PATCH 1/2] Refresh MCP portfolio documentation and add smoke-check
CI
---
.github/workflows/portfolio-ci.yml | 34 ++++
readme.md | 264 ++++++++++++-----------------
2 files changed, 139 insertions(+), 159 deletions(-)
create mode 100644 .github/workflows/portfolio-ci.yml
diff --git a/.github/workflows/portfolio-ci.yml b/.github/workflows/portfolio-ci.yml
new file mode 100644
index 0000000..1b32718
--- /dev/null
+++ b/.github/workflows/portfolio-ci.yml
@@ -0,0 +1,34 @@
+name: Portfolio CI — syntax and frontend build
+
+on:
+ push:
+ branches: [Paolo_minimax2.7, portfolio-refresh-2026-10]
+ pull_request:
+
+jobs:
+ python-syntax:
+ name: Python syntax check
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ with:
+ python-version: '3.11'
+ - name: Compile backend and test sources
+ run: python -m compileall -q app tests
+
+ frontend-build:
+ name: React production build
+ runs-on: ubuntu-latest
+ defaults:
+ run:
+ working-directory: ebay-ui
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: '22'
+ cache: npm
+ cache-dependency-path: ebay-ui/package-lock.json
+ - run: npm ci
+ - run: npm run build
diff --git a/readme.md b/readme.md
index cb086c2..5312c38 100644
--- a/readme.md
+++ b/readme.md
@@ -1,190 +1,136 @@
-# MCP E-Commerce — AI Shopping Assistant
-
-**An end-to-end AI shopping system combining MCP, agentic workflows, retrieval and a full web application**
-
-MCP E-Commerce is a working AI-assisted shopping platform built around eBay. It combines a FastAPI backend, a Model Context Protocol server, an agentic orchestration layer, retrieval and ranking services, persistent storage and a React interface.
-
-Unlike a standalone chatbot demo, the project is designed as a complete software system: the AI agent can access explicit tools, search products, inspect sellers, manage user context and interact with application services through a structured architecture.
-
-## What the system does
-
-A user can express a shopping request in natural language and the system can turn it into a sequence of concrete operations.
-
-Depending on the request, the agent can:
-
-- search for products;
-- retrieve item details;
-- analyse sellers;
-- inspect deals and trends;
-- work with user profiles and preferences;
-- manage wishlists;
-- use browser-backed tools where API access is insufficient;
-- maintain conversational context;
-- stream intermediate and final responses to the frontend.
-
-## Architecture
-
-```text
-React / TypeScript UI
- ↓
-FastAPI application
- ↓
-Agent orchestration
- ┌─────┼──────────────┐
- ↓ ↓ ↓
- MCP Search / RAG User context
-tools pipelines & memory
- ↓ ↓ ↓
-eBay Qdrant Redis / PostgreSQL
+
+
+# 🛍️ MCP E-Commerce
+
+### AI Shopping Assistant · Model Context Protocol · Agentic Workflows
+
+**From natural-language shopping requests to explicit tools, retrieval and a real web application.**
+
+
+
+
+
+
+
+
+
+> **Portfolio project:** A full-stack AI-assisted shopping platform built around eBay, dedicated MCP tools, an agent orchestration layer, semantic retrieval and a React interface. Some functions require external credentials and running infrastructure.
+
+## ✨ At a glance
+
+| 🧠 AI workflows | 🔎 Product discovery | 🧰 Software engineering |
+| --- | --- | --- |
+| Agent planning, explicit MCP tools, conversational memory | eBay search, semantic retrieval, seller/trust analysis, price tracking | FastAPI, PostgreSQL, Redis, Qdrant, React, TypeScript |
+
+### What can a user do?
+
+- Search for products through natural-language requests and structured tool calls.
+- Retrieve item details and inspect seller-related information.
+- Explore deals, comparisons and product recommendations.
+- Manage profiles, preferences and wishlists.
+- Follow conversations with streamed responses in the React UI.
+- Use browser-assisted actions when supported and properly configured.
+
+## 🧩 Architecture
+
+```mermaid
+flowchart TB
+ U["React + TypeScript Shopping experience"] --> API["FastAPI API, Auth & Streaming"]
+ API --> AG["Agent orchestration Planning · Execution · Memory"]
+ AG --> MCP["MCP tools Explicit tool actions"]
+ AG --> R["Retrieval & Ranking RAG · Seller analysis"]
+ AG --> C["User context"]
+ MCP --> EB["eBay API / Browser tools"]
+ R --> Q[("Qdrant")]
+ C --> RD[("Redis")]
+ C --> PG[("PostgreSQL")]
+ style U fill:#e8f8ff,stroke:#2196b3,color:#173449
+ style API fill:#eae4ff,stroke:#7955c4,color:#242040
+ style AG fill:#f4eaff,stroke:#9454bd,color:#282044
+ style MCP fill:#e8fff4,stroke:#2aaf82,color:#214638
+ style R fill:#fff3e4,stroke:#e59c40,color:#513c22
+ style C fill:#f1f5ff,stroke:#6a85b6,color:#28334f
```
-The MCP server is mounted directly inside the FastAPI application at `/mcp`, allowing the application to expose shopping capabilities through explicit tools rather than hiding external actions inside prompts.
-
-## MCP tool layer
-
-The project contains dedicated MCP tools for capabilities including:
-
-- product search;
-- item inspection;
-- seller analysis;
-- deals;
-- market trends;
-- profile information;
-- wishlist operations;
-- seller contact workflows;
-- browser / Playwright-assisted actions;
-- conversation context.
-
-This tool-oriented design keeps external actions explicit and makes the agent easier to inspect and extend.
-
-## Agentic layer
-
-The agent package separates responsibilities into dedicated components for:
-
-- planning;
-- task decomposition;
-- execution;
-- tool registration;
-- memory;
-- prompts and schemas.
-
-This makes the orchestration layer independent from individual integrations and allows new tools or workflows to be introduced without rewriting the entire application.
+The MCP server is mounted in the FastAPI application. Agent planning, execution, tool registration, memory and prompts are organized as separate components. The diagram shows architectural responsibilities, not a promise that every service can run without configuration.
-## Retrieval, ranking and trust
+**Explore the implementation:** [Agent](app/agent/) · [MCP](app/mcp/) · [Services](app/services/) · [Frontend](ebay-ui/) · [Technical diagrams](docs/)
-The shopping pipeline uses several signals instead of relying only on keyword matching.
+## 🛠️ Stack
-The service layer includes components for:
+| Layer | Technologies |
+| --- | --- |
+| Backend | Python, FastAPI, SQLAlchemy, Alembic |
+| AI and tools | MCP, LLM services, Sentence Transformers, RAG, Playwright |
+| Storage and retrieval | PostgreSQL, Redis, Qdrant |
+| Frontend | React 19, TypeScript, Vite, Material UI, Ant Design |
+| Infrastructure | Docker Compose, HTTP integrations, SSE streaming |
-- semantic retrieval;
-- RAG;
-- query parsing;
-- seller analysis;
-- trust scoring;
-- sentiment / NLP processing;
-- comparison and reranking;
-- user profiling;
-- price tracking.
+## 🚀 Run locally
-**Qdrant** is used for vector retrieval, while **Redis** provides caching and short-lived state and **PostgreSQL** stores persistent application data.
+### Requirements
-## Frontend
+- Python environment compatible with the versions in [`requirements.txt`](requirements.txt) (Python 3.11 is a reasonable starting point; verify dependency compatibility on your OS).
+- Node.js and npm for the React frontend.
+- Docker Desktop or Docker Engine with Compose.
+- External API credentials for eBay/LLM features you intend to use.
-The application includes a modern React interface built with:
+### 1. Configure and launch infrastructure
-- React 19
-- TypeScript
-- Vite
-- Material UI
-- Ant Design
-- Zustand
-- Recharts
-- Server-Sent Events / streaming support
-
-The UI is therefore part of the project itself rather than a future integration.
-
-## Backend and infrastructure
-
-- Python
-- FastAPI
-- Model Context Protocol (MCP)
-- PostgreSQL
-- Redis
-- Qdrant
-- SQLAlchemy / Alembic
-- eBay integration
-- Playwright
-- Docker Compose
-- Sentence Transformers
-- NLP / LLM services
-
-Docker Compose provisions the main infrastructure services locally:
-
-```text
-PostgreSQL
-Redis
-Qdrant
+```bash
+cp .env.example .env
+# Edit .env; set real local passwords and required service keys
+docker compose up -d
```
-The application also performs startup checks, model preloading, shared HTTP-client initialization and background price tracking.
-
-## Repository structure
-
-```text
-MCP_E-commerce/
-├── app/
-│ ├── agent/
-│ ├── api/
-│ ├── auth/
-│ ├── config/
-│ ├── db/
-│ ├── llm/
-│ ├── mcp/
-│ ├── models/
-│ ├── services/
-│ └── tools/
-├── ebay-ui/
-├── tests/
-├── alembic/
-└── docker-compose.yaml
-```
+Compose starts PostgreSQL (**localhost:5435**), Redis (**localhost:6379**) and Qdrant (**localhost:6333**). It reads the `.env` file automatically from the project directory.
-## Testing
+### 2. Install and start FastAPI
-The repository contains dedicated test suites for:
+```bash
+python -m venv .venv
+# Linux/macOS: source .venv/bin/activate
+# Windows PowerShell: .\.venv\Scripts\Activate.ps1
+python -m pip install -r requirements.txt
+python -m uvicorn app.main:app --reload --port 8050
+```
-- agent behaviour;
-- API behaviour;
-- MCP functionality.
+On Windows, [`start_dev.ps1`](start_dev.ps1) provides an alternative Docker-and-backend workflow after creating the environment. FastAPI serves on **http://127.0.0.1:8050**.
-## Running locally
+> The backend performs model loading and service initialization at startup, so availability and startup time depend on the configured integrations. This is not a credential-free, one-command demo.
-The application requires the credentials for the external services used by the project, including the configured eBay and LLM integrations.
+### 3. Start React
-Start the infrastructure with:
+In a second terminal:
```bash
-docker compose up -d
+cd ebay-ui
+npm ci
+npm run dev
```
-The repository also includes `start_dev.ps1` for the local Windows development workflow.
+Open the URL printed by Vite (typically **http://localhost:5173**).
-The React frontend can be started separately:
+Stop the infrastructure when done: `docker compose down`. Don't use `docker compose down -v` unless you intend to delete database volumes.
+
+## ✅ Quality checks
+
+The repository includes test modules under [`tests/`](tests/) for agent, API and MCP behavior. Running the complete suite requires the appropriate environment and integrations:
```bash
-cd ebay-ui
-npm install
-npm run dev
+python -m pip install pytest
+python -m pytest tests -q
```
-## Why this project matters
+The [GitHub Actions workflow](.github/workflows/portfolio-ci.yml) performs **Python syntax compilation** and a **React production build**. These are smoke checks, not proof of end-to-end correctness or external API integration.
-This is one of the projects that best represents how I like to work: **AI as part of a real software architecture**.
+## 🔐 Configuration and boundaries
-It brings together agentic AI, MCP, retrieval, backend engineering, databases, caching, external APIs, browser automation and frontend development in one functioning end-to-end application.
+- Use [`.env.example`](.env.example) as a template; never commit personal secrets or real tokens.
+- eBay, LLM and browser features require additional external configuration.
+- Seller trust signals are application heuristics; they should not be interpreted as verified guarantees about sellers.
+- Documentation describes the system's design; production readiness, security and correctness require independent validation.
-## Author
+## 👨💻 Author
-**Paolo Pangallo**
-M.Sc. Computer Engineering — Artificial Intelligence
-University of Calabria
+[**Paolo Pangallo**](https://github.com/PaoloPangallo) · M.Sc. candidate in Computer Engineering — Artificial Intelligence · [LinkedIn](https://www.linkedin.com/in/paolo-pangallo-9aa456170/)
From ba4501422fd38d4768991b3ee268971a3383a0c4 Mon Sep 17 00:00:00 2001
From: Paolo Pangallo <154351366+PaoloPangallo@users.noreply.github.com>
Date: Wed, 14 Oct 2026 12:58:03 +0200
Subject: [PATCH 2/2] Restore missing seller contact card and fix TypeScript
build errors
---
.../src/features/chat/ContactSellerCard.tsx | 89 +++++++++++++++++++
.../search/components/ComparisonDisplay.tsx | 1 -
.../search/components/SearchResultCard.tsx | 1 -
.../search/components/SearchResultList.tsx | 1 -
4 files changed, 89 insertions(+), 3 deletions(-)
create mode 100644 ebay-ui/src/features/chat/ContactSellerCard.tsx
diff --git a/ebay-ui/src/features/chat/ContactSellerCard.tsx b/ebay-ui/src/features/chat/ContactSellerCard.tsx
new file mode 100644
index 0000000..356784a
--- /dev/null
+++ b/ebay-ui/src/features/chat/ContactSellerCard.tsx
@@ -0,0 +1,89 @@
+import { Box, Button, Link, Paper, Typography } from "@mui/material"
+import OpenInNewIcon from "@mui/icons-material/OpenInNew"
+
+interface ContactSellerResult {
+ success?: boolean
+ status?: string
+ contact_status?: string
+ contact_url?: string
+ seller_name?: string
+ message?: string
+ message_sent?: string
+ detail?: string
+ error?: string
+}
+
+// The API contact tool generates a link; the Playwright tool may submit a
+// message. Treat these as different outcomes to avoid false "sent" claims.
+export default function ContactSellerCard({ data }: { data: ContactSellerResult | null }) {
+ if (!data) return null
+
+ const submitted = data.contact_status === "message_sent"
+ const failed = data.status === "error" || data.success === false
+ const title = submitted
+ ? "Messaggio inviato"
+ : failed
+ ? "Contatto venditore non completato"
+ : "Contatta il venditore"
+
+ // Tool output must not become an arbitrary clickable URL in the UI.
+ const safeLink =
+ typeof data.contact_url === "string" &&
+ /^https:\/\/(www\.)?ebay\.it\//i.test(data.contact_url)
+ ? data.contact_url
+ : null
+
+ const description =
+ data.detail ||
+ data.error ||
+ (submitted
+ ? "Il browser ha riportato l'invio del messaggio."
+ : "Apri la messaggistica di eBay per continuare.")
+
+ return (
+
+
+ {title}
+
+ {data.seller_name && (
+
+ Venditore: {data.seller_name}
+
+ )}
+
+ {description}
+
+ {submitted && data.message_sent && (
+
+
+ {data.message_sent}
+
+
+ )}
+ {!submitted && safeLink && (
+ }
+ sx={{ mt: 1.5 }}
+ >
+ Apri messaggistica eBay
+
+ )}
+
+ )
+}
diff --git a/ebay-ui/src/features/search/components/ComparisonDisplay.tsx b/ebay-ui/src/features/search/components/ComparisonDisplay.tsx
index 397784c..58e8283 100644
--- a/ebay-ui/src/features/search/components/ComparisonDisplay.tsx
+++ b/ebay-ui/src/features/search/components/ComparisonDisplay.tsx
@@ -8,7 +8,6 @@ import {
TableHead,
TableRow,
Typography,
- Chip,
Button,
IconButton,
Avatar,
diff --git a/ebay-ui/src/features/search/components/SearchResultCard.tsx b/ebay-ui/src/features/search/components/SearchResultCard.tsx
index e7816dd..29c5c5b 100644
--- a/ebay-ui/src/features/search/components/SearchResultCard.tsx
+++ b/ebay-ui/src/features/search/components/SearchResultCard.tsx
@@ -13,7 +13,6 @@ import { Menu, MenuItem, ListItemIcon, ListItemText, IconButton } from "@mui/mat
import ContactMailIcon from "@mui/icons-material/ContactMail"
import CheckCircleIcon from "@mui/icons-material/CheckCircle"
import RadioButtonUncheckedIcon from "@mui/icons-material/RadioButtonUnchecked"
-import CompareArrowsIcon from "@mui/icons-material/CompareArrows"
import SellerTrustGauge from "../../seller/component/SellerTrustGauge.tsx"
import SellerFeedbackPanel from "../../seller/component/SellerFeedbackPanel.tsx"
diff --git a/ebay-ui/src/features/search/components/SearchResultList.tsx b/ebay-ui/src/features/search/components/SearchResultList.tsx
index 65b8ea4..f1361da 100644
--- a/ebay-ui/src/features/search/components/SearchResultList.tsx
+++ b/ebay-ui/src/features/search/components/SearchResultList.tsx
@@ -1,6 +1,5 @@
import { useState, useMemo, useEffect } from "react"
import { Box, Typography, Button } from "@mui/material"
-import TrendingUpIcon from "@mui/icons-material/TrendingUp"
import GppGoodIcon from "@mui/icons-material/GppGood"
import ListIcon from "@mui/icons-material/List"
import CompareArrowsIcon from "@mui/icons-material/CompareArrows"