Puch MCP Hackathon

🚀 PuchAI Hackathon

This project offers a suite of tools, including a Reddit research tool and various data visualization tools, along with medicine information retrieval, user preference management, and task management features. It also provides a setup guide to get you up and running quickly.

🚀 Quick Start

🌟 CLICK TO USE THE MCP

✨ Features

Reddit Research Tool

• Description: This tool scrapes the latest new posts from specified subreddits. It filters posts containing specific keywords and then analyzes the content using intent scoring for market validation and audience sentiment analysis.
• Parameters:

  Property	Details
  puch_user_id	User ID for rate limiting (string)
  query	Descriptive query about what you're looking for (string)
  subreddits	List of subreddit names (without 'r/' prefix) (list of strings)
  keywords	Keywords to search for using fuzzy matching (list of strings)
  threshold	Fuzzy match threshold (0 - 100), default: 80 (int)
  post_limit	Number of new posts to check per subreddit (1 - 35), default: 10 (int)

• Cooldown: 80 seconds between uses.
• Example Prompts:
  1. "Hey Puch, I am trying to promote my MCP with Kubernetes EKS setup, please check if recently anyone is interested in r/mcp or r/saas."
  2. "I'm building my own payment gateway service, check if there is any discussion around payment gateways in r/saas, and tell me how to approach them."

Data Visualization Tools

Make Bar Chart

• Description: Generates a labeled bar chart image from lists of labels and numeric data with customizable styling.
• Parameters:

  Property	Details
  puch_labels	Label strings for x - axis (list of strings)
  puch_values	Numeric values (same length as labels) (list of floats)
  width	Image width in pixels, default: 900 (int)
  height	Image height in pixels, default: 450 (int)
  bg_color	Background color, default: "#f8fffe" (string)
  bar_color	Bar color, default: "#4ade80" (string)
  title	Chart title (string, optional)

• Example Prompts:
  1. "Create a bar chart showing sales data: Q1 = 15000, Q2 = 18000, Q3 = 22000, Q4 = 17000 with title 'Quarterly Sales'."
  2. "Make a bar chart of programming languages: Python = 45, JavaScript = 38, Java = 32, C++ = 28, Go = 15."

Make Line Chart

• Description: Creates a line chart visualization showing trends over time or relationships between variables.
• Parameters:

  Property	Details
  puch_labels	Label strings for x - axis (list of strings)
  puch_values	Numeric values (same length as labels) (list of floats)
  width	Image width in pixels, default: 900 (int)
  height	Image height in pixels, default: 450 (int)
  bg_color	Background color, default: "#f8fffe" (string)
  line_color	Line color, default: "#4ade80" (string)
  title	Chart title (string, optional)

• Example Prompts:
  1. "Show me a line chart of website traffic over the past 6 months: Jan = 1200, Feb = 1350, Mar = 1100, Apr = 1600, May = 1850, Jun = 2100."
  2. "Create a line chart showing temperature trends: Mon = 22, Tue = 24, Wed = 19, Thu = 25, Fri = 27, Sat = 23, Sun = 21."

Make Pie Chart

• Description: Generates a pie chart with modern styling, shadow effects, and detailed legend showing percentages and values.
• Parameters:

  Property	Details
  labels	Category labels for the pie chart (list of strings)
  values	Numeric values for each category (list of floats)
  title	Chart title (string, optional)
  width	Image width in pixels, default: 1000 (int)
  height	Image height in pixels, default: 600 (int)

• Example Prompts:
  1. "Create a pie chart showing budget allocation: Marketing = 5000, Development = 8000, Operations = 3000, Sales = 4000."
  2. "Make a pie chart of survey responses: Very Satisfied = 45, Satisfied = 32, Neutral = 15, Dissatisfied = 8."

Make Scatter Plot

• Description: Creates a scatter plot to visualize relationships between two numeric variables with optional categorization and custom styling.
• Parameters:

  Property	Details
  x_values	X - coordinate values (list of floats)
  y_values	Y - coordinate values (same length as x_values) (list of floats)
  labels	Point labels (list of strings, optional)
  categories	Categories for color coding (list of strings, optional)
  colors	Custom colors for each point (hex codes) (list of strings, optional)
  width	Image width in pixels, default: 900 (int)
  height	Image height in pixels, default: 600 (int)
  bg_color	Background color, default: "#fafafa" (string)
  point_color	Default point color, default: "#4F46E5" (string)
  point_size	Point radius in pixels, default: 6 (int)
  title	Chart title (string, optional)
  x_label	X - axis label (string, optional)
  y_label	Y - axis label (string, optional)

• Example Prompts:
  1. "Create a scatter plot showing correlation between hours studied (x) and exam scores (y): study hours [2,4,6,8,10,12] and scores [65,72,78,85,90,95]."
  2. "Make a scatter plot of height vs weight data with categories for different age groups."

Medicine Information Provider

• Description: Retrieves information about any given medicine from Tata 1mg.
• Parameters:

  Property	Details
  medicine_name	Name of the medicine (string)

• Example Prompts:
  1. "Hey, the pharmacy gave me montelukast, is this the right medicine for allergies?"

User Preference Management

Get User Preference

• Description: Retrieves user preferences or a specific preference value by key.
• Parameters:

  Property	Details
  puch_user_id	User ID (string)
  key	Specific preference key to retrieve (string, optional)

• Example Prompts:
  1. "What's my favorite programming language?"
  2. "Show me all my saved preferences."

Save User Preference

• Description: Saves user preferences, likes, interests, or any memorable information to persistent storage.
• Parameters:

  Property	Details
  puch_user_id	User ID (string)
  key	Preference category or key (e.g., 'favorite_color') (string)
  value	Value to save under the given key (string)

• Example Prompts:
  1. "Remember that my favorite programming language is Python."
  2. "Save that I prefer coffee over tea in the mornings."

Task Management Tools

Add Todo

• Description: Adds a new task to the user's TODO list with timestamp.
• Parameters:

  Property	Details
  puch_user_id	User ID (string)
  task	The task or todo item text (string)

• Example Prompts:
  1. "Add 'Finish MCP documentation' to my todo list."
  2. "I need to remember to 'Call client about project proposal' - please add this to my tasks."

List Todos

• Description: Retrieves and displays all TODO items for a user, sorted by creation date.
• Parameters:

  Property	Details
  puch_user_id	User ID (string)

• Example Prompts:
  1. "Show me all my current tasks and todos."
  2. "What's on my todo list right now?"

Delete Todo

• Description: Removes a specific task from the user's TODO list by index number.
• Parameters:

  Property	Details
  puch_user_id	User ID (string)
  index	The index number of the todo from list_todos (1 - based) (int)

• Example Prompts:
  1. "Delete task number 3 from my todo list."
  2. "Remove the second item from my tasks."

⚠️ Important Note

• Reddit Scraper: 80 - second cooldown per user.
• Other tools: No cooldown restrictions.
• User data stored in user_data.json.
• Thread - safe file operations with locking.
• Atomic write operations with temporary files.

📦 Installation

Install uv

Assuming you have Python installed already. uv is a fast Python package installer and environment manager.

pip install uv

📚 Documentation

Run

Git clone the repo, populate the .env file, navigate inside, and execute this:

uv run src/main.py

By default, it will run on port 8085.

Setup NGROK

1. Install ngrok

Download and install ngrok from:
https://ngrok.com/download

2. Get Your Authtoken

1. Go to: https://dashboard.ngrok.com/get-started/your-authtoken.
2. Copy your authtoken.
3. Run the following command to add your token:

   ngrok config add-authtoken YOUR_AUTHTOKEN
   

4. run ngrok http 8085.
5. Copy the URL, and type /mcp connect {copied url}/mcp AUTH_TOKEN. The AUTH_TOKEN should be same as the one in .env file, on puch.ai/hi