README.md•9.9 kB
# Puch AI - WhatsApp Integration MCP Server 🚀
This repository contains the source code for the **MCP (Multi-Capability Provider) Server**, a powerful backend service designed to bridge **Puch AI** with external services like WhatsApp, web content fetching, and product searching. It acts as a tool hub, allowing the AI to perform complex tasks in the real world.
## Image Result
### Output 1
### Output 2
## ✨ Overview
Puch AI is an intelligent assistant capable of automating tasks and retrieving information. This MCP server extends its capabilities by providing a secure, authenticated API endpoint that Puch AI can call to execute specific "tools."
This server enables Puch AI to:
* 🌐 **Fetch Web Content**: Scrape and process information from any URL on the internet.
* 🛒 **Search for Products**: Perform real-time product searches using Google Shopping to provide users with up-to-date recommendations.
* 📱 **Integrate with WhatsApp**: The server is architected to be the backbone of a full-fledged WhatsApp integration.
-----
## 🏗️ How It Works
The server provides a single, powerful API endpoint that accepts requests to run a specific tool with given arguments. The process flow is as follows:
1. **Puch AI receives a user prompt** (e.g., "Find me a good laptop for under $1000").
2. **Puch AI determines a tool is needed** (e.g., `search_for_products`).
3. **Puch AI sends a POST request** to this MCP server's `/mcp/` endpoint, specifying the `tool_name` and `arguments`.
4. **The MCP Server authenticates the request** using the Bearer Token.
5. **The server executes the requested tool** (e.g., calls the SerpApi for product results).
6. **The server formats and returns the result** to Puch AI in a structured JSON format.
7. **Puch AI uses this information** to formulate a natural language response for the user.
-----
## 🔧 Installation & Setup
Follow these steps to get the MCP server running on your local machine.
### Prerequisites
* **Python 3.11+**
* **pip** (Python package installer)
* **Git**
### Step-by-Step Guide
1. **Clone the Repository**
Open your terminal and clone the repository to your local machine.
```bash
git clone https://github.com/alok-ahirrao/Puch-AI-WhatsApp-Integration-MCP-Server.git
cd Puch-AI-WhatsApp-Integration-MCP-Server
```
2. **Create a Virtual Environment (Recommended)**
It's best practice to create a virtual environment to manage project dependencies.
```bash
# For macOS/Linux
python3 -m venv venv
source venv/bin/activate
# For Windows
python -m venv venv
.\venv\Scripts\activate
```
3. **Install Dependencies**
Install all the required Python packages from the `requirements.txt` file.
```bash
pip install -r requirements.txt
```
4. **Create and Configure the `.env` File**
Create a file named `.env` in the root directory of the project. This file will store your secret keys and configuration variables. Copy the following and replace the placeholder values.
```env
# Get your API key from https://serpapi.com/
SERPAPI_API_KEY=YOUR_SERPAPI_API_KEY
# Your WhatsApp phone number (e.g., 919876543210)
MY_NUMBER=YOUR_PHONE_NUMBER
# A strong, secret token for authenticating API requests
TOKEN=YOUR_SECURE_BEARER_TOKEN
```
5. **Run the Server**
Start the FastAPI server using Uvicorn.
```bash
python main.py
```
The server should now be running at `http://127.0.0.1:8085`.
-----
## MCP Server Setup Instructions
Follow the instructions below to set up your MCP server and complete the application process.
1. **Obtain an application key:**
Use the provided starter code to spin up a local MCP server. After running `/apply <TWITTER/LINKEDIN REPLY URL>`, you will get an application key.
2. **Create an MCP server:**
Now you need to create an MCP server using the starter code given in this gist to submit your resume.
3. **Connect Puch to your MCP server:**
Use this command to connect Puch with your MCP server: `/mcp connect <SERVER URL (should be publicly accesible)>/mcp <AUTH TOKEN>`
4. **Validate the auth token and phone number:**
Puch will run a validation check against your Auth token (application key) and phone number. Validation requires both the key and your phone number, formatted as {country_code}{number} — without the + symbol. Example: 919876543210 for an Indian number.
5. **Create a resume tool:**
Feed your resume to Puch: Create a tool that sends your resume in a format fit for an LLM.
* Resume Tool Requirement: Your server must include a resume tool that:
* Accepts a local file (your resume).
* Converts it to markdown text
* Submits the data to the Puch AI MCP endpoint as a string.
6. **Set up an ngrok server:**
To make your local server publicly accessible, you can use ngrok. Run the following command: `ngrok http 8085`
-----
## 🔑 Authentication
All requests to the `/mcp/` endpoint must be authenticated using a **Bearer Token**. Include the token in the `Authorization` header of your request.
`Authorization: Bearer YOUR_SECURE_BEARER_TOKEN`
Replace `YOUR_SECURE_BEARER_TOKEN` with the value you set for `TOKEN` in your `.env` file. A request with a missing or invalid token will result in a `401 Unauthorized` error.
-----
## 🛠️ Available Tools
The server exposes its capabilities through a set of tools. You can invoke a tool by sending a POST request to the `/mcp/` endpoint.
### `fetch`
Fetches and parses the textual content of a given URL. This is useful for summarizing articles, extracting data, or reading documentation.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- |:---|
| `url` | string | **Yes** | N/A | The full URL of the webpage to fetch. |
| `max_length`| integer | No | 5000 | The maximum number of characters to return. |
| `start_index`| integer | No | 0 | The character index from which to start extracting content. Useful for pagination. |
| `raw` | boolean | No | False | If `true`, returns raw HTML. If `false`, returns cleaned text content. |
**Example Request (`curl`):**
```bash
curl -X POST http://127.0.0.1:8085/mcp/ \
-H "Authorization: Bearer YOUR_SECURE_BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tool_name": "fetch",
"arguments": {
"url": "https://en.wikipedia.org/wiki/Artificial_intelligence",
"max_length": 250
}
}'
```
**Example Response:**
```json
{
"content": "Artificial intelligence (AI) is the intelligence of machines or software, as opposed to the intelligence of living beings, primarily of humans. It is a field of computer science that develops and studies intelligent machines. Such machines may be called AIs."
}
```
### `search_for_products`
Searches Google Shopping for products based on a query, using the SerpApi service.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- |:---|
| `query` | string | **Yes** | N/A | A descriptive search query for the product. |
**Example Request (`curl`):**
```bash
curl -X POST http://127.0.0.1:8085/mcp/ \
-H "Authorization: Bearer YOUR_SECURE_BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tool_name": "search_for_products",
"arguments": {
"query": "wireless noise cancelling headphones"
}
}'
```
**Example Response:**
```json
{
"search_results": [
{
"position": 1,
"title": "Sony WH-1000XM5 Wireless Noise-Canceling Over-the-Ear Headphones",
"price": "$399.99",
"extracted_price": 399.99,
"link": "https://www.bestbuy.com/...",
"source": "Best Buy",
"rating": 4.7,
"reviews": 1250,
"thumbnail": "https://i5.walmartimages.com/..."
},
{
"position": 2,
"title": "Bose QuietComfort 45 headphones",
"price": "$329.00",
"extracted_price": 329,
"link": "https://www.bose.com/...",
"source": "Bose",
"rating": 4.6,
"reviews": 890,
"thumbnail": "https://assets.bose.com/..."
}
]
}
```
-----
## 🗺️ Roadmap & Future Development
This server is designed for expansion. Future plans include:
* **Full Two-Way WhatsApp Integration**: Implement webhook endpoints to receive messages from users on WhatsApp and a mechanism to send replies back through the WhatsApp Business API.
* **Support for More Tools**: Add new tools for capabilities like:
* Sending emails.
* Managing calendar events.
* Interacting with other third-party APIs (e.g., Spotify, Google Maps).
* **Interactive Messages**: Utilize WhatsApp's interactive message components like buttons and lists for a richer user experience.
* **Enhanced Error Handling**: Provide more descriptive error messages to the calling AI.
-----
## 🤝 Contributing
Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
1. **Fork the Project**
2. **Create your Feature Branch** (`git checkout -b feature/AmazingFeature`)
3. **Commit your Changes** (`git commit -m 'Add some AmazingFeature'`)
4. **Push to the Branch** (`git push origin feature/AmazingFeature`)
5. **Open a Pull Request**
Please feel free to open an issue if you find a bug or have a suggestion.
-----
## 📜 License
Copyright © 2025, Alok Ahirrao
Licensed under the **Creative Commons Attribution-NonCommercial 4.0 International License**. You may use or modify this project for personal or educational purposes only. Commercial usage requires explicit permission.
For inquiries, please contact [alokahirrao.ai@gmail.com](mailto:alokahirrao.ai@gmail.com).