Byte Bandits MCP服务器
一个全面的模型上下文协议（MCP）服务器样板，旨在与Puch AI无缝集成。该服务器为构建自定义MCP工具和服务提供了坚实的基础。
🚀 特性
核心MCP协议支持
- ✅ 承载令牌身份验证 -基于安全令牌的身份验证
- ✅ HTTPS就绪 -生产就绪的HTTPS支持
- ✅ 验证工具 -Puch AI所需的电话号码验证
- ✅ JSON-RPC 2.0 -完全符合MCP协议
- ✅ 错误处理 -使用适当的MCP错误代码进行全面的错误处理
内置工具
- 🔄 回声工具 -测试服务器连接和基本功能
- 🌐 Web内容提取器 -获取web内容并将其转换为可读的markdown
- 🖼️ 图像处理 -将图像转换为黑白
- 🔧 可扩展框架 -易于扩展的刀具注册系统
发展特征
- 📝 综合文档 -文档化良好的代码和API
- 🧪 测试框架 -内置测试支持
- 🔧 开发工具 -代码格式化、linting和类型检查
- 📦 模块化设计 -清晰地分离关注点
📋 需求
- Python 3.11或更高版本
- 虚拟环境（推荐）
- 配置的环境变量
- 用于Puch AI生产环境的HTTPS部署
🛠️ 快速设置
1.克隆和安装依赖项
# Clone the repository
git clone
cd byte-bandits-mcp-server
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -e .
# For development (optional)
pip install -e ".[dev]"2.配置环境变量
# Copy example environment file
cp .env.example .env
# Edit .env file with your configuration
nano .env所需的环境变量：
# Your secret authentication token (keep this secure!)
AUTH_TOKEN=your_secret_token_here
# Your phone number in format {country_code}{number}
# Example: 919876543210 for +91-9876543210
MY_NUMBER=9198765432103.运行服务器
python main.py您应该看到如下输出：
🚀 Starting Byte Bandits MCP Server...
📱 Phone number: 919876543210
🔐 Authentication: Bearer token configured
✅ Available features: Core MCP Protocol, Echo Tool, Web Content Fetching, Image Processing
🌐 Server running on http://0.0.0.0:8086
📋 Required: Make server publicly accessible via HTTPS for Puch AI4.公开服务器（Puch AI需要）
Puch AI需要HTTPS访问您的服务器。选择以下选项之一：
选项A：使用ngrok（建议用于开发）
# Install ngrok from https://ngrok.com/download
# Get your authtoken from https://dashboard.ngrok.com/get-started/your-authtoken
# Configure ngrok
ngrok config add-authtoken YOUR_AUTHTOKEN
# Start tunnel
ngrok http 8086选项B：部署到云平台
部署到以下服务：
- 铁路
- 渲染
- Heroku
- 数字海洋应用平台
- 维塞尔
- Cloudflare员工
5.连接Puch AI
- 打开 Puch AI
- 开始新的对话
- 使用connect命令：
/mcp connect https://your-domain.ngrok.app/mcp your_secret_token_here🔧 发展
添加新工具
- 创建新的工具功能：
@mcp.tool(description=your_description.model_dump_json())
async def your_tool_name(
parameter: Annotated[str, Field(description="Parameter description")]
) -> str:
# Your tool logic here
return "Tool result"- 添加工具说明：
your_description = ToolDescription(
description="What your tool does",
use_when="When to use this tool",
side_effects="Any side effects (optional)"
)测试
# Run tests
pytest
# Run with coverage
pytest --cov=main
# Type checking
mypy main.py
# Code formatting
black main.py
isort main.py📚 建筑
核心组件
- 认证：带有RSA密钥对生成的承载令牌
- 工具注册表：基于Pydantic的工具描述和验证
- 错误处理：符合MCP的错误代码和消息
- 内容处理：HTML到Markdown转换实用程序
- 图像处理：基于PIL的图像处理
工具类别
- 核心工具：验证、回声
- Web工具：fetch_web_content
- 图像工具：convert_to_bw
- 自定义工具：（添加您自己的）
🔒 安全考虑
- 将敏感令牌存储在环境变量中
- 在生产环境中使用HTTPS
- 验证所有输入
- 实施适当的错误处理
- 遵循最小特权原则
📖 api参考
所需工具
validate()
- 目的：Puch AI要求进行身份验证
- 退货：服务器所有者的电话号码
- 格式:
{country_code}{number}（例如，“919876543210”）
可选工具
echo(message: str)
- 目的：测试服务器连接
- 参数:
message-要回显的文本 - 退货：带前缀的回声消息
fetch_web_content(url: AnyUrl, raw: bool = False)
- 目的：获取和处理web内容
- 参数:
- url -要获取的URL - raw -返回原始内容，不进行降价转换
- 退货：已处理包含元数据的内容
convert_to_bw(image_data: str)
- 目的：将图像转换为黑白
- 参数:
image_data-Base64编码图像数据 - 退货：已转换图像的ImageContent列表
🐛 故障排除
常见问题
- 导入错误：确保安装了所有依赖项
- 身份验证失败：检查AUTH_TOKEN和MY_NUMBER格式
- 连接问题：验证HTTPS可访问性
- 工具错误：检查刀具参数验证
调试模式
在Puch AI中启用调试日志记录：
/mcp diagnostics-level debug🤝 贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 如果适用，添加测试
- 提交拉取请求
📝 许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。
🆘 获取帮助
- Puch AI不和谐: https://discord.gg/VMCnMvYx
- PUCH AI MCP文档: https://puch.ai/mcp
- Puch WhatsApp: +91 99988 81729
- MCP协议文件: https://modelcontextprotocol.io/
______________________________________________________________________
编码愉快！ 🚀
内置于❤️ Byte Bandits团队。
使用标签 #BuildWithPuch 分享您的MCP创作！