How paolopangallo/mcp_e-commerce works
1. Overall shape
This is a full-stack eBay shopping assistant. The backend is a FastAPI service in app/, the frontend is a React/Vite app in ebay-ui/, and the runtime depends on PostgreSQL, Redis, and Qdrant. The architecture is centered on an AI agent that can stream its reasoning and invoke domain tools.
2. Primary request entry points
app/main.py bootstraps the backend and wires the API routers under app/api/. The most important endpoints are the agent streaming API, classic search, and seller analysis. The frontend talks to these endpoints through ebay-ui/src/api/apiClient.ts and the streaming hooks under ebay-ui/src/features/agent/.
3. User-facing interaction flow
The dominant user flow is chat-driven: the React chat page submits a request, the backend returns server-sent event style updates, and the UI renders “thinking” stages, tool output, and domain cards such as item details, metadata, wishlist, trends, and seller trust. The frontend is organized by feature, not by technical layer, which matches the domain-specific response types.
4. Agent orchestration layer
The agent subsystem lives in app/agent/ and is complemented by app/services/agent_executor.py. It follows a ReAct-style pattern: prompts and schemas define the reasoning format, a planner and task decomposer break down the user intent, memory keeps short-term context, and a tool registry exposes callable capabilities. This is the core decision-making boundary of the system.
5. Tool execution boundary
The app/mcp/ package is the execution/tooling layer. It provides an MCP-style server/client split, a Playwright-based browser automation path, and domain tools for search, item lookup, seller lookup, deals, trends, profile, conversation, contact_seller, and wishlist. The agent does not directly embed all business logic; it delegates to these tools through a standardized interface.
6. eBay integration and scraping
eBay-specific behavior is split across app/services/ebay.py, ebay_playwright.py, ebay_metadata.py, ebay_user.py, and scraping helpers such as scraping_brands.py. This layer is responsible for fetching live marketplace data, scraping pages when needed, and normalizing the results into the app’s own domain structures.
7. Search, ranking, and seller intelligence
The main business pipelines are search_pipeline.py, seller_pipeline.py, and compare_pipeline.py. These combine query parsing, candidate retrieval, trust scoring, sentiment, price tracking, and user preference matching. app/services/trust.py, feedback.py, user_profiling.py, and price_tracker.py are the main inputs to ranking and seller evaluation.
8. RAG subsystem
app/services/rag/ is a self-contained retrieval stack. It includes chunking, embeddings, BM25, Qdrant storage, reranking, query expansion, context building, and learning-to-rank features/training. The repo includes a persisted Qdrant store under qdrant_storage/, and there are local FAISS artifacts in app/test/ for offline or test scenarios. This subsystem feeds the agent and search pipeline with semantically retrieved product and feedback context.
9. NLP and LLM services
app/services/nlp_ner.py, nlp_sentiment.py, parser.py, and app/llm/ provide structured understanding of free-form user input and generated explanations. The README indicates spaCy plus Gemini as the main NLP/LLM stack, and app/llm/vision.py suggests multimodal analysis when images are involved. These services sit upstream of search and agent planning.
10. Persistence and caching
PostgreSQL is the primary relational store, with SQLAlchemy models in app/models/ for users, listings, and wishlists, and Alembic migrations in alembic/. Redis is used for transient state and cache-like data through app/db/redis.py and app/config/cache.py. This cleanly separates durable domain data from ephemeral session, feedback, and performance data.
11. Authentication and user settings
Authentication is isolated in app/auth/ with JWT handling, password utilities, config, dependencies, and router integration. User settings and personalization are part of the domain model and are surfaced in both the backend and frontend settings UI. This boundary matters because user identity affects saved wishlists, preferences, and recommendation/trust behavior.
12. Frontend domain composition
The UI is split into feature modules for chat, search, seller, auth, and agent streaming. State is managed in feature-local stores such as chat, wishlist, sidebar, and settings. Components like comparison cards, seller trust gauges, and market trend panels map directly to backend concepts, which makes the UI a projection of the backend’s domain model rather than a generic interface.
13. Testing, scripts, and operational support
The repository contains integration and unit tests for agent streaming, MCP tools, Playwright, Redis, and search behavior under tests/ and app/test/. There are also scripts for dataset analysis, LTR training, embedding checks, and environment sanitization. This indicates the project is operationally oriented around offline evaluation, ranking experiments, and reproducible agent/tool behavior.
14. Deployment/runtime boundaries
docker-compose.yaml and the README imply local multi-service development with FastAPI, Postgres, Redis, and Qdrant running together. The backend can also run its MCP/playwright components separately, which creates a clear split between the API surface, the agent/tool orchestration layer, and the external automation/runtime dependencies.
Main entry points: routes.py API routes · agent_executor.py Agent executor · core.py MCP core · search_pipeline.py Search pipeline
Components 25
Backend
FastAPI application, agent orchestration, domain services, and persistence
- App entry · Starts the backend and mounts the API surface.
app/main.py - API routes · Primary backend routing for search, seller, wishlist, and agent stream.
app/api/routes.py - Agent stream · Streams reasoning steps and tool events to the client.
app/api/agent_stream.py - Auth router · Login and auth-related request handling.
app/auth/auth_router.py - Agent executor · Bridges API requests to agent execution and streaming behavior.
app/services/agent_executor.py - Planner · Breaks user intent into actionable steps for the shopping agent.
app/agent/planner.py - Agent memory · Maintains short-term conversation and execution context.
app/agent/memory.py - Tool registry · Exposes callable tools to the agent in a controlled way.
app/agent/tool_registry.py - MCP core · Standardized tool execution boundary and server/client coordination.
app/mcp/core.py - Playwright server · Browser-backed automation path for page interactions and contact flows.
app/mcp/playwright_server.py - Search pipeline · Query parsing, candidate retrieval, and result ranking for product search.
app/services/search_pipeline.py - Seller pipeline · Builds seller trust, feedback, and profile insights.
app/services/seller_pipeline.py - eBay service · Fetches live marketplace data and normalizes listings and item details.
app/services/ebay.py - RAG store · Retrieval, embeddings, reranking, and Qdrant-backed context assembly.
app/services/rag/qdrant_store.py - NLP + LLM · NER, sentiment, parsing, and multimodal LLM helpers.
app/services/parser.py - User model · Persistent user and preference data.
app/models/user.py - Listing model · Persistent marketplace listing data.
app/models/listing.py - DB layer · Database and cache access used by the backend services.
app/db/database.py
Frontend
React/Vite UI organized by shopping features
- UI shell · Main browser application and theme wiring.
ebay-ui/src/App.tsx - API client · Frontend request layer for backend APIs.
ebay-ui/src/api/apiClient.ts - Stream hook · Consumes streamed agent updates and maps them into UI state.
ebay-ui/src/features/agent/hooks/useAgentStream.ts - Chat page · Primary chat-driven shopping experience and result rendering.
ebay-ui/src/features/chat/ChatPage.tsx - Search view · Search results, comparisons, filters, and deal displays.
ebay-ui/src/features/search/components/SearchResultList.tsx - Seller view · Seller trust, feedback, and summary panels.
ebay-ui/src/features/seller/component/SellerTrustGauge.tsx
Runtime
Local datastores and persisted retrieval artifacts
- Qdrant store · Persisted retrieval collection used by the RAG subsystem.
qdrant_storage/collections/ecommerce_rag/0
Connections 29
- App entry → API routes: mounts · Bootstraps the HTTP API surface.
- App entry → Auth router: includes · Registers authentication endpoints.
- API routes → Agent stream: streams · Exposes the chat/agent SSE endpoint.
- API routes → Search pipeline: search · Serves classic product search requests.
- API routes → Seller pipeline: seller · Serves seller analysis endpoints.
- API routes → Auth router: guards · Applies authentication and user context.
- Agent stream → Agent executor: delegates · Hands off streamed requests to the executor.
- Agent executor → Planner: plans · Decomposes user intent into steps.
- Agent executor → Agent memory: tracks · Reads and updates short-term context.
- Agent executor → Tool registry: uses · Resolves the callable tool surface.
- Tool registry → MCP core: invokes · Routes tool calls through the standardized execution boundary.
- MCP core → Playwright server: automates · Uses browser automation for page-backed operations.
- MCP core → eBay service: fetches · Pulls marketplace data and item details.
- MCP core → RAG store: retrieves · Adds semantic context and ranking evidence.
- Search pipeline → eBay service: queries · Pulls live marketplace data for search.
- Search pipeline → RAG store: enriches · Uses retrieval and ranking context.
- Seller pipeline → eBay service: analyzes · Builds seller intelligence from marketplace data.
- Seller pipeline → RAG store: augments · Uses retrieved feedback and context signals.
- NLP + LLM → Search pipeline: parses intent · Converts free-form requests into structured search input.
- NLP + LLM → Agent executor: supports · Feeds reasoning and explanation generation.
- DB layer → User model: stores · Persists user accounts and preferences.
- DB layer → Listing model: stores · Persists marketplace listing records.
- UI shell → API client: contains · Hosts the API integration layer.
- UI shell → Stream hook: contains · Hosts the streaming chat integration.
- Stream hook → Agent stream: consumes · Consumes backend SSE events.
- Chat page → Stream hook: renders · Displays thinking stages and streamed results.
- Search view → API client: requests · Loads search and comparison data.
- Seller view → API client: requests · Loads seller intelligence data.
- RAG store → Qdrant store: persists · Stores and reads vector retrieval state.