星战科技xingzhan.cloud
返回市场
二维码-MCP

二维码-MCP

作者：antoBrugnot4 星标更新：2025-09-29
安装使用来源：spider==github.com

项目介绍

技术文档摘要

QR Code MCP Server

License: MIT Node.js TypeScript Docker Podman Build and Release

MCP Badge

一个使用 Node.js 和 TypeScript 的 MCP（模型上下文协议）服务器，用于从文本或 URL 生成二维码。

🚀 功能特性

  • 多种格式的二维码生成：DataURL（base64）、SVG、终端显示
  • 高级自定义选项：错误纠正级别、大小、边距、颜色
  • 批量生成：一次命令处理多个文本/URL
  • 标准化的 MCP 接口：兼容所有 MCP 客户端
  • 完整的 TypeScript 支持：安全类型和自动补全

📦 安装

选项 1: Docker/Podman（推荐） 🐳

前提条件：系统上安装了 Docker 或 Podman

# 使用 Docker
docker pull antobrugnot/qrcode-mcp-server:latest

# 或者使用 Podman（更安全，无 root）
podman pull antobrugnot/qrcode-mcp-server:latest

# 使用 Docker 进行本地构建
docker build -t qrcode-mcp-server .

# 使用 Podman 进行本地构建
podman build -t qrcode-mcp-server .

选项 2: 本地安装

前提条件：

  • Node.js 18.0.0 或更高版本
  • npm 或 yarn
# 克隆项目
git clone <你的仓库>
cd qrcode-mcp

# 安装依赖
npm install

# 构建项目
npm run build

🛠️ 使用方法

使用 Docker/Podman（推荐）

# 使用 Docker
docker run -i --rm antobrugnot/qrcode-mcp-server:latest

# 使用 Podman（更安全）
podman run -i --rm antobrugnot/qrcode-mcp-server:latest

# 使用 Docker Compose
docker-compose up qrcode-mcp-server

# 使用 Podman Compose
podman-compose up qrcode-mcp-server

# 开发模式
docker-compose --profile dev up qrcode-mcp-dev
# 或
podman-compose --profile dev up qrcode-mcp-dev

本地开发

# 开发模式，带自动重新加载
npm run dev

# 或监视模式
npm run watch

# 为生产构建
npm run build

# 启动已构建的版本
npm start

🔧 可用的 MCP 工具

1. generate-qrcode-dataurl

生成二维码并以 Data URL（base64）形式返回。

参数：

  • text（字符串，必需）：要编码的文本或 URL
  • options（对象，可选）：生成选项
    • errorCorrectionLevel：'L'、'M'、'Q' 或 'H'（默认：'M'）
    • width：像素宽度（50-2000）
    • margin：模块边距（0-10，默认：4）
    • color.dark：深色模块的颜色（默认：'#000000'）
    • color.light：背景颜色（默认：'#FFFFFF'）
    • type：MIME 类型（'image/png'、'image/jpeg'、'image/webp'）

使用示例：

{
  "text": "https://github.com",
  "options": {
    "width": 300,
    "errorCorrectionLevel": "H",
    "color": {
      "dark": "#1f2937",
      "light": "#f3f4f6"
    }
  }
}

2. generate-qrcode-svg

生成 SVG 格式的二维码。

参数：

  • text（字符串，必需）：要编码的文本或 URL
  • options（对象，可选）：生成选项（与 dataurl 相似）

使用示例：

{
  "text": "Hello, World!",
  "options": {
    "width": 200,
    "margin": 2
  }
}

3. generate-qrcode-terminal

生成用于终端显示的二维码。

参数：

  • text（字符串，必需）：要编码的文本或 URL
  • options（对象，可选）：
    • small（布尔值）：使用紧凑格式（默认：false）

使用示例：

{
  "text": "Terminal QR Code",
  "options": {
    "small": true
  }
}

4. generate-qrcode-batch

一次操作生成多个二维码（最多 10 个）。

参数：

  • texts（字符串数组，必需）：要编码的文本/URL 数组（最多 10 个）
  • format（字符串，可选）：输出格式（'dataurl'、'svg'、'terminal'，默认：'dataurl'）
  • options（对象，可选）：生成选项

使用示例：

{
  "texts": [
    "https://github.com",
    "https://www.google.com",
    "Hello World"
  ],
  "format": "dataurl",
  "options": {
    "width": 200
  }
}

🎯 使用 MCP 客户端

Claude Desktop（或 GitHub Copilot）

ℹ️ GitHub Copilot 提示：
对于 GitHub Copilot，配置中的 mcpServers 键变为简单的 servers。

选项 1: 使用 Docker/Podman（推荐）

在你的 claude_desktop_config.json 中添加以下配置：

{
  "mcpServers": {
    "qrcode-generator": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "antobrugnot/qrcode-mcp-server:latest"]
    }
  }
}

或者使用 Podman（更安全，无 root）：

{
  "mcpServers": {
    "qrcode-generator": {
      "command": "podman",
      "args": ["run", "-i", "--rm", "antobrugnot/qrcode-mcp-server:latest"]
    }
  }
}

选项 2: 本地安装

{
  "mcpServers": {
    "qrcode-generator": {
      "command": "node",
      "args": ["/路径/到/qrcode-mcp/dist/index.js"]
    }
  }
}

其他 MCP 客户端

该服务器使用标准的 stdio 传输，并且可以与任何兼容的 MCP 客户端一起使用。

📋 使用示例

生成简单的二维码

为 "https://github.com" 生成二维码

自定义二维码

为 "我的网站" 生成二维码，宽度为 400 像素，带有自定义颜色（深色：#2563eb，浅色：#eff6ff）

批量生成二维码

为这些 URL 生成二维码：https://github.com, https://stackoverflow.com, https://nodejs.org

终端二维码

为 "测试终端" 生成紧凑格式的终端二维码

🔒 安全性

实施的安全措施

  • 安全容器：使用非 root 用户（UID 1001）
  • Alpine 镜像：最小的基础镜像以减少攻击面
  • 限制的能力：移除所有不必要的 Linux 能力
  • 只读文件系统：容器只读以防止修改
  • 资源限制：CPU 和内存限制以防止 DoS 攻击
  • 安全扫描：使用 Trivy 自动扫描漏洞
  • 依赖审核：自动检查 npm 依赖项
  • 多阶段构建：优化构建，生产环境中不包含开发工具

最佳实践

  • 始终使用最新标记的版本
  • 定期检查安全更新
  • 监控 GitHub Security 警报
  • 使用 GitHub Secrets 存储 DockerHub 访问令牌

🔄 CI/CD

自动化流程

  • 自动测试：TypeScript、构建和安全审计
  • 多架构构建：支持 AMD64 和 ARM64
  • 自动推送：带有适当标签的 DockerHub
  • 安全扫描：Trivy 检测漏洞
  • 自动发布：带有自动生成说明的 GitHub Releases

需要配置的环境变量

# 在 GitHub Secrets 中
DOCKERHUB_TOKEN=你的_dockerhub_令牌

🏗️ 架构

qrcode-mcp/
├── .github/
│   └── workflows/        # GitHub Actions CI/CD
├── scripts/
│   └── release.sh        # 发布脚本
├── src/
│   └── index.ts          # 主 MCP 服务器
├── dist/                 # 编译文件
├── Dockerfile            # Docker 配置
├── docker-compose.yml    # Docker 编排
├── .dockerignore         # Docker 排除
├── package.json          # 依赖项和脚本
├── tsconfig.json         # TypeScript 配置
├── CONFIGURATION.md      # 配置指南
└── README.md            # 文档

🔧 使用的技术

  • Node.js：JavaScript 运行时
  • TypeScript：静态类型
  • @modelcontextprotocol/sdk：官方 MCP SDK
  • qrcode：二维码生成库
  • zod：模式验证

📝 错误纠正级别

  • L（低）：约 7% 的错误恢复
  • M（中）：约 15% 的错误恢复（推荐）
  • Q（四分位）：约 25% 的错误恢复
  • H（高）：约 30% 的错误恢复

🐛 故障排除

错误 "模块未找到"

确保已安装依赖项：

npm install

TypeScript 编译错误

检查 tsconfig.json 配置并重新构建：

npm run build

服务器无法启动

确保已安装 Node.js 18+：

node --version

🚀 发布和部署

创建新版本

# 使用发布脚本
./scripts/release.sh v1.0.0

# 或通过 GitHub Actions 手动触发
# GitHub → Actions → 发布 → 运行工作流

自动发布流程

  1. 验证：测试、构建和检查
  2. 版本控制：更新 package.json 并创建标签
  3. Docker 构建：构建和推送多架构
  4. 安全扫描：使用 Trivy 分析安全
  5. GitHub 发布：创建带有自动生成说明的发布
  6. 通知：确认成功

可用的 Docker 镜像

# 最新稳定版
docker pull antobrugnot/qrcode-mcp-server:latest

# 特定版本
docker pull antobrugnot/qrcode-mcp-server:v1.0.0

# 开发版本（develop 分支）
docker pull antobrugnot/qrcode-mcp-server:develop

🤝 贡献

欢迎贡献！请随时打开问题或提交拉取请求。

贡献流程

  1. 分叉项目
  2. 创建功能分支（git checkout -b feature/amazing-feature）
  3. 提交更改（git commit -m '添加神奇功能'）
  4. 推送到分支（git push origin feature/amazing-feature）
  5. 打开拉取请求

代码标准

  • 使用 TypeScript 严格模式
  • 遵循 ESLint/Prettier 规则
  • 为新功能添加测试
  • 如有必要，请更新文档

📄 许可证

MIT 许可证 - 详情见 LICENSE 文件。

🔗 相关链接