docs/QUICKSTART.md

EcoMCP - Quick Start Guide

E-commerce MCP Server for the MCP 1st Birthday Hackathon

Track 1: Building MCP | Integrating OpenAI + LlamaIndex + Modal

Installation

1. Clone and Setup

cd ecomcp
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Configure Environment

cp .env.example .env
# Edit .env and add your OpenAI API key:
# OPENAI_API_KEY=sk-...

Or set directly:

export OPENAI_API_KEY="sk-your-key-here"

Running EcoMCP

Option 1: Gradio UI (Recommended for Demo)

python ecomcp_ui.py

Then open http://localhost:7860 in your browser.

Features:

• Product Analysis
• Review Analysis
• Generate Product Listings
• Pricing Recommendations
• Competitive Analysis

Option 2: MCP Server (Direct)

python ecomcp_server.py

The server listens for JSON-RPC messages on stdin and outputs responses on stdout.

Example message:

echo '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' | python ecomcp_server.py

Option 3: Modal Deployment

modal run ecomcp_modal.py::run_mcp_server

Or call individual functions:

modal run ecomcp_modal.py::analyze_product \
  --product_name "Wireless Headphones" \
  --category "electronics"

API Examples

Analyze Product

Input:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "analyze_product",
    "arguments": {
      "name": "Premium Wireless Headphones",
      "category": "electronics",
      "description": "High-end headphones with active noise cancellation",
      "current_price": 299
    }
  },
  "id": 1
}

Output:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "success",
    "product": "Premium Wireless Headphones",
    "analysis": "...[AI analysis]...",
    "timestamp": "2024-01-15T10:30:00"
  }
}

Analyze Reviews

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "analyze_reviews",
    "arguments": {
      "reviews": [
        "Great sound quality!",
        "Battery life is impressive",
        "A bit pricey but worth it"
      ],
      "product_name": "Premium Wireless Headphones"
    }
  },
  "id": 2
}

Generate Listing

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "generate_listing",
    "arguments": {
      "product_name": "Smart Coffee Maker",
      "features": ["WiFi enabled", "Programmable brewing", "Thermal carafe"],
      "target_audience": "Coffee enthusiasts",
      "style": "professional"
    }
  },
  "id": 3
}

Price Recommendation

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "price_recommendation",
    "arguments": {
      "product_name": "T-Shirt",
      "cost": 8.00,
      "category": "fashion",
      "target_margin": 50
    }
  },
  "id": 4
}

Competitor Analysis

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "competitor_analysis",
    "arguments": {
      "product_name": "Eco-friendly Water Bottle",
      "category": "sports",
      "key_competitors": ["Hydro Flask", "S'well", "Nalgene"]
    }
  },
  "id": 5
}

Features

1. Product Analysis

• Identify key value propositions
• Determine target customer segments
• Highlight competitive advantages
• Recommend market opportunities

2. Review Analysis

• Sentiment analysis (positive/negative/mixed)
• Extract top strengths and concerns
• Identify patterns and themes
• Actionable improvement recommendations

3. Listing Generation

• AI-written headlines
• Benefit-focused descriptions
• Persuasive call-to-actions
• Conversion-optimized copy

4. Pricing Strategy

• Cost-based pricing
• Psychological pricing tactics
• Discount strategies
• Bundle recommendations
• Price elasticity analysis

5. Competitive Analysis

• Market positioning opportunities
• Differentiation strategies
• Competitor strengths/weaknesses
• White space identification

Architecture

ecomcp/
 ecomcp_server.py      # MCP server implementation
 ecomcp_ui.py          # Gradio interface
 ecomcp_modal.py       # Modal deployment
 requirements.txt      # Dependencies
 QUICKSTART.md        # This file

Flow Diagram

   Gradio UI     

         
         → JSON-RPC Messages
         

 EcoMCP Server   

 analyze_product 
analyze_reviews  
generate_listing 
price_rec...     
competitor...    

         
         → OpenAI API
         
         → Results

Environment Variables

# Required
OPENAI_API_KEY=sk-...                    # OpenAI API key

# Optional
MODEL=gpt-5-preview                # AI model (default)
LOG_LEVEL=INFO                           # Logging level
GRADIO_PORT=7860                         # Gradio port

Troubleshooting

Server won't start

# Check Python version
python --version  # Should be 3.8+

# Verify dependencies
pip install -r requirements.txt

# Check OpenAI key
echo $OPENAI_API_KEY

Gradio UI slow or unresponsive

# Run in debug mode
python ecomcp_ui.py --debug

# Check server logs
python ecomcp_server.py 2>&1 | tee server.log

OpenAI API errors

• Verify API key is correct: echo $OPENAI_API_KEY
• Check account has credits
• Verify rate limits aren't hit
• Check internet connection

Testing

# Run tests
pytest tests/ -v

# With coverage
pytest tests/ --cov=. --cov-report=html

# Run specific test
pytest tests/test_ecomcp.py::test_analyze_product -v

Deployment

Modal Deployment

1. Install Modal CLI:

   pip install modal
   

2. Authenticate:

   modal token new
   

3. Deploy:

   modal deploy ecomcp_modal.py
   

4. Invoke remotely:

   modal run ecomcp_modal.py::analyze_product \
     --product_name "Your Product"
   

Docker Deployment

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY ecomcp_*.py .
ENV OPENAI_API_KEY=${OPENAI_API_KEY}
CMD ["python", "ecomcp_ui.py"]

docker build -t ecomcp .
docker run -e OPENAI_API_KEY=$OPENAI_API_KEY -p 7860:7860 ecomcp

Support & Resources

• MCP Spec: https://modelcontextprotocol.io/
• OpenAI Docs: https://platform.openai.com/docs
• Gradio Docs: https://www.gradio.app/
• Modal Docs: https://modal.com/docs

License

MIT License - See LICENSE file for details