Перейти до вмісту

Сервер MCP QR Branding

Спілкуйтеся зі своїм редактором або настільним ШІ-застосунком і доручайте йому генерувати QR-коди через рушій QR Branding. Сервер MCP обгортає публічний API у набір інструментів, які може викликати будь-який клієнт, сумісний із MCP. Користуватися ним можна двома способами:

  • Віддалений сервер https://qr-branding.com/mcp: нічого встановлювати не потрібно, достатньо вставити URL і свій ключ API в клієнт.
  • Локальний сервер, пакет npm @qr-branding/mcp-server (Node 20+), який ваш клієнт запускає через stdio.

Обидва надають ті самі одинадцять інструментів і автентифікуються тим самим ключем API QR Branding. npm: @qr-branding/mcp-server.

Що ви отримуєте

Одинадцять інструментів, зіставлених із публічним шлюзом за адресою https://qr-branding.com/api/v1/*:

ІнструментЩо робить
qr_generateРучна генерація: передайте практичну підмножину QrConfig (вміст, кольори, форми модулів і маркерів, рівень ECC, формат і розмір виводу, за потреби логотип і підпис). Повертає відрендерений PNG/JPG/WEBP/SVG/PDF.
qr_scan_checkПеревірка перед друком: рендерить дизайн і декодує його за 13 змодельованих умов (дрібний шрифт, відстань, розмиття, тьмяне світло, низький контраст, відблиски, шум, обертання). Повертає оцінку, symbolModules, версію, smallestModulePx, звіт за кожною умовою, мінімальний розмір друку на відстані столу, стіни й вулиці в мм, designScore і designWarnings. Працює і в пробному режимі без ключа.
qr_generate_aiПромпт ШІ на сервері → QR. Дайте промпт на кшталт «акварельний захід сонця» та URL або текст вмісту; рушій сам обирає кольори й форми та рендерить.
qr_get_templateПовертає повну конфігурацію дизайну шаблону, щоб її оглянути й потім доопрацювати через qr_generate.
qr_posterГотовий до друку плакат навколо одного дизайну: a4/a5/a6/letter, макети minimal/band/card/tent, заголовок, інструкція й підпис, showLogo, припуск 3 мм, мітки різу та акцентний колір. Повертає векторний PDF (типово) або PNG на 36–300 dpi.
qr_list_templatesПерегляд 118 готових шаблонів (id, назва, опис, URL мініатюри попереднього перегляду).
qr_generate_from_templateРендерить шаблон за id з перевизначеннями для кожного виклику: змініть вміст, замініть кольори, налаштуйте формат виводу.
qr_build_wifiКодує облікові дані Wi-Fi (WIFI:T:WPA;S:...;P:...;;) і повертає і рядок, і QR.
qr_build_vcardКодує контактну картку (vCard) і повертає рядок та QR.
qr_build_geoКодує URI geo: із широти й довготи та повертає рядок і QR.
qr_list_ai_providersПерелічує провайдерів LLM, яких приймає рушій для ШІ-дизайнів із власним ключем (POST /api/qr/ai/generate): ідентифікатор кожного провайдера, його типова модель і рекомендовані ідентифікатори моделей. Підходить будь-який ідентифікатор моделі, який пропонує ваш провайдер; список — це рекомендація, а не білий список. qr_generate_ai його не потребує, бо використовує керований шлях.

qr_build_vcard підтримує такі поля: firstName (обов’язкове), lastName, organization, phone, email і url. Поштова адреса, посада й нотатки поки не підтримуються. qr_build_geo приймає лише latitude і longitude (без висоти).

Растрові формати (PNG, JPG, WEBP) і SVG повертаються як вбудовані блоки зображень, тож клієнти, що відображають зображення MCP, показують QR прямо в чаті. PDF вбудувати не можна: локальний сервер записує його у тимчасовий файл і повертає шлях; віддалений сервер повертає його як вбудований ресурс application/pdf.

Передумови

  1. Ключ API — увійдіть на qr-branding.com, перейдіть у Кабінет → Ключі API, натисніть Згенерувати ключ і одразу скопіюйте значення qrb_…. Більше ви його не побачите, але можна випустити ще ключі.
  2. План Studio — API потребує активного пакета Studio. З будь-яким іншим планом виклики інструментів завершуються помилкою studio_required, а помилка доходить до моделі з підказкою перейти на Studio. Генерації ШІ також витрачають кредити ШІ Studio (out_of_api_credits, коли вони закінчаться).
  3. Node 20+ — лише для локального сервера, на машині, де працює процес MCP (зазвичай це ваш ноутбук). Встановленням займається npx.

Віддалений сервер (Streamable HTTP)

Ендпоінт — https://qr-branding.com/mcp, він працює з транспортом Streamable HTTP протоколу MCP (без стану, відповіді JSON). Надсилайте ключ в одному з двох заголовків:

  • Authorization: Bearer qrb_PASTE_YOUR_KEY (так налаштовує більшість клієнтів)
  • X-API-Key: qrb_PASTE_YOUR_KEY (той самий заголовок, що й у REST API)

Запит із недійсним або відкликаним ключем отримує 401 із заголовком WWW-Authenticate: Bearer.

Пробний режим без ключа. Зовсім без ключа віддалений сервер працює в пробному режимі: усі інструменти, крім qr_generate_ai, рендери PNG до 720 px і 20 викликів інструментів на день для однієї мережі. Додайте ключ, щоб відкрити AI-дизайни, усі формати й розміри та ліміти свого плану. Локальний npm-сервер завжди потребує ключа.

Claude Code (CLI)

claude mcp add --transport http qr-branding https://qr-branding.com/mcp \
  --header "Authorization: Bearer qrb_PASTE_YOUR_KEY"

Виконайте /mcp у сесії, щоб переконатися, що сервер підключено, і попросіть, наприклад, «згенеруй QR для https://qr-branding.com з модулями у формі листка та золотим кольором»; Claude викличе qr_generate.

Cursor

~/.cursor/mcp.json (або Settings → MCP):

{
  "mcpServers": {
    "qr-branding": {
      "url": "https://qr-branding.com/mcp",
      "headers": { "Authorization": "Bearer qrb_PASTE_YOUR_KEY" }
    }
  }
}

VS Code (режим агента GitHub Copilot)

.vscode/mcp.json у вашому робочому просторі:

{
  "servers": {
    "qr-branding": {
      "type": "http",
      "url": "https://qr-branding.com/mcp",
      "headers": { "Authorization": "Bearer qrb_PASTE_YOUR_KEY" }
    }
  }
}

Інші клієнти

Будь-який клієнт, що підтримує Streamable HTTP із власними заголовками, працює з тією самою парою url + headers. Клієнт, який запускає лише сервери stdio, може скористатися локальним сервером.

Користувацькі конектори claude.ai і Claude Desktop

Користувацькі конектори, додані з claude.ai (вебверсія та налаштування конекторів Claude Desktop), автентифікуються через OAuth, який підтримує віддалений сервер: вкажіть конектору https://qr-branding.com/mcp, і клієнт сам проведе потік OAuth 2.1. Клієнти, які можуть надіслати заголовок із ключем API, працюють як і раніше, а Claude Desktop може також використовувати локальний сервер через stdio з QR_BRANDING_API_KEY (нижче).

Локальний сервер (npm, stdio)

Ваш клієнт запускає npx @qr-branding/mcp-server і обмінюється JSON-RPC через stdin/stdout процесу. Ключ задається в змінній середовища QR_BRANDING_API_KEY.

Claude Code (CLI)

claude mcp add qr-branding --env QR_BRANDING_API_KEY=qrb_PASTE_YOUR_KEY -- npx -y @qr-branding/mcp-server

Claude Desktop (macOS / Windows)

Відкрийте файл конфігурації:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "qr-branding": {
      "command": "npx",
      "args": ["-y", "@qr-branding/mcp-server"],
      "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
    }
  }
}

Повністю закрийте Claude Desktop і відкрийте знову. Сервер QR Branding має з’явитися як доступний у меню інструментів біля поля введення повідомлення.

Cursor

{
  "mcpServers": {
    "qr-branding": {
      "command": "npx",
      "args": ["-y", "@qr-branding/mcp-server"],
      "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
    }
  }
}

Перезапустіть Cursor. Інструменти доступні і агентові в чаті, і Composer.

ChatGPT Desktop

ChatGPT Desktop читає ~/.openai/chatgpt/mcp-config.json (шлях може відрізнятися залежно від версії — перевірте в Settings → Beta features → Model Context Protocol):

{
  "mcpServers": {
    "qr-branding": {
      "command": "npx",
      "args": ["-y", "@qr-branding/mcp-server"],
      "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
    }
  }
}

Continue (розширення VS Code / JetBrains)

У конфігурації Continue (~/.continue/config.json або .continue/config.json робочого простору), у розділі mcpServers:

"mcpServers": [
  {
    "name": "qr-branding",
    "command": "npx",
    "args": ["-y", "@qr-branding/mcp-server"],
    "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
  }
]

Zed

Відкрийте ~/.config/zed/settings.json і додайте в context_servers:

"context_servers": {
  "qr-branding": {
    "source": "custom",
    "command": "npx",
    "args": ["-y", "@qr-branding/mcp-server"],
    "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
  }
}

Змінні середовища (локальний сервер)

ЗміннаТипове значенняНавіщо її змінювати
QR_BRANDING_API_KEY(не задано)Ваш ключ qrb_…. Починаючи з 0.2.1 сервер запускається й без нього та виводить одне попередження: tools/list працює, а виклики інструментів, яким потрібен API, повертають помилку missing_api_key. Пробний режим без ключа доступний лише на віддаленому сервері.
QR_BRANDING_API_BASE_URLhttps://qr-branding.comВкажіть тестове середовище або власний шлюз. Корисно під час розробки.

Перевірка роботи

Віддалений сервер: виведіть список інструментів за допомогою curl:

curl -s https://qr-branding.com/mcp \
  -H "Authorization: Bearer qrb_PASTE_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Локальний сервер: запустіть димовий тест із вихідного коду:

cd mcp-server
npm install
QR_BRANDING_API_KEY=qrb_xxx npm run smoke
QR_BRANDING_API_KEY=qrb_xxx SMOKE_GENERATE=1 npm run smoke

Димовий тест опитує /api/v1/qr/ping і /api/v1/qr/templates, виводить кількість шаблонів і (з SMOKE_GENERATE=1) наскрізно генерує крихітний тестовий QR.

Вартість і обмеження

  • Виклики генерації: ручна генерація, шаблони й допоміжні інструменти вмісту не витрачають кредитів; генерація ШІ на наших ключах (qr_generate_ai) витрачає один кредит ШІ Studio. Виклики списків і метаданих шаблонів теж не витрачають кредитів. Див. Ціни й кредити.
  • Ліміти запитів — це ліміти шлюзу: див. огляд API. На віддаленому сервері кожен виклик інструмента рахується як один запит у межах хвилинного ліміту та добової квоти вашого ключа; рукостискання й tools/list враховуються лише в ліміті на мережу.
  • Вартість з боку ШІ-асистента залежить від тарифів вашого асистента (використання Claude, підписка ChatGPT тощо). Сам сервер MCP безкоштовний.

Конфіденційність і безпека

  • Сервер MCP пересилає ваші промпти й усі передані URL/тексти на qr-branding.com. Жодної сторонньої телеметрії, жодних SDK аналітики.
  • Ключ API зберігається в конфігурації вашого клієнта — він ніколи не з’являється в історії чату чи контексті моделі. Віддалений сервер отримує його лише через HTTPS і звіряє з хешем, як і REST API.
  • Змінюйте ключ будь-коли в Кабінет → Ключі API — старі ключі відкликаються миттєво.

Усунення несправностей

  • «QR_BRANDING_API_KEY not set» (локально): змінна середовища не дійшла до запущеного процесу npx. Переконайтеся, що JSON коректний, і перезапустіть застосунок-хост.
  • 401 invalid_api_key / missing_api_key (віддалено): заголовок не дійшов або ключ відкликано. Перевірте заголовок Authorization: Bearer qrb_… у конфігурації клієнта.
  • studio_required — у вашому обліковому записі немає активного пакета Studio (Starter і Pro містять лише редактор). Придбайте Studio на сторінці цін.
  • out_of_api_credits — кредити ШІ Studio закінчилися. Поповніть їх на сторінці цін.
  • Зображення не відображається вбудовано: ваш клієнт, імовірно, не підтримує вміст-зображення MCP. Растрові зображення та SVG використовують тип вмісту-зображення зі специфікації; PDF повертаються як шлях до файлу (локально) або вбудований ресурс (віддалено).
  • Помилки мережі / тайм-аути: шлюз розташований за адресою https://qr-branding.com. Якщо ваша мережа його блокує, перевизначте QR_BRANDING_API_BASE_URL (локальний сервер).

Що далі

Ми відстежуємо ці пункти для наступних випусків:

  • Інструмент qr_dynamic_create, що створює друковані динамічні QR (редиректор q.qr-branding.com/{slug}), не виходячи з чату.
  • Обробники ресурсів для перегляду шаблонів як ресурсів MCP (щоб клієнти з вибором ресурсів могли показувати їх у своєму інтерфейсі).

Питання або запити на функції: пишіть на support@qr-branding.com.