npm package: @mcpcn/mcp-qrcode
Description: QR Code generation and decoding MCP server
Latest version: 1.0.6

# MCP QRCode Server 📱

一个功能完整的基于MCP协议的二维码生成和解码服务器，为AI Agent提供强大而灵活的二维码处理功能。

## ✨ 功能特点

### 🎯 多种内容类型支持
- **URL/网站链接** - 生成网址二维码
- **WiFi网络凭证** - 快速分享WiFi连接信息
- **联系信息(vCard)** - 分享联系人详情
- **纯文本** - 任意文本内容
- **日历事件(iCal)** - 分享日程安排

### 🎨 多种输出格式
- **PNG图片文件** - 保存到指定路径
- **Base64编码** - 用于嵌入网页或应用
- **数据URL格式** - 直接在HTML中使用
- **ASCII文本** - 终端友好的字符画二维码

### ⚙️ 自定义选项
- **尺寸调整** - 100-1000像素范围
- **错误纠正级别** - L(低)、M(中)、Q(高)、H(最高)
- **输出格式选择** - 根据需要选择合适的格式

## 📦 安装与配置

```bash
# 安装依赖
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二维码（文件输出）
```json
{
  "name": "generate_qrcode",
  "arguments": {
    "content": "https://example.com",
    "contentType": "url",
    "outputFormat": "file",
    "outputPath": "./url_qr.png",
    "size": 300,
    "errorCorrectionLevel": "H"
  }
}
```

#### 文本二维码（Base64输出）
```json
{
  "name": "generate_qrcode",
  "arguments": {
    "content": "Hello, World! 你好世界！",
    "contentType": "text",
    "outputFormat": "base64",
    "size": 200
  }
}
```

#### ASCII文本二维码
```json
{
  "name": "generate_qrcode",
  "arguments": {
    "content": "终端显示的二维码",
    "outputFormat": "text",
    "errorCorrectionLevel": "M"
  }
}
```

### 2. 生成WiFi网络二维码

```json
{
  "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. 生成联系人二维码

```json
{
  "name": "generate_vcard_qrcode",
  "arguments": {
    "name": "张三",
    "phone": "+86 138-0013-8000",
    "email": "zhangsan@example.com",
    "organization": "ABC科技公司",
    "url": "https://zhangsan.example.com",
    "outputFormat": "dataurl",
    "size": 300
  }
}
```

### 4. 生成日历事件二维码

```json
{
  "name": "generate_qrcode",
  "arguments": {
    "content": {
      "title": "重要会议",
      "startDate": "20241201T100000Z",
      "endDate": "20241201T120000Z",
      "location": "会议室A",
      "description": "季度业务回顾会议"
    },
    "contentType": "ical",
    "outputFormat": "file",
    "outputPath": "./meeting_qr.png"
  }
}
```

### 5. 解码二维码

```json
{
  "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配置格式

## 📝 响应格式

### 成功响应示例

#### 文件输出
```json
{
  "success": true,
  "contentType": "url",
  "outputFormat": "file",
  "size": 200,
  "errorCorrectionLevel": "H",
  "outputPath": "./example_qr.png",
  "message": "成功生成二维码文件",
  "encodedContent": "https://example.com"
}
```

#### Base64输出
```json
{
  "success": true,
  "contentType": "text",
  "outputFormat": "base64",
  "size": 200,
  "base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "message": "成功生成Base64二维码"
}
```

#### 数据URL输出
```json
{
  "success": true,
  "outputFormat": "dataurl",
  "dataUrl": "data:image/png;base64,iVBORw0KGgo...",
  "message": "成功生成数据URL二维码"
}
```

#### ASCII文本输出
```json
{
  "success": true,
  "outputFormat": "text",
  "textQR": "█████████████████████████████████\n█████████████████████████████████\n...",
  "message": "成功生成ASCII文本二维码"
}
```

## 🔍 故障排除

### 常见问题

**Q: 生成的二维码无法扫描？**
A: 检查内容长度是否过长，尝试提高错误纠正级别或增大二维码尺寸。

**Q: WiFi二维码连接失败？**
A: 确认SSID和密码正确，检查安全类型设置是否与路由器匹配。

**Q: 文件保存失败？**
A: 检查输出路径的目录是否存在写权限，确保路径格式正确。

**Q: 解码在线图片超时？**
A: 检查图片URL是否可访问，网络连接是否正常。

### 错误代码

- `创建输出目录失败` - 检查文件系统权限
- `生成二维码失败` - 检查输入内容和参数
- `获取图片数据失败` - 检查图片路径或URL
- `解码二维码失败` - 检查图片质量和格式
- `未检测到二维码` - 确认图片中包含有效的二维码

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件。

## 🤝 贡献

欢迎提交问题和功能请求！请确保遵循现有的代码风格和测试规范。

---

*让二维码生成变得简单而强大！* 🚀