这是一个创建你自己的模型上下文协议（MCP）服务器的起始模板，该服务器可配合Puch AI。它配备了现成的求职和图像处理工具。

什么是MCP？

MCP（模型上下文协议）允许像Puch这样的AI助手安全地连接外部工具和数据源。可以把它想象成在不牺牲安全性的情况下赋予你的AI额外的超能力。

这个开胃菜里包含了什么？

文件夹

• mcp-bearer-token/ 示例MCP服务器使用持有令牌认证（Puch AI要求）。包括：

• mcp_starter.py 一个最小的MCP服务器，具备：

• 文本输入/输出工具（Echo 风格处理）

• 图像输入/输出工具（例如，转换为黑白）

• 持有人令牌验证

• puch-user-id-mcp-example.py 一个任务管理MCP服务器，演示如何使用puch_user_id（Puch提供的独特用户标识符）来为每个用户范围分配任务和数据。

• mcp-google-oauth/ 示例MCP服务器展示了如何与Google实现OAuth进行MCP认证/授权。

• mcp-oauth-github/ 示例MCP服务器展示了如何用GitHub实现OAuth进行MCP认证/授权。

MCP Starter for Puch AI

This is a starter template for creating your own Model Context Protocol (MCP) server that works with Puch AI. It comes with ready-to-use tools for job searching and image processing.

What is MCP?

MCP (Model Context Protocol) allows AI assistants like Puch to connect to external tools and data sources safely. Think of it like giving your AI extra superpowers without compromising security.

What’s Included in This Starter?

Folders

• mcp-bearer-token/
  Example MCP servers using Bearer token auth (required by Puch AI). Includes:

  • mcp_starter.py
    A minimal MCP server with:
    • Text input/output tool (echo-style processing)
    • Image input/output tool (e.g., convert to black & white)
    • Bearer token validation
  • puch-user-id-mcp-example.py
    A task management MCP server that demonstrates how to use puch_user_id (a unique, Puch-provided user identifier) to scope tasks and data per user.

• mcp-google-oauth/
  Example MCP server showing how to implement OAuth with Google for MCP authentication/authorization.

• mcp-oauth-github/
  Example MCP server showing how to implement OAuth with GitHub for MCP authentication/authorization.

Quick Setup Guide

Step 1: Install Dependencies

First, make sure you have Python 3.11 or higher installed. Then:

# Create virtual environment
uv venv

# Install all required packages
uv sync

# Activate the environment
source .venv/bin/activate

Step 2: Set Up Environment Variables

Create a .env file in the project root:

# Copy the example file
cp .env.example .env

Then edit .env and add your details:

AUTH_TOKEN=your_secret_token_here
MY_NUMBER=919876543210

Important Notes:

• AUTH_TOKEN: This is your secret token for authentication. Keep it safe!
• MY_NUMBER: Your WhatsApp number in format {country_code}{number} (e.g., 919876543210 for +91-9876543210)

Step 3: Run the Server

cd mcp-bearer-token
python mcp_starter.py

You’ll see: 🚀 Starting MCP server on http://0.0.0.0:8086

Step 4: Make It Public (Required by Puch)

Since Puch needs to access your server over HTTPS, you need to expose your local server:

Option A: Using ngrok (Recommended)

1. Install ngrok: Download from https://ngrok.com/download

2. Get your authtoken:

   • Go to https://dashboard.ngrok.com/get-started/your-authtoken
   • Copy your authtoken
   • Run: ngrok config add-authtoken YOUR_AUTHTOKEN

3. Start the tunnel:

   ngrok http 8086
   

Option B: Deploy to Cloud

You can also deploy this to services like:

• Railway
• Render
• Heroku
• DigitalOcean App Platform

How to Connect with Puch AI

1. Open Puch AI in your browser