RepairDesk MCP Server

Сервер MCP (Model Context Protocol), который даёт любому MCP-совместимому ИИ-ассистенту — Claude Code, Claude Desktop, Codex CLI, OpenCode, Cursor, Windsurf или любому другому MCP-клиенту — прямой доступ на чтение и запись к данным вашего магазина RepairDesk. Укажите API-ключ вашего магазина и задавайте вопросы вроде «найди заявку T-15423», «что просрочено по счёту 8821» или «назначь замену экрана iPhone Дейву».

Это не официальный продукт RepairDesk — независимый инструмент, созданный магазином RepairDesk для магазинов RepairDesk. Без гарантий, используйте на свой страх и риск (см. Лицензия) — но он ежедневно используется для управления очередью заявок реальной ремонтной мастерской, а не как демонстрация концепции.

Содержание

• Что с этим реально можно делать

• Справочник инструментов

• Что это не

• Быстрый старт

• Настройка вручную

• Все параметры конфигурации

• Поиск и устранение неисправностей

• Часто задаваемые вопросы

• Безопасность

Related MCP server: TicketAI

Что с этим реально можно делать

Как только он подключён к вашему ИИ-ассистенту, вы можете просто общаться со своими данными RepairDesk, вместо того чтобы кликать по веб-интерфейсу. Вот несколько реальных примеров:

Ресепшн / первичный приём

• «Найди заявку T-15423» — полная информация о заявке: клиент, устройство, статус по каждому устройству, заметки.

• «Какой статус у телефона Сары Миллер?» — поиск заявок по имени клиента/ключевому слову.

• «Покажи всё, что в статусе Pending или Waiting for Parts» — фильтрация заявок по статусу.

• «Что сейчас назначено Дейву?» — фильтрация заявок по технику.

• «Найди контактные данные Джона» — поиск клиента по имени, телефону или email.

Рабочие процессы / ремонтные работы

• «Добавь диагностическую заметку к T-15423: заменён экран, аккумулятор проверен, OK»

• «Назначь заявку T-15490 Дейву»

• «Отметь T-15423 как Repaired» — сервер сначала попросит вас подтвердить действие и предупредит, что этот статус автоматически отправляет клиенту SMS/email в RepairDesk.

• «Создай заявку для этого клиента: iPhone 13, замена экрана» — и здесь также требуется подтверждение, прежде чем будет что-то создано.

Финансы / администрирование

• «Какие счета остались неоплаченными с прошлого месяца?»

• «Какова сумма задолженности по счёту 8821?»

• «Есть ли у нас в наличии аккумулятор для iPhone 13?» — поиск по складу.

• «Перечисли всех наших техников» / «Какие способы оплаты у нас настроены?»

• «Какие категории ремонта/типы устройств у нас настроены?» — полезный контекст при создании заявки или при выяснении, что вообще за модель устройства в вашей системе.

Поскольку это работает через настоящего ИИ-ассистента, а не через фиксированную панель управления, вы можете естественно объединять такие запросы — «найди просроченные счета для клиентов, у которых ещё открыта заявка» — и ассистент сам всё выясняет с помощью инструментов, а вам не нужно вручную сверять данные на двух экранах.

Справочник инструментов

Защитный механизм: repairdesk_tickets_write требует confirmed: true перед применением изменения статуса и предупреждает, если целевой статус относится к тем, о которых RepairDesk автоматически уведомляет клиента (Repaired, Ready for Pickup, Completed, Waiting on Customer, Waiting For Quote, Cancelled). Для работы этой функции ничего делать не нужно — просто ответьте «да», когда ваш ассистент передаст запрос на подтверждение.

Удобная особенность: поиск и запись заявок принимают как формат идентификатора заказа RepairDesk (T-15423), так и внутренний числовой ID заявки — вам не нужно знать, какой именно у вас, сервер определит это за вас.

Что это не

Это покрывает чтение данных RepairDesk, а также основные операции записи, связанные с заявками. Оно не охватывает сметы, создание записей на приём, POS/торговые транзакции, запись на склад, фиксацию платежей, загрузку изображений/вложений к заявкам и вебхуки. PR приветствуются, если вам нужно что-то из этого.

Быстрый старт

Вам не нужно быть разработчиком, чтобы запустить это, — достаточно уверенно вводить несколько команд в терминале. Общее время: около 5 минут.

1. Установите Node.js (если он у вас не установлен)

Скачайте и установите с nodejs.org — выберите версию «LTS». Это устанавливает и node, и npm. Чтобы проверить, что всё работает, откройте терминал и выполните:

node --version

Вы должны увидеть что-то вроде v20.x.x (подойдёт любая версия 18 или выше).

2. Получите код

Если у вас есть Git:

git clone https://github.com/codeyoc/repairdesk-mcp.git
cd repairdesk-mcp

Если нет: нажмите зелёную кнопку Code на странице репозитория GitHub → Download ZIP → распакуйте архив в любое место → откройте терминал в этой папке.

3. Получите API-ключ RepairDesk

В админ-панели RepairDesk: Settings → API. Скопируйте показанный там ключ — скрипт настройки запросит его на следующем шаге. Относитесь к нему как к паролю: он даёт полный доступ на чтение и запись к данным вашего магазина (см. Безопасность).

4. Запустите скрипт настройки

node setup.mjs

Это самый быстрый путь, и он делает всё сам: при необходимости сам запускает npm install, запрашивает ваш API-ключ, спрашивает, каким ИИ-ассистентом вы пользуетесь (Claude Code, Claude Desktop, Codex CLI или OpenCode), и автоматически записывает конфигурацию — сначала создавая резервную копию существующего файла конфигурации. Если у вас что-то другое, он выводит блок конфигурации, который нужно вставить самостоятельно.

Если вы предпочитаете сделать это вручную — или ваш клиент не относится к четырём перечисленным выше — воспользуйтесь разделом Настройка вручную ниже. В любом случае, если вы пропускаете скрипт, сначала самостоятельно выполните npm install.

5. Попробуйте

Спросите у ассистента что-нибудь вроде «С помощью RepairDesk, покажи мои 5 последних заявок». Если он вернёт реальные данные о заявках — всё готово.

Настройка вручную

Пропустите этот раздел, если node setup.mjs у вас уже сработал. В противном случае сначала выполните npm install в этой папке, а затем подключите клиент вручную:

Запустите это из любого места, заменив путь на полный путь к папке, в которую вы распаковали/склонировали проект, а ключ — на ваш настоящий:

claude mcp add repairdesk \
  --env REPAIRDESK_API_KEY=your_key_here \
  --env REPAIRDESK_USER_AGENT=YourShopName-MCP/1.0 \
  -- node /full/path/to/repairdesk-mcp/server.mjs

Откройте (или создайте) файл конфигурации для вашей операционной системы:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Добавьте это (объедините с тем, что уже есть в mcpServers, если файл не пуст):

{
  "mcpServers": {
    "repairdesk": {
      "command": "node",
      "args": ["/full/path/to/repairdesk-mcp/server.mjs"],
      "env": {
        "REPAIRDESK_API_KEY": "your_key_here",
        "REPAIRDESK_USER_AGENT": "YourShopName-MCP/1.0"
      }
    }
  }
}

Сохраните файл, затем полностью выйдите из Claude Desktop и запустите его снова (не просто закройте окно).

Отредактируйте (или создайте) ~/.codex/config.toml и добавьте:

[mcp_servers.repairdesk]
command = "node"
args = ["/full/path/to/repairdesk-mcp/server.mjs"]

[mcp_servers.repairdesk.env]
REPAIRDESK_API_KEY = "your_key_here"
REPAIRDESK_USER_AGENT = "YourShopName-MCP/1.0"

Начните новую сессию Codex и выполните /mcp, чтобы убедиться, что он подключился. (В Codex также есть интерактивная команда codex mcp add, если вы предпочитаете её редактированию файла — посмотрите codex mcp add --help, чтобы узнать точные флаги для вашей установленной версии.)

Откройте (или создайте) файл конфигурации для вашей операционной системы:

• Mac/Linux: ~/.config/opencode/opencode.json

• Windows: %APPDATA%\opencode\opencode.json

Добавьте это (объедините с тем, что уже есть в mcp, если файл не пуст):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "repairdesk": {
      "type": "local",
      "command": ["node", "/full/path/to/repairdesk-mcp/server.mjs"],
      "enabled": true,
      "environment": {
        "REPAIRDESK_API_KEY": "your_key_here",
        "REPAIRDESK_USER_AGENT": "YourShopName-MCP/1.0"
      }
    }
  }
}

Перезапустите OpenCode, чтобы он подхватил изменения.

Форма command/args/env, использованная выше (Claude Code/Desktop), является фактическим стандартом — большинство MCP-клиентов следуют ему, просто в другом файле настроек. Посмотрите в документации вашего клиента, где находится этот файл; сам блок должен работать как есть.

Используйте полный абсолютный путь к server.mjs (например, /Users/you/repairdesk-mcp/server.mjs или C:\Users\you\repairdesk-mcp\server.mjs) — относительный путь не сработает, потому что ваш ИИ-клиент запускается не из этой папки.

Все параметры конфигурации

Всё, что указано ниже, помещается в блок env/environment, который использует конфигурация вашего клиента (setup.mjs сделает это за вас), — а не в файл .env, поскольку большинство MCP-клиентов не читают его автоматически. Файл .env.example в этом репозитории перечисляет те же переменные для справки.

Альтернатива: файл конфигурации вместо переменных окружения. Если ваша настройка делает переменные окружения неудобными, создайте config.json (в gitignore) рядом с server.mjs:

{
  "repairdesk_api_key": "your_key_here",
  "repairdesk_base_url": "https://api.repairdesk.co/api/web/v1"
}

Он перечитывается при каждом вызове API, так что вы можете ротировать ключ без перезапуска сервера. Переменные окружения имеют приоритет над этим файлом, когда присутствуют оба.

Ограничение частоты запросов — те самые 100 в минуту

Документированный лимит RepairDesk — 100 запросов в минуту на один API-ключ (некоторые тарифы допускают до 120 — проверьте свой тариф, если не уверены). Этот сервер обрабатывает это за вас автоматически:

• Каждый исходящий вызов ставится в очередь через единый ограничитель, который ждёт не менее REPAIRDESK_MIN_INTERVAL_MS (по умолчанию 600 мс ≈ 100/мин) между запросами — так что запрос большого пакета тикетов сам по себе не вызовет ошибку ограничения частоты.

• Если RepairDesk всё же возвращает 429 (ограничение частоты) — например, другой инструмент также активно использует тот же ключ — сервер автоматически ждёт и повторяет попытку один раз, прежде чем сдаться.

• Для работы этого ничего настраивать не нужно. Трогайте REPAIRDESK_MIN_INTERVAL_MS только если вы постоянно видите ошибки ограничения частоты (увеличьте его) или если вы знаете, что ваш тариф допускает более высокий лимит, и хотите ускорить массовые запросы (уменьшите его, осторожно).

Устранение неполадок

«RepairDesk API returned 401 Unauthorized» / «Unauthorized» в ответе Ваш API-ключ неверен, был отозван или не был подхвачен. Перепроверьте ключ в Settings → API в RepairDesk и убедитесь, что он правильно указан в конфигурации вашего MCP-клиента (без лишних пробелов, не всё ещё YOUR_REPAIRDESK_API_KEY_HERE). Полностью перезапустите ваш AI-клиент после любого изменения конфигурации — большинство не перезагружает MCP-конфиг на лету.

Запросы падают сразу / выглядят как блокировка, а не ошибка аутентификации Cloudflare от RepairDesk блокирует запросы с пустым или похожим на стандартный User-Agent. Не устанавливайте REPAIRDESK_USER_AGENT в пустую строку.

«RepairDesk API rate limit hit twice in a row (429)» Вы делаете запросы быстрее, чем позволяет ваш ключ, даже после встроенной повторной попытки. Увеличьте REPAIRDESK_MIN_INTERVAL_MS (попробуйте 1000) в вашей конфигурации.

«Ticket T-XXXXX not found — could not resolve to internal ID» Проверьте, что ID заказа корректен и существует в этом магазине RepairDesk. Если у вас есть внутренний числовой ID, он тоже подойдёт — передайте его напрямую.

«RepairDesk API request timed out after 15000ms» Обычно это проблема сети/брандмауэра при доступе к api.repairdesk.co, или REPAIRDESK_BASE_URL указан неверно. Проверьте, что вы можете достучаться до этого хоста с того места, где запущен сервер.

Ваш AI-ассистент вообще не видит инструмент

• Убедитесь, что путь в args абсолютный, а не относительный, и действительно указывает на server.mjs.

• Убедитесь, что вы выполнили npm install в этой папке (отсутствие node_modules = сервер не может запуститься).

• Полностью выйдите и перезапустите ваш AI-клиент — не просто закройте окно чата.

• Запустите node /full/path/to/server.mjs напрямую в терминале — если возникнет ошибка, вы увидите реальную проблему, а не общее «инструмент недоступен» от клиента.

node setup.mjs сообщает, что не может найти claude/codex в вашем PATH Это нормально — он переключается на вывод блока конфигурации, который вы можете вставить вручную (см. Ручная настройка). Это просто означает, что соответствующий CLI не установлен или не находится в вашем PATH; это не значит, что сам MCP-сервер сломан.

Всё ещё не получается? Откройте issue в этом репозитории с сообщением об ошибке (сначала закрасьте свой API-ключ, если он где-то появляется в выводе).

FAQ

Это официальный инструмент RepairDesk? Нет. Он создан и поддерживается независимо, используя публичный API RepairDesk. Используйте на своё усмотрение.

Стоит ли это денег для запуска? Нет — он просто совершает те же вызовы API, которые уже разрешены вашим тарифом RepairDesk. Никакой дополнительной платы от этого проекта нет. (Подписка на вашего AI-ассистента, например Claude, — это отдельная история и не связана с этим сервером.)

Могу ли я использовать это с чем-то, кроме Claude? Да — MCP — это открытый стандарт. setup.mjs настраивает Claude Code, Claude Desktop, Codex CLI и OpenCode напрямую; всё остальное, что говорит на MCP через stdio (Cursor, Windsurf и т.д.), также может использовать этот сервер через ручную конфигурацию в Ручная настройка.

Могу ли я запустить это для нескольких магазинов RepairDesk? Да — зарегистрируйте его несколько раз под разными именами (например, repairdesk-store1, repairdesk-store2) в вашем MCP-клиенте, каждый со своим REPAIRDESK_API_KEY.

Может ли мой AI-ассистент случайно отправить email/SMS моим клиентам? Только repairdesk_tickets_write может это вызвать, и только через изменение статуса — которое всегда требует явного confirmed: true и помечается в описании инструмента, когда целевой статус является одним из уведомляющих статусов RepairDesk. Это не произойдёт молча.

Безопасность

Ваш REPAIRDESK_API_KEY даёт полный доступ на чтение/запись к данным клиентов и финансовым данным вашего магазина. Храните его в конфигурации окружения вашего MCP-клиента, никогда не в коммитируемом файле. config.json и .env здесь в gitignore именно по этой причине — используйте их локально, если предпочитаете файл переменным окружения, но не коммитьте заполненную копию. Нашли проблему безопасности? Пожалуйста, откройте issue (или приватный отчёт, если ваш хостинг это поддерживает), а не публичный PR с деталями эксплойта.

Лицензия

MIT — см. LICENSE. Предоставляется как есть, без гарантий — вы несёте ответственность за то, как вы используете его со своей учётной записью RepairDesk.