Spaces:

MCP-1st-Birthday
/

ecomcp

Sleeping

App Files Files Community

ecomcp / docs /HUGGINGFACE_SPACES_SETUP.md

vinhnx90

docs: Remove `docs/` and `../` prefixes from internal links across documentation files.

d12052d 5 months ago

preview code

raw

history blame contribute delete

9.57 kB

A newer version of the Gradio SDK is available: 6.14.0

Upgrade

EcoMCP - HuggingFace Spaces Setup Guide

Deploy EcoMCP as a HuggingFace Space with full MCP integration

Overview

This guide walks you through deploying EcoMCP to HuggingFace Spaces, following the MCP 1st Birthday Hackathon submission requirements.

Setup time: ~10 minutes
Difficulty: Beginner-friendly
Requirements: HuggingFace account, GitHub repo access

Prerequisites

HuggingFace account (free): https://huggingface.co/join
GitHub repository with EcoMCP code
OpenAI API key (for functionality)
Basic git knowledge

Step 1: Create HuggingFace Space

1.1 Navigate to Spaces

Go to https://huggingface.co/spaces
Click "Create new Space"

1.2 Configure Space

Fill in the following:

Field	Value
Space name	`ecomcp` (or your preferred name)
License	MIT
Visibility	Public
SDK	Gradio
Gradio template	Blank

1.3 Create Space

Click "Create Space" and wait for initialization (usually <1 minute).

Step 2: Clone and Push Code

2.1 Clone Your Space Locally

git clone https://huggingface.co/spaces/[your-username]/ecomcp
cd ecomcp

2.2 Add EcoMCP Files

Copy your EcoMCP repository files:

# Copy main files
cp path/to/ecomcp/run_ui.py .
cp path/to/ecomcp/requirements.txt .
cp path/to/ecomcp/README.md .

# Copy source code
cp -r path/to/ecomcp/src ./src
cp -r path/to/ecomcp/docs ./docs

2.3 Ensure Project Structure

Your Space directory should look like:

ecomcp/
 run_ui.py           # Entry point
 requirements.txt    # Dependencies
 README.md          # Space README (hackathon metadata)
 src/
    ui/
    server/
    clients/
    core/
 docs/
    QUICK_START.md
    DEVELOPER_GUIDE.md
    STRUCTURE.md
 .gitignore

2.4 Commit and Push

git add .
git commit -m "Initial EcoMCP Space setup"
git push

Step 3: Configure README.md for Hackathon

Your Space's README.md must include hackathon metadata. Use this template:

---
title: EcoMCP - E-commerce MCP Server
emoji: 
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.26.0
app_file: run_ui.py
pinned: true
tags:
  - building-mcp-track-enterprise
  - ecommerce
  - llm
  - openai
---

# EcoMCP: E-Commerce MCP Server

**Hackathon Submission for MCP 1st Birthday - Track 1: Building MCP**

##  Project Summary

EcoMCP is a production-ready Model Context Protocol (MCP) server designed for e-commerce intelligence and automation. It provides AI-powered tools for product analysis, review sentiment analysis, listing generation, and pricing optimization.

**Key Features:**
-  5 core AI-powered tools
-  OpenAI GPT integration
-  Beautiful Gradio 6 interface
-  Production-ready code

##  Quick Start

### Local Development

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
export OPENAI_API_KEY="your-key-here"
python3 run_ui.py

Visit: http://localhost:7860

Features

1. Analyze Product

Market insights, positioning, competitive advantages

2. Analyze Reviews

Sentiment analysis, extraction of strengths and concerns

3. Generate Listing

Conversion-optimized product copy with multiple styles

4. Price Recommendation

Strategic pricing with discount and bundle recommendations

5. Competitor Analysis

Market positioning and differentiation opportunities

Tool Specifications

Each tool is fully compliant with MCP specification:

{
  "name": "analyze_product",
  "description": "Comprehensive product analysis",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": {"type": "string"},
      "category": {"type": "string"}
    },
    "required": ["name"]
  }
}

Demo Video

[Link to your demo video on YouTube or other platform]

Show the Gradio interface
Demonstrate each tool
Show integration with MCP client

Documentation

Quick Start Guide - Get running in 2 minutes
Developer Guide - Complete architecture
Project Structure - Code organization

Architecture


    Gradio UI (HF Space)  

             
    
      MCP Server      
      (JSON-RPC 2.0)  
    
             
    
      OpenAI API       
      (GPT-4 / GPT-5.1)

Environment Variables

Create a .env file (add to Space secrets):

OPENAI_API_KEY=sk-your-api-key-here

In HuggingFace Spaces:

Go to Settings → Repository secrets
Add key: OPENAI_API_KEY
Value: Your OpenAI API key

Hackathon Compliance

Track 1: Building MCP

Implements MCP 2024-11-05 specification
Fully functional MCP server
JSON-RPC 2.0 protocol
Tool definitions and execution
Production-ready code

Submission Requirements

Published on HuggingFace Space
Track tag: building-mcp-track-enterprise
Working demo (Gradio interface)
Demo video (1-5 minutes)
Documentation in Space README
Social media post link

Prize Alignments

OpenAI API Integration ($1,000)

Real-time GPT-4/5.1 API calls with streaming
Optimized prompts for e-commerce domain
Intelligent fallback mechanisms
Token optimization (max_tokens: 800)

Modal Deployment Support

Optional Modal serverless deployment
Automatic scaling and pay-per-use pricing
HTTP endpoints for direct API calls

LlamaIndex Integration (Future)

Product knowledge base indexing
Vector-based product similarity
Foundation for RAG enhancements

Social Media Post

[Include link to your social media post about this project]

Required platforms:

Twitter/X
LinkedIn
Or other major platform

Post template:

Excited to announce EcoMCP, my submission for the MCP 1st Birthday Hackathon!

 Building an MCP server for e-commerce intelligence
 Analyze products, reviews, pricing, and competitors
 Powered by OpenAI GPT-4/5.1
 Beautiful Gradio interface

Try it here: [Space Link]
#MCP #AI #Ecommerce #Hackathon

Testing the Space

Test 1: Basic Tool Availability

Open the Space
Check that all 5 tools appear in the interface
Verify tool descriptions are visible

Test 2: Product Analysis

Input: "Apple AirPods Pro"
Expected: Detailed analysis with market insights

Test 3: Review Analysis

Input: Sample customer reviews
Expected: Sentiment breakdown and recommendations

Test 4: Listing Generation

Input: Product name and features
Expected: Multiple tone styles of product copy

Test 5: Price Recommendation

Input: Cost, margin target
Expected: Recommended pricing strategy

Configuration

For HuggingFace Spaces

The Space automatically handles:

Python environment setup
Dependency installation from requirements.txt
GPU acceleration (if needed)
Web server configuration

Custom Settings

Modify run_ui.py if needed:

import gradio as gr
from src.ui.app import create_interface

if __name__ == "__main__":
    interface = create_interface()
    interface.launch(
        server_name="0.0.0.0",  # Required for HF Spaces
        server_port=7860,        # Required for HF Spaces
        share=True,             # Optional
        debug=False
    )

Security

API Keys

Never commit API keys to git
Use HuggingFace Repository secrets
Access via os.getenv("OPENAI_API_KEY")

Environment Variables

import os
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
    raise ValueError("OPENAI_API_KEY not set")

Performance

Expected performance on HuggingFace Spaces:

Metric	Expected	Notes
Load time	<5 seconds	Including dependencies
Tool response	2-5 seconds	Includes OpenAI API latency
Concurrent users	10-50+	Depends on hardware
Memory	~200-300MB	Python + Gradio

Troubleshooting

Issue: "No module named 'src'"

Solution: Ensure src/ directory is in the root:

ls -la src/  # Should list __init__.py, ui/, server/, etc.

Issue: OpenAI API errors

Solution: Verify API key in Space secrets:

Go to Settings → Repository secrets
Check OPENAI_API_KEY is set correctly
Test with: echo $OPENAI_API_KEY

Issue: Gradio connection issues

Solution: Ensure run_ui.py uses:

server_name="0.0.0.0"
server_port=7860

Issue: Slow responses

Solution: Check:

OpenAI API rate limits
Network connectivity
Space hardware (may need upgrade)

Support & Resources

MCP Docs: https://modelcontextprotocol.io/
Gradio Docs: https://www.gradio.app/
HF Spaces: https://huggingface.co/docs/hub/spaces
OpenAI API: https://platform.openai.com/docs
Hackathon Discord: [Hackathon Discord Link]

Submission Checklist

Space created and published
Code pushed to HF Space repo
Track tag added to README.md (building-mcp-track-enterprise)
Environment variables configured (OPENAI_API_KEY)
Demo video recorded and linked
Documentation complete
Social media post created and linked
Space tested and working
All 5 tools functional

Final Notes

Your Space is now live and ready for the hackathon!

Next steps:

Record a 1-5 minute demo video
Post on social media
Add video link to this README
Join Discord for live support

Built with for the MCP 1st Birthday Hackathon

Last updated: November 2025