docs/QUICK_REFERENCE.md

EcoMCP Quick Reference

Fast access to key deployment & submission info

---

🚀 Deploy to HuggingFace Spaces (5 mins)

# 1. Create Space at https://huggingface.co/spaces
# 2. Clone it
git clone https://huggingface.co/spaces/[your-username]/ecomcp
cd ecomcp

# 3. Copy files
cp -r /path/to/ecomcp/src .
cp -r /path/to/ecomcp/docs .
cp /path/to/ecomcp/run_ui.py .
cp /path/to/ecomcp/requirements.txt .
cp SPACE_README_TEMPLATE.md README.md

# 4. Edit README.md with your info
nano README.md  # Update title, links, etc.

# 5. Push
git add .
git commit -m "Deploy EcoMCP"
git push origin main

# 6. Add API key secret
# Settings → Repository secrets → Add OPENAI_API_KEY

---

📋 Pre-Submission Checklist

• Space deployed and public
• README.md has correct metadata (emoji, tags, sdk, app_file)
• Track tag added: building-mcp-track-enterprise
• OPENAI_API_KEY secret configured
• All 5 tools working
• Demo video (1-5 mins) recorded and linked
• Social media post created and linked
• No hardcoded API keys in code

---

📖 Documentation Structure

Priority 1 (Essential)
├── docs/DEPLOYMENT_GUIDE.md          → Start here for HF Spaces
├── docs/QUICK_START.md               → 2-minute setup
└── HACKATHON_SUBMISSION_CHECKLIST.md → Pre-submission

Priority 2 (Reference)
├── docs/DEVELOPER_GUIDE.md           → Architecture details
├── docs/STRUCTURE.md                 → Project layout
├── docs/HUGGINGFACE_SPACES_SETUP.md → Detailed HF guide
└── docs/CLAUDE_DESKTOP_SETUP.md      → Desktop integration

Submission Templates
├── SPACE_README_TEMPLATE.md          → Copy to HF Space README
└── README.md                         → Main documentation

---

🎯 The 5 Tools

Tool	Purpose	Input	Output
Analyze Product	Market insights	Product name, category	Analysis with positioning
Analyze Reviews	Sentiment & insights	Customer reviews	Sentiment breakdown, recommendations
Generate Listing	Product copy	Product info	Copy in multiple tones
Price Recommendation	Pricing strategy	Cost, margin	Recommended price, strategy
Competitor Analysis	Market positioning	Product details	Competitive landscape

---

📁 Files You Need

Minimum for HF Space:

ecomcp/
├── run_ui.py           ← Entry point
├── requirements.txt    ← Dependencies
├── README.md           ← Use SPACE_README_TEMPLATE.md
└── src/                ← All your code

For complete submission:

ecomcp/
├── run_ui.py
├── requirements.txt
├── README.md
├── src/
├── docs/               ← All guides
└── tests/              ← Optional

---

🔑 Environment Variables

Required:

OPENAI_API_KEY=sk-your-key-here

Optional (defaults work fine):

OPENAI_MODEL=gpt-4
OPENAI_MAX_TOKENS=800
OPENAI_TEMPERATURE=0.7

---

🧪 Test Locally First

# Setup
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run
export OPENAI_API_KEY="your-key"
python3 run_ui.py

# Visit: http://localhost:7860

---

📝 README.md Frontmatter

Copy this exact YAML for HF Space:

---
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
  - mcp
  - ecommerce
  - openai
---

---

🎬 Demo Video Checklist

• 1-5 minutes long
• Shows all 5 tools
• Shows actual tool outputs
• Clear audio
• Professional presentation
• Uploaded to public platform (YouTube, Loom, etc.)
• Link ready to add to README

---

📱 Social Media Post Template

🚀 Excited to announce EcoMCP! My MCP 1st Birthday Hackathon submission.

Building an MCP server for e-commerce intelligence:
📦 Analyze Products
⭐ Analyze Reviews
✍️ Generate Listings
💰 Price Optimization
🔍 Competitor Analysis

Powered by OpenAI GPT-4/5.1

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

---

🔒 Security Quick Check

• No sk- keys in code
• No .env file committed
• API key only in HF secrets
• No sensitive data in comments
• No test credentials in code

---

⚡ Performance Targets

Metric	Target	Notes
Load time	<5 sec	HF Spaces startup
Tool response	2-5 sec	Includes API latency
Memory	<300MB	Baseline usage
Uptime	99%+	HF Spaces reliability

---

🚨 Common Issues & Fixes

Issue	Fix
"Module not found"	Verify src/ exists with __init__.py
API key error	Check Repository secrets, restart Space
Tool not showing	Refresh browser, clear cache
Slow response	Use GPT-3.5-turbo, reduce tokens
Connection timeout	Check Space logs, upgrade hardware

---

📊 Hackathon Alignment

Track 1: Building MCP ✅

• Implements MCP 2024-11-05 spec
• JSON-RPC 2.0 protocol
• 5 fully functional tools
• Production-ready code

Prize Alignment ✅

• OpenAI API ($1,000) - Full integration
• Modal ($2,500) - Deployment ready
• LlamaIndex ($1,000) - Foundation prepared

---

🔗 Key Links

Resource	URL
Create Space	https://huggingface.co/spaces
OpenAI API Keys	https://platform.openai.com/api-keys
Hackathon Main	https://huggingface.co/spaces/MCP-1st-Birthday
MCP Spec	https://spec.modelcontextprotocol.io/
Gradio Docs	https://www.gradio.app/
HF Spaces Docs	https://huggingface.co/docs/hub/spaces
Discord	https://discord.gg/fveShqytyh

---

📅 Submission Deadline

November 30, 2025 at 11:59 PM UTC

---

✅ Final Checklist

Before you submit:

Space & Code
□ Space created and public
□ Code pushed successfully
□ Space shows "Built successfully"
□ Interface loads in <5 seconds

Configuration
□ OPENAI_API_KEY secret added
□ README.md with correct metadata
□ Track tag: building-mcp-track-enterprise

Functionality
□ All 5 tools working
□ No errors in console
□ Reasonable response times
□ Graceful error handling

Submission Materials
□ Demo video (1-5 mins) - Recorded & Linked
□ Social media post - Created & Linked
□ Documentation - Complete & Clear

Quality Checks
□ No hardcoded secrets
□ Code is clean & readable
□ Error messages are helpful
□ UI is polished & intuitive

Ready to Submit? → YES ✅

---

Last Updated: November 27, 2025

Questions? Check the full guides in /docs or join Discord