Enhanced QR Code MCP Server

增强型二维码MCP服务器

  

先进的 模型上下文协议（MCP）服务器 生成二维码 自动将它们保存为PNG文件 具有全面的元数据、批处理功能和文件管理工具。

🔗 双重实施策略\ 这 Python实现 专注于 可靠的文件生成和批处理.\ 对于 高级样式、分析和模板，查看我们的 TypeScript实现.

基于并增强了: @jwalsh/mcp服务器qrcode 此增强版本添加了自动文件生成、元数据跟踪、批处理和生产就绪功能，同时保持了与MCP协议的完全兼容性。

🚀 与原版相比的主要增强功能

🛠️ 安装

先决条件

• Python 3.8+
• MCP客户端（克劳德桌面、VS代码扩展等）

快速设置

git clone https://github.com/myownipgit/enhanced-qrcode-mcp.git
cd enhanced-qrcode-mcp
chmod +x setup.sh
./setup.sh

手动设置

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Make server executable
chmod +x src/enhanced_qrcode_server.py

🔧 MCP客户端配置

添加到MCP客户端配置中：

{
  "mcpServers": {
    "enhanced-qrcode": {
      "command": "python3",
      "args": ["/path/to/enhanced-qrcode-mcp/src/enhanced_qrcode_server.py"],
      "env": {},
      "description": "Enhanced QR code generator with automatic PNG file saving"
    }
  }
}

📚 可用工具

1. generate_and_save_qrcode

生成一个二维码并自动保存为PNG文件。

参数：

• content （必填）：要编码的文本内容
• output_directory：目标目录（默认： ./qr_output/)
• filename：自定义文件名（如果为空，则自动生成）
• errorCorrectionLevel：L、M、Q或H（默认值：M）
• size：大小倍数1-20（默认值：5）
• border：边框大小1-20（默认值：4）
• include_metadata：生成JSON元数据（默认值：true）
• display_in_chat：在聊天界面中显示（默认值：true）

例子：

{
  "content": "https://github.com/myownipgit/enhanced-qrcode-mcp",
  "output_directory": "./qr_codes/",
  "filename": "github_repo",
  "errorCorrectionLevel": "H",
  "size": 6
}

输出：

• PNG 文件 ： github_repo.png
• 元数据： github_repo_metadata.json
• 聊天显示（可选）

2. batch_generate_qrcodes

从阵列输入生成多个二维码。

例子：

{
  "qr_codes": [
    {
      "id": "contact",
      "content": "BEGIN:VCARD\nVERSION:3.0\nFN:John Doe\nORG:Acme Corp\nTEL:555-0123\nEMAIL:john@acme.com\nEND:VCARD",
      "type": "vcard"
    },
    {
      "id": "website", 
      "content": "https://example.com",
      "type": "url"
    }
  ],
  "output_directory": "./batch_output/",
  "size": 5
}

输出：

• PNG文件： qr_contact.png, qr_website.png
• 单个元数据文件
• 批次清单： batch_manifest_YYYYMMDD_HHMMSS.json

3. list_generated_qrcodes

列出包含元数据的目录中的所有二维码文件。

{
  "directory": "./qr_output/"
}

📁 文件结构

生成的文件

output_directory/
├── qr_20250616_143022_hello_world.png
├── qr_20250616_143022_hello_world_metadata.json
├── github_repo.png
├── github_repo_metadata.json
└── batch_manifest_20250616_143500.json

元数据格式

{
  "generated_date": "2025-06-16T14:30:22.123456",
  "content": "Hello World!",
  "parameters": {
    "error_correction": "M",
    "size": 5,
    "border": 4,
    "box_size": 10
  },
  "png_file": "/path/to/qr_file.png",
  "file_size_bytes": 1117
}

🎯 用例

业务应用程序

• 事件管理：生成门票二维码，准备打印PNG文件
• 营销：使用跟踪元数据创建活动二维码
• 库存：使用自动文件组织生成资产标签
• 联系人共享：批量创建名片的vCard二维码

技术集成

• 印刷制作：设计工作流程的直接PNG输出
• API工作流：从数据库记录批量生成二维码
• 资产管理：具有元数据的有组织文件结构
• 质量控制：不同环境的纠错级别

🧪 测试

运行综合测试套件：

# Activate virtual environment
source venv/bin/activate

# Run tests
python3 tests/test_server.py

预期产量：

🚀 Running Enhanced QR Code MCP Server Tests
✅ QR code generation successful
✅ Filename generation tests passed  
✅ File operations tests passed
✅ Integration test passed - 3 files generated
📊 Test Results: 4/4 passed
🎉 All tests passed! Enhanced MCP server is ready to use.

📈 演出

• 单个二维码：~50ms生成+文件保存
• 批量处理：每个代码+清单约100ms
• 元数据生成：每个文件约5ms
• 文件列表：每100个文件约10ms

🔍 错误纠正级别

• L（低）：约7%的损伤恢复-基本室内使用
• M（中等）：~15%损伤恢复-标准使用（默认）
• Q（四分位数）：约25%的损坏恢复-工业环境
• H（高）：约30%的损伤恢复-室外/受损表面

🚀 未来的增强功能

查看我们的综合 ROADMAP.md 详细的开发计划，包括：

🔄 即将推出（v2.1.0）

• 结构化内容构建器 用于vCard、WiFi和活动
• SVG和PDF输出格式
• 增强验证 内容优化

🎨 高级功能（在TypeScript版本中可用）

我们的 TypeScript实现 已经包括：

• 自定义样式 带有颜色、徽标和渐变
• 二维码分析 以及解码能力
• 模板系统 具有预定义的样式
• 质量评价 带有推荐的工具

🔗 选择正确的实施方式

🐛 故障排除

常见问题

ModuleNotFoundError:没有名为“mcp”的模块

pip install mcp

setup.sh上的权限被拒绝

chmod +x setup.sh

二维码未保存

• 检查目录权限
• 验证输出路径是否存在
• 检查磁盘空间

测试服务器

# Test dependencies
python3 -c "import qrcode, mcp; print('✅ Dependencies OK')"

# Test server startup
python3 src/enhanced_qrcode_server.py

🤝 贡献

欢迎投稿！请看 贡献.md 作为指导方针。

开发设置

git clone https://github.com/myownipgit/enhanced-qrcode-mcp.git
cd enhanced-qrcode-mcp
./setup.sh
source venv/bin/activate
python3 tests/test_server.py

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 原创作品: @jwalsh/mcp服务器qrcode -基金会二维码MCP服务器
• MCP协议: 模型上下文协议 -实现AI工具集成
• 二维码库: 二维码 -核心二维码生成
• 枕头: PIL/枕头 -图像处理能力

🔗 相关项目

• 增强的TypeScript版本 -先进的造型和分析功能
• 原始MCP二维码服务器 -它所建立的基础
• 模型上下文协议 -MCP规范和工具
• 克劳德桌面 -支持MCP的AI助手

📊 存储库统计信息

• 语言：Python 3.8+
• 依赖项：MCP、qrcode、枕头
• 测试覆盖率：100%（4/4测试通过）
• 文档：附有示例
• 许可证：MIT

______________________________________________________________________

增强型二维码MCP服务器v2.0.0\ *生产就绪的二维码生成，自动输出PNG文件和全面的元数据*

内置于❤️ 在良好的基础上 @jwalsh/mcp服务器qrcode