# QR Reader MCP Server

**视觉模型能看到图片里有二维码，但解不了码。这个 MCP 补上了这个缺口——让模型"看到即读到"。**

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-1.0-blueviolet)](https://modelcontextprotocol.io/)

---

## 解决什么问题

视觉模型能识别出"图里有一个二维码"，但二维码解码走的是像素→二进制数据→文本的算法路径，模型做不到。这就导致一个很尴尬的场景：用户发来一张带二维码的截图，AI 只能说"我看到有个码"却读不出里面的内容。

QR Reader MCP Server 把二维码解码能力**嵌入**视觉模型的工作流——模型看到图片 → 调用 MCP 解码 → 拿到内容 → 继续处理。就像给模型装了一个二维码驱动。

### 两个工具

| 工具 | 说明 |
|---|---|
| `decode_qrcode_full` | 扫描整张图片，返回所有二维码的内容 |
| `enhance_and_decode` | 对模糊/反光/太小的区域做增强后再解码 |

### 比成功/失败更多的信息

实际场景中二维码质量参差不齐——模糊、反光、太小、对比度不够。MCP 在返回解码结果的同时，也附带了图像质量数据（模糊度、对比度、反光比例）和 `result_code`。Agent 拿到这些信息后，可以自然地告诉用户"这个码有点模糊，换个角度拍"或者"反光挡住了，调整一下光源"，而不需要用户自己猜测问题出在哪。

---

## 快速开始

### 前置依赖

**Linux（Debian / Ubuntu）：**
```bash
sudo apt install libzbar0
```

**macOS：**
```bash
brew install zbar
```

**Windows：**（三种方案，任选其一）

| 方案 | 说明 | 推荐 |
|------|------|:---:|
| **Docker** | `docker run -i --rm ghcr.io/<your-org>/qr-reader-mcp-server` — 零配置，自带 zbar | ⭐ |
| **预编译 DLL** | 从 [zbar Windows builds](https://github.com/NaturalHistoryMuseum/pyzbar#windows) 下载 `libzbar-64.dll`，放到 Python 安装目录或项目根目录 | ✅ |
| **vcpkg** | `vcpkg install zbar`，然后设置 `ZBAR_PATH` 环境变量指向 vcpkg 的 `bin` 目录 | 备选 |

> 💡 如果 Windows 上 `pip install pyzbar` 后导入报错 `ImportError`，大概率是 zbar DLL 没找到。最省事的方式是用 **Docker** 运行。

### 安装运行

```bash
# 克隆
git clone https://github.com/Shalim-C/QR.git
cd QR

# 安装
pip install -e .

# 启动（stdio 模式）
python -m qr_reader.server
```

### 接入 MCP 客户端

#### Claude Desktop

编辑 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "qr-reader": {
      "command": "python",
      "args": ["-m", "qr_reader.server"],
      "env": {
        "LOG_LEVEL": "info",
        "READ_ONLY_MODE": "false"
      }
    }
  }
}
```

或使用 Docker：

```json
{
  "mcpServers": {
    "qr-reader": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "ghcr.io/<your-org>/qr-reader-mcp-server"
      ]
    }
  }
}
```

#### VS Code / Cursor

[![Install in VS Code](https://img.shields.io/badge/VS_Code-一键安装-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=qr-reader&config=%7B%22command%22%3A%22python%22%2C%22args%22%3A%5B%22-m%22%2C%22qr_reader.server%22%5D%7D)

点击上方按钮一键安装，或手动配置：

`Ctrl + Shift + P` → `MCP: Open User Configuration`，添加：

```json
{
  "servers": {
    "qr-reader": {
      "command": "python",
      "args": ["-m", "qr_reader.server"],
      "env": {
        "LOG_LEVEL": "info",
        "READ_ONLY_MODE": "false"
      }
    }
  }
}
```

#### Continue.dev

编辑 `~/.continue/config.json`：

```json
{
  "experimental": {
    "mcpServers": {
      "qr-reader": {
        "command": "python",
        "args": ["-m", "qr_reader.server"],
        "env": {
          "LOG_LEVEL": "info"
        }
      }
    }
  }
}
```

#### Reasonix

编辑 `config.toml`，在 `[[plugins]]` 段追加：

```toml
[[plugins]]
name    = "qr-reader"
command = "python"
args    = ["-m", "qr_reader.server"]
env     = { LOG_LEVEL = "info", READ_ONLY_MODE = "false" }
```

#### Codex (OpenAI) / Zed / Cursor

这些客户端在 Web 控制台或设置面板中配置 MCP Server，搜索 "MCP Server" 选项，填入：

- **Command:** `python`
- **Arguments:** `-m qr_reader.server`
- **Environment:** `LOG_LEVEL=info`

### 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `LOG_LEVEL` | `info` | 日志级别：`debug`、`info`、`warning`、`error` |
| `READ_ONLY_MODE` | `false` | 设为 `true` 禁用 `enhance_and_decode`（仅保留 `decode_qrcode_full`） |
| `MAX_IMAGE_SIZE` | `10485760` | 图片大小上限（字节，默认 10 MB） |

---

## 工具说明

### `decode_qrcode_full`

对整张图片进行二维码识别和解码，返回结构化结果和质量指标。

**输入参数：**

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `image_base64` | string | 二选一 | Base64 编码的图片 |
| `image_url` | string | 二选一 | 图片 URL |

**返回示例：**

```json
{
  "success": true,
  "result_code": "SUCCESS",
  "results": [
    {
      "content": "https://example.com",
      "bbox": [50, 60, 200, 200],
      "type": "QRCODE",
      "raw_bytes": "..."
    }
  ],
  "diagnosis": {
    "total_detected": 1,
    "quality": {
      "blur_score": 128.5,
      "contrast": 0.72,
      "glare_ratio": 0.05,
      "noise_level": 12.3
    }
  },
  "suggestion": null
}
```

### `enhance_and_decode`

裁剪指定区域，执行增强操作后再解码。

**输入参数：**

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `image_base64` | string | 二选一 | Base64 编码的图片 |
| `image_url` | string | 二选一 | 图片 URL |
| `bbox` | [int,int,int,int] | 是 | 目标区域 `[x, y, width, height]` |
| `operations` | object[] | 是 | 增强操作列表（见下方） |

**增强操作：**

| 操作 | 说明 | 关键参数 |
|---|---|---|
| `upscale` | 放大区域 | `scale`（默认 2.0） |
| `sharpen` | 锐化边缘 | `strength`（默认 1.5） |
| `adjust_contrast` | 调整对比度 | `alpha`（默认 1.5），`beta`（默认 0） |
| `denoise` | 降噪 | `h`（默认 10） |

---

## 结果码说明

`result_code` 告诉 AI 助手下一步该做什么：

| 结果码 | 含义 | AI 应该做什么 |
|---|---|---|
| `SUCCESS` | 解码成功 | 直接使用内容 |
| `SUCCESS_WITH_WARNING` | 解码成功但内容可能有异常 | 检查警告，验证内容 |
| `RETRYABLE` | 质量问题，可修复 | 调用 `enhance_and_decode` 重试 |
| `NO_QR_FOUND` | 未检测到二维码 | 告知用户图中没有二维码 |
| `QR_UNRECOVERABLE` | 二维码已损坏无法恢复 | 告知用户二维码损坏 |

---

## 示例对话

接入后试试对 AI 助手说：

- "帮我读一下这张截图里的二维码"
- "这个二维码太模糊了，试试增强后再读"
- "扫描这张照片里的所有二维码，列出内容"
- "这个收据上的码很难扫——能修复一下吗？"

---

## 只读模式

设置 `READ_ONLY_MODE=true` 后，仅保留 `decode_qrcode_full` 工具。此模式下 `enhance_and_decode` 不可用——AI 只能扫描，不能修改图片。

适用于审计/日志场景，确保行为确定、无副作用。

---

## 安全说明

- 本服务只处理你提供的图片，不访问你的文件系统
- `image_url` 仅用于获取你指定的图片，不做其他网络请求
- stdio 模式下无需 API Key 或认证
- 设置 `MAX_IMAGE_SIZE` 可限制内存占用
- 日志不记录图片内容和解码数据

---

## 项目结构

```
qr-reader-mcp-server/
├── README.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
├── .env.example
├── .gitignore
├── Dockerfile
├── docker-compose.yml
├── .github/
│   └── workflows/
│       ├── ci.yml
│       └── release.yml
├── docs/
│   ├── setup.md
│   ├── tools.md
│   ├── troubleshooting.md
│   └── prompts.md
├── src/
│   └── qr_reader/
│       ├── __init__.py
│       ├── server.py          # MCP 入口
│       └── core/
│           ├── __init__.py
│           ├── decoder.py     # 二维码解码（基于 pyzbar）
│           ├── quality.py     # 图像质量分析
│           └── diagnosis.py   # 结果分类诊断
└── tests/
    ├── __init__.py
    ├── test_decoder.py
    ├── test_diagnosis.py
    └── test_quality.py
```

---

## 开发

### 本地运行与调试

```bash
git clone https://github.com/Shalim-C/QR.git
cd QR
pip install -e ".[dev]"
```

### MCP Inspector 验证

使用 MCP Inspector 在浏览器中调试工具调用，无需配置客户端：

```bash
npx @modelcontextprotocol/inspector python -m qr_reader.server
```

浏览器打开后即可在 UI 中手动调用 `decode_qrcode_full` 和 `enhance_and_decode`，查看返回结果。

### 运行测试

```bash
pytest tests/ -v
```

CI 在 3 个 Python 版本（3.10 / 3.11 / 3.12）上运行测试 + Docker 镜像构建，详见 `.github/workflows/ci.yml`。

### Docker 构建

```bash
docker build -t qr-reader-mcp-server .
```

---

## 开源协议

MIT — 详见 [LICENSE](LICENSE)。