AI导哈

MCP服务器框架

一个全面的模型上下文协议(MCP)服务器样板，用于与Puch AI无缝集成，提供构建自定义MCP工具和服务的基础。

  • by Aki0x137
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 aki0x137/byte-bandits-mcp-server

使用说明

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 <your-repo-url>
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=919876543210

3.运行服务器

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 AI

4.公开服务器（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

  1. 打开 Puch AI
  2. 开始新的对话
  3. 使用connect命令：
    /mcp connect https://your-domain.ngrok.app/mcp your_secret_token_here

🔧 发展

添加新工具

  1. 创建新的工具功能：

    @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"

  2. 添加工具说明：

    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的图像处理

工具类别

  1. 核心工具：验证、回声
  2. Web工具：fetch_web_content
  3. 图像工具：convert_to_bw
  4. 自定义工具：（添加您自己的）

🔒 安全考虑

  • 将敏感令牌存储在环境变量中
  • 在生产环境中使用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列表

🐛 故障排除

常见问题

  1. 导入错误：确保安装了所有依赖项
  2. 身份验证失败：检查AUTH_TOKEN和MY_NUMBER格式
  3. 连接问题：验证HTTPS可访问性
  4. 工具错误：检查刀具参数验证

调试模式

在Puch AI中启用调试日志记录：

/mcp diagnostics-level debug

🤝 贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

📝 许可证

此项目根据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创作！

相关 MCP