Skip to content

CLAUDE.md

Latest commit

 

History

History
74 lines (54 loc) · 2.62 KB

CLAUDE.md

File metadata and controls

74 lines (54 loc) · 2.62 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an AI-powered e-commerce product search agent built with Flask, LangChain, and MCP (Model Context Protocol). The application searches across multiple e-commerce platforms (Amazon, Best Buy, eBay, Walmart, Target, Costco, Newegg) using web scraping capabilities through BrightData's MCP server.

Architecture

  • Backend: Flask web application (app.py) with async MCP client integration
  • AI Agent: LangGraph ReAct agent using OpenAI GPT-4o with structured output
  • MCP Integration: Uses @brightdata/mcp server for web scraping and data extraction
  • Frontend: Jinja2 templates with Bootstrap styling
  • Data Models: Pydantic models for structured product search responses

Key Components

  1. MCP Client: Connects to BrightData's MCP server via stdio for web scraping tools
  2. LangChain Integration: Uses langchain-mcp-adapters to load MCP tools into LangChain
  3. Structured Output: Returns product results in a structured format using Pydantic models
  4. Multi-platform Search: Searches across 7 major e-commerce platforms simultaneously

Development Commands

Setup

# Using uv (recommended)
uv sync

# Install dependencies manually
pip install flask langchain langchain-mcp-adapters langchain-openai langgraph mcp python-dotenv

Running the Application

# Development server
python app.py

# The app runs on http://0.0.0.0:8000 with debug mode enabled

Environment Variables

Required in .env file:

  • OPENAI_API_KEY: OpenAI API key for GPT-4o
  • WEB_UNLOCKER_ZONE: BrightData zone configuration
  • BROWSER_AUTH: BrightData browser authentication
  • API_TOKEN: BrightData API token

MCP Server Requirements

The application requires Node.js and the BrightData MCP server:

npx @brightdata/mcp

The MCP server provides tools for:

  • search_engine: General web search functionality
  • web_data_*: Platform-specific product data extraction tools

Code Structure

  • app.py: Main Flask application with MCP client integration
  • templates/: Jinja2 templates (base.html, index.html)
  • static/: CSS styling
  • pyproject.toml: Python dependencies and project configuration
  • .env: Environment variables (not committed)

Important Notes

  • The app uses async operations for MCP client communication
  • Product search results are structured using Pydantic models
  • The system prompt guides the agent to use appropriate tools for each platform
  • Flask secret key is hardcoded for development (should be changed for production)