MCP QRCode Server 📱

一个功能完整的基于MCP协议的二维码生成和解码服务器，为AI Agent提供强大而灵活的二维码处理功能。

✨ 功能特点

🎯 多种内容类型支持

• URL/网站链接 - 生成网址二维码
• WiFi网络凭证 - 快速分享WiFi连接信息
• 联系信息(vCard) - 分享联系人详情
• 纯文本 - 任意文本内容
• 日历事件(iCal) - 分享日程安排

🎨 多种输出格式

• PNG图片文件 - 保存到指定路径
• Base64编码 - 用于嵌入网页或应用
• 数据URL格式 - 直接在HTML中使用
• ASCII文本 - 终端友好的字符画二维码

⚙️ 自定义选项

• 尺寸调整 - 100-1000像素范围
• 错误纠正级别 - L(低)、M(中)、Q(高)、H(最高)
• 输出格式选择 - 根据需要选择合适的格式

📦 安装与配置

# 安装依赖
npm install

# 构建项目
npm run build

# 在 ~/.cursor/mcp.json 中添加以下配置：
{
  "mcpServers": {
    "mcp-server/qrcode": {
      "command": "node",
      "args": [
        "你的项目路径/typescript/mcp-qrcode/dist/index.js"
      ],
      "autoApprove": [
        "generate_qrcode",
        "generate_wifi_qrcode",
        "generate_vcard_qrcode",
        "decode_qrcode"
      ]
    }
  }
}

🚀 使用示例

1. 生成通用二维码

基本URL二维码（文件输出）

{
  "name": "generate_qrcode",
  "arguments": {
    "content": "https://example.com",
    "contentType": "url",
    "outputFormat": "file",
    "outputPath": "./url_qr.png",
    "size": 300,
    "errorCorrectionLevel": "H"
  }
}

文本二维码（Base64输出）

{
  "name": "generate_qrcode",
  "arguments": {
    "content": "Hello, World! 你好世界！",
    "contentType": "text",
    "outputFormat": "base64",
    "size": 200
  }
}

ASCII文本二维码

{
  "name": "generate_qrcode",
  "arguments": {
    "content": "终端显示的二维码",
    "outputFormat": "text",
    "errorCorrectionLevel": "M"
  }
}

2. 生成WiFi网络二维码

{
  "name": "generate_wifi_qrcode",
  "arguments": {
    "ssid": "MyWiFi-5G",
    "password": "MySecretPassword123",
    "security": "WPA",
    "hidden": false,
    "outputFormat": "file",
    "outputPath": "./wifi_qr.png",
    "size": 250
  }
}

支持的安全类型：

• WPA - WPA/WPA2加密（推荐）
• WEP - WEP加密（不推荐，安全性差）
• nopass - 无密码开放网络

3. 生成联系人二维码

{
  "name": "generate_vcard_qrcode",
  "arguments": {
    "name": "张三",
    "phone": "+86 138-0013-8000",
    "email": "[email protected]",
    "organization": "ABC科技公司",
    "url": "https://zhangsan.example.com",
    "outputFormat": "dataurl",
    "size": 300
  }
}

4. 生成日历事件二维码

{
  "name": "generate_qrcode",
  "arguments": {
    "content": {
      "title": "重要会议",
      "startDate": "20241201T100000Z",
      "endDate": "20241201T120000Z",
      "location": "会议室A",
      "description": "季度业务回顾会议"
    },
    "contentType": "ical",
    "outputFormat": "file",
    "outputPath": "./meeting_qr.png"
  }
}

5. 解码二维码

{
  "name": "decode_qrcode",
  "arguments": {
    "imagePath": "https://example.com/qrcode.png"
  }
}

📋 API参考

generate_qrcode

通用二维码生成工具，支持所有内容类型和输出格式。

参数：

• content (必需) - 要编码的内容
• contentType (可选) - 内容类型：url、wifi、vcard、text、ical，默认为text
• outputFormat (可选) - 输出格式：file、base64、dataurl、text，默认为file
• outputPath (条件必需) - 当outputFormat为file时必需
• size (可选) - 尺寸，100-1000像素，默认为200
• errorCorrectionLevel (可选) - 错误纠正级别：L、M、Q、H，默认为H

generate_wifi_qrcode

专门用于WiFi网络的二维码生成。

参数：

• ssid (必需) - WiFi网络名称
• password (可选) - WiFi密码
• security (可选) - 安全类型：WPA、WEP、nopass，默认为WPA
• hidden (可选) - 是否为隐藏网络，默认为false
• outputFormat (可选) - 输出格式，默认为file
• outputPath (条件必需) - 当outputFormat为file时必需
• size (可选) - 尺寸，默认为200

generate_vcard_qrcode

专门用于联系人信息的二维码生成。

参数：

• name (必需) - 姓名
• phone (可选) - 电话号码
• email (可选) - 邮箱地址
• organization (可选) - 组织/公司
• url (可选) - 网站地址
• outputFormat (可选) - 输出格式，默认为file
• outputPath (条件必需) - 当outputFormat为file时必需
• size (可选) - 尺寸，默认为200

decode_qrcode

解码二维码图片。

参数：

• imagePath (必需) - 二维码图片路径（本地路径或HTTP URL）

🎭 使用场景

商务场景

• 快速分享公司WiFi给访客
• 生成员工联系方式二维码
• 会议邀请和日程分享
• 产品网站推广

个人场景

• 分享个人社交媒体链接
• 家庭WiFi密码分享
• 个人名片二维码
• 活动邀请函

开发场景

• 应用下载链接
• API文档分享
• 测试数据生成
• 调试信息输出

🔧 技术特性

高质量输出

• 支持高密度二维码生成
• 可调节的错误纠正级别
• 清晰的图像输出

安全性

• 输入参数验证
• 安全的文件路径处理
• 网络请求超时控制

兼容性

• 标准vCard 3.0格式
• 标准iCalendar格式
• 通用WiFi配置格式

📝 响应格式

成功响应示例

文件输出

{
  "success": true,
  "contentType": "url",
  "outputFormat": "file",
  "size": 200,
  "errorCorrectionLevel": "H",
  "outputPath": "./example_qr.png",
  "message": "成功生成二维码文件",
  "encodedContent": "https://example.com"
}

Base64输出

{
  "success": true,
  "contentType": "text",
  "outputFormat": "base64",
  "size": 200,
  "base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "message": "成功生成Base64二维码"
}

数据URL输出

{
  "success": true,
  "outputFormat": "dataurl",
  "dataUrl": "data:image/png;base64,iVBORw0KGgo...",
  "message": "成功生成数据URL二维码"
}

ASCII文本输出

{
  "success": true,
  "outputFormat": "text",
  "textQR": "█████████████████████████████████\n█████████████████████████████████\n...",
  "message": "成功生成ASCII文本二维码"
}

🔍 故障排除

常见问题

Q: 生成的二维码无法扫描？ A: 检查内容长度是否过长，尝试提高错误纠正级别或增大二维码尺寸。

Q: WiFi二维码连接失败？ A: 确认SSID和密码正确，检查安全类型设置是否与路由器匹配。

Q: 文件保存失败？ A: 检查输出路径的目录是否存在写权限，确保路径格式正确。

Q: 解码在线图片超时？ A: 检查图片URL是否可访问，网络连接是否正常。

错误代码

• 创建输出目录失败 - 检查文件系统权限
• 生成二维码失败 - 检查输入内容和参数
• 获取图片数据失败 - 检查图片路径或URL
• 解码二维码失败 - 检查图片质量和格式
• 未检测到二维码 - 确认图片中包含有效的二维码

📄 许可证

MIT License - 详见 LICENSE 文件。

🤝 贡献

欢迎提交问题和功能请求！请确保遵循现有的代码风格和测试规范。

让二维码生成变得简单而强大！ 🚀