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/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 && ( + + )} + + ) +} 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" 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.** + +![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white) +![FastAPI](https://img.shields.io/badge/FastAPI-009688?style=for-the-badge&logo=fastapi&logoColor=white) +![MCP](https://img.shields.io/badge/MCP-Agent_Tools-8057DC?style=for-the-badge) +![React](https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB) +![PostgreSQL](https://img.shields.io/badge/PostgreSQL-4169E1?style=for-the-badge&logo=postgresql&logoColor=white) + +
+ +> **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/)