feat: Add Shopping Agent MCP Server

Author: yenayuu

mcp/shopping_agent/ARCHITECTURE.md

@@ -1,44 +1,51 @@
 # Shopping Agent MCP Tool
 
-A Model Context Protocol (MCP) server that provides intelligent shopping recommendations using LangChain, LangGraph, OpenAI, and SerpAPI.
+A Model Context Protocol (MCP) server that provides product search capabilities using SerpAPI. The server returns structured product data, and the calling agent provides intelligent reasoning and recommendations.
 
 ## Features
 
-- **AI-Powered Recommendations**: Uses OpenAI's GPT-4 to understand natural language queries and generate personalized product recommendations
-- **Real-time Search**: Leverages SerpAPI to search across multiple retailers for the best products
-- **LangGraph Agent**: Implements a sophisticated multi-step agent workflow with:
-  - Query parsing and understanding
-  - Product search across retailers
-  - Recommendation generation with reasoning
-- **Configurable Results**: Limit recommendations (default 5, max 20) based on your needs
+- **Product Search**: Leverages SerpAPI (Google Shopping) to search across multiple retailers
+- **Structured Data**: Returns rich product info including titles, prices, descriptions, thumbnails, ratings, and reviews
+- **Agent-Driven Analysis**: The MCP server returns raw data; your AI agent analyzes and provides reasoning
+- **Budget Awareness**: Product data includes prices for the agent to consider constraints
+- **Configurable Results**: Limit search results (default 10, max 20) based on your needs
 
 ## Tools
 
 ### 1. `recommend_products`
 
-Recommends products based on a natural language query with budget and preferences.
+Searches for products based on a natural language query and returns structured product data. The calling agent should analyze this data and provide intelligent reasoning.
 
 **Parameters:**
 - `query` (string, required): Natural language product request (e.g., "I want to buy a scarf for 40 dollars")
-- `maxResults` (integer, optional): Maximum number of recommendations (default: 5, max: 20)
+- `maxResults` (integer, optional): Maximum number of results (default: 10, max: 20)
 
 **Returns:**
 ```json
 {
   "query": "I want to buy a scarf for 40 dollars",
-  "recommendations": [
+  "products": [
     {
       "name": "Cashmere Blend Scarf",
       "price": "$35.99",
-      "description": "Soft and warm cashmere blend scarf in multiple colors",
+      "description": "Soft and warm cashmere blend scarf in multiple colors...",
       "url": "https://example.com/product",
-      "reason": "High quality within budget with excellent reviews"
+      "thumbnail": "https://example.com/image.jpg",
+      "source": "Amazon",
+      "rating": 4.5,
+      "reviews": 120
     }
   ],
   "count": 5
 }
 ```
 
+**Features:**
+- Returns rich structured product data including thumbnails and ratings
+- The calling agent should analyze products and provide reasoning
+- Products include names, prices, descriptions, and purchase URLs
+- Only requires `SERPAPI_API_KEY` to function
+
 ### 2. `search_products`
 
 Search for products across retailers (lower-level tool for raw search results).
@@ -56,13 +63,11 @@ Raw search results from SerpAPI.
 
 - Python 3.10 or higher
 - [uv](https://docs.astral.sh/uv/) package manager
-- OpenAI API key
-- SerpAPI key
+- SerpAPI key (required for product search)
 
 ### Installation
 
-1. **Get API Keys:**
-   - OpenAI API key: https://platform.openai.com/api-keys
+1. **Get API Key:**
    - SerpAPI key: https://serpapi.com/manage-api-key
 
 2. **Install Dependencies:**
@@ -74,16 +79,15 @@ uv pip install -e .
 
 ### Configuration
 
-Set the required environment variables:
+Set the required environment variable:
 
 ```bash
-export OPENAI_API_KEY="your-openai-api-key"
 export SERPAPI_API_KEY="your-serpapi-key"
 ```
 
 Optional configuration:
 ```bash
-export HOST="0.0.0.0"                    # Server host (default: 0.0.0.0)
+export HOST="0.0.0.0"                     # Server host (default: 0.0.0.0)
 export PORT="8000"                        # Server port (default: 8000)
 export MCP_TRANSPORT="http"               # Transport type (default: http, Inspector-ready)
 export MCP_JSON_RESPONSE="1"              # Force JSON responses (default: enabled)
@@ -96,12 +100,11 @@ export LOG_LEVEL="INFO"                   # Logging level (default: INFO)
 
 ```bash
 cd mcp/shopping_agent
-export OPENAI_API_KEY="your-key"
-export SERPAPI_API_KEY="your-key"
+export SERPAPI_API_KEY="your-serpapi-key"
 python shopping_agent.py
 ```
 
-The server will start on `http://0.0.0.0:8000` by default.
+The server will start on `http://0.0.0.0:8000` by default and will return structured product data for your agent to analyze.
 
 ### Command-line options
 
@@ -122,7 +125,6 @@ Follow these steps to debug the shopping agent with the official MCP Inspector U
 1. Start the server on its own port using HTTP transport:
    ```bash
    cd mcp/shopping_agent
-   export OPENAI_API_KEY="your-key"
    export SERPAPI_API_KEY="your-key"
    MCP_TRANSPORT=http PORT=8001 python shopping_agent.py
    ```
@@ -148,31 +150,47 @@ docker build -t shopping-agent-mcp .
 
 # Run the container
 docker run -p 8000:8000 \
-  -e OPENAI_API_KEY="your-openai-api-key" \
   -e SERPAPI_API_KEY="your-serpapi-key" \
   shopping-agent-mcp
 ```
 
 ## Architecture
 
-The shopping agent uses LangGraph to implement a multi-step workflow:
+The shopping agent MCP server provides product search data. The calling agent (your AI) provides reasoning and recommendations:
 
 ```
-User Query → Parse Query → Search Products → Generate Recommendations → Return Results
+User Query → [MCP Tool] Search Products → Return Structured Data → [Your Agent] Analyze & Recommend
 ```
 
-### LangGraph Workflow
+### Workflow
+
+1. **MCP Server**: Receives query, searches SerpAPI, returns structured product data (no reasoning)
+2. **Your Agent** (e.g., Claude, GPT-4): Analyzes the product data and provides intelligent reasoning for recommendations
+
+### Suggested Agent System Prompt
 
-1. **Parse Query Node**: Uses OpenAI to extract product type and budget from natural language
-2. **Search Products Node**: Queries SerpAPI for relevant products across retailers
-3. **Generate Recommendations Node**: Uses OpenAI to analyze results and create personalized recommendations
+When using this MCP server, configure your agent with a system prompt like this:
+
+```
+When users ask for product recommendations:
+1. Use the recommend_products tool to search for products
+2. Analyze each product considering:
+   - How well it matches the user's requirements
+   - Whether it fits within their budget
+   - The value proposition (quality vs. price)
+   - Any specific features mentioned in the query
+3. For each product, provide:
+   - A brief explanation of why it's a good match
+   - A recommendation score (1-10)
+   - Any caveats or considerations
+4. Rank products by how well they match the user's needs
+5. Present the top 3-5 recommendations with your reasoning
+```
 
 ### Technologies Used
 
 - **FastMCP**: MCP server framework
-- **LangChain**: LLM application framework
-- **LangGraph**: Agent workflow orchestration
-- **OpenAI GPT-4**: Natural language understanding and generation
+- **LangChain Community**: SerpAPI wrapper for product search
 - **SerpAPI**: Real-time product search across retailers
 
 ## Usage Examples
@@ -183,18 +201,39 @@ User Query → Parse Query → Search Products → Generate Recommendations →
 # Query
 "I want to buy a scarf for 40 dollars"
 
-# Response
+# MCP Server Response (raw product data)
 {
-  "recommendations": [
+  "query": "I want to buy a scarf for 40 dollars",
+  "products": [
     {
       "name": "Winter Wool Scarf",
       "price": "$38.99",
-      "description": "100% merino wool, various colors",
-      "reason": "High quality, within budget, great reviews"
+      "description": "100% merino wool...",
+      "url": "https://example.com/product",
+      "thumbnail": "https://...",
+      "source": "Retailer A"
     },
-    // ... 4 more recommendations
-  ]
+    {
+      "name": "Cashmere Blend Scarf",
+      "price": "$35.99",
+      "description": "Soft cashmere blend...",
+      "url": "https://example.com/product2",
+      "thumbnail": "https://...",
+      "source": "Retailer B"
+    }
+  ],
+  "count": 2
 }
+
+# Your Agent should then analyze these products and provide reasoning:
+# "Here are my top recommendations:
+# 
+# 1. Winter Wool Scarf ($38.99) - Score: 9/10
+#    This is an excellent choice within your $40 budget. The 100% merino wool 
+#    provides superior warmth and quality, making it great value at this price point.
+# 
+# 2. Cashmere Blend Scarf ($35.99) - Score: 8/10
+#    A more affordable option that still offers luxury with its cashmere blend..."
 ```
 
 ### Example 2: Specific Requirements
@@ -203,20 +242,54 @@ User Query → Parse Query → Search Products → Generate Recommendations →
 # Query
 "Find me wireless headphones under $100 with good noise cancellation"
 
-# Response includes 5 curated recommendations with:
-# - Product names
-# - Prices
-# - Detailed descriptions
-# - Reasons for recommendation
-# - Purchase links
+# MCP Server Response (raw product data)
+{
+  "query": "wireless headphones under $100 with good noise cancellation",
+  "products": [
+    {
+      "name": "Sony WH-CH710N Wireless Headphones",
+      "price": "$89.99",
+      "description": "Active noise canceling...",
+      "url": "https://example.com/sony-headphones",
+      "rating": 4.4,
+      "reviews": 8500
+    }
+  ],
+  "count": 1
+}
+
+# Your Agent analyzes and recommends:
+# "I found the Sony WH-CH710N Wireless Headphones at $89.99 - this is an excellent 
+# match for your requirements:
+# - ✅ Wireless Bluetooth connectivity
+# - ✅ Active noise cancellation feature
+# - ✅ Well under your $100 budget ($89.99)
+# - ✅ Bonus: 35-hour battery life
+# 
+# Recommendation Score: 9/10
+# This product checks all your boxes and comes from Sony, a trusted brand in audio..."
 ```
 
 ## Testing
 
-You can test the MCP server tools using curl:
+### Using Python Test Script
+
+Test the shopping agent MCP server:
 
 ```bash
-# Test recommend_products tool
+cd mcp/shopping_agent
+export SERPAPI_API_KEY="your-serpapi-key"
+python simple_test.py
+```
+
+This will test the product search functionality and show the structured data returned by the server.
+
+### Using curl
+
+You can also test the MCP server tools using curl:
+
+```bash
+# Test recommend_products tool (returns structured product data)
 curl -X POST http://localhost:8000/mcp/tools/recommend_products \
   -H "Content-Type: application/json" \
   -H "Accept: application/json, text/event-stream" \
@@ -230,9 +303,15 @@ curl -X POST http://localhost:8000/mcp/tools/recommend_products \
 
 ### API Key Issues
 
-If you see "API key not configured" errors:
-1. Verify your API keys are set correctly
-2. Check that environment variables are exported in the same shell session
+**SerpAPI Key Issues:**
+If you see "SERPAPI_API_KEY not configured" errors:
+1. Get your key from https://serpapi.com/manage-api-key
+2. Export it: `export SERPAPI_API_KEY="your-key"`
+3. Restart the server
+
+**General API Key Tips:**
+1. Verify your API key is set correctly
+2. Check that the environment variable is exported in the same shell session
 3. Restart the server after setting environment variables
 
 ### No Results Returned
@@ -255,11 +334,12 @@ If you encounter import errors:
 
 ```
 shopping_agent/
-├── shopping_agent.py    # Main MCP server with LangGraph agent
-├── pyproject.toml       # Dependencies and project metadata
-├── README.md            # This file
-├── Dockerfile           # Container configuration
-└── __init__.py          # Package initialization
+├── shopping_agent.py       # Main MCP server with SerpAPI integration
+├── simple_test.py          # Test script for product search
+├── pyproject.toml          # Dependencies and project metadata
+├── README.md               # This file
+├── Dockerfile              # Container configuration
+└── __init__.py             # Package initialization
 ```
 
 ### Contributing