Сервер 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.
Передумови
- Ключ API — увійдіть на qr-branding.com, перейдіть у Кабінет → Ключі API, натисніть Згенерувати ключ і одразу скопіюйте значення
qrb_…. Більше ви його не побачите, але можна випустити ще ключі. - План Studio — API потребує активного пакета Studio. З будь-яким іншим планом виклики інструментів завершуються помилкою
studio_required, а помилка доходить до моделі з підказкою перейти на Studio. Генерації ШІ також витрачають кредити ШІ Studio (out_of_api_credits, коли вони закінчаться). - 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_URL | https://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.