AI-асистент (MCP Server)

@placraftic/mcp-server - це офіційна реалізація протоколу Model Context Protocol (MCP) для операційної системи 3D-друку Placraftic. Сервер дозволяє підключати штучний інтелект (Claude Desktop, Cursor IDE, Zed, Claude Code CLI) безпосередньо до робочих процесів вашої студії.

Завдяки MCP ваш AI-асистент отримує прямий доступ до 6 живих ресурсів студії, 39 спеціалізованих інструментів та 4 готових робочих промптів.

Для роботи з MCP-сервером потрібен ключ API студії з префіксом pk_live_, створений у розділі Ключі API. Доступ до API надається на тарифах Pro та Enterprise.

Швидкий старт#

1. Claude Desktop#

Відкрийте файл налаштувань Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Додайте конфігурацію:

{
  "mcpServers": {
    "placraftic": {
      "command": "npx",
      "args": ["-y", "@placraftic/mcp-server"],
      "env": {
        "PLACRAFTIC_API_KEY": "pk_live_YOUR_KEY_HERE"
      }
    }
  }
}

2. Cursor IDE#

Створіть або оновіть файл .cursor/mcp.json у корені вашого проекту або у глобальних налаштуваннях Cursor:

{
  "mcpServers": {
    "placraftic": {
      "command": "npx",
      "args": ["-y", "@placraftic/mcp-server"],
      "env": {
        "PLACRAFTIC_API_KEY": "pk_live_YOUR_KEY_HERE"
      }
    }
  }
}

3. Claude Code CLI#

Підключіть сервер однією командою в терміналі:

claude mcp add placraftic -e PLACRAFTIC_API_KEY="pk_live_YOUR_KEY_HERE" -- npx -y @placraftic/mcp-server

4. Zed Editor#

Додайте блок у settings.json вашого редактора Zed:

{
  "experimental": {
    "model_context_protocol": {
      "servers": {
        "placraftic": {
          "command": "npx",
          "args": ["-y", "@placraftic/mcp-server"],
          "env": {
            "PLACRAFTIC_API_KEY": "pk_live_YOUR_KEY_HERE"
          }
        }
      }
    }
  }
}

Змінні середовища#

Змінна	Опис	За замовчуванням
`PLACRAFTIC_API_KEY`	Токен студії з розділу `/api-keys` (обов'язковий для авторизованих дій)	(порожньо)
`PLACRAFTIC_BASE_URL`	Базовий URL для REST API Placraftic	`https://api.placraftic.com/v1`

Ресурси MCP#

Клієнти MCP автоматично підтягують живі ресурси студії в контекст діалогу:

URI ресурсу	Опис
`placraftic://studio/profile`	Профіль студії, валюта, ставка нормо-години та базові ціноутворювальні коефіцієнти
`placraftic://catalog/materials`	Склад та каталог матеріалів (філаменти, смоли), залишки та собівартість за кг
`placraftic://catalog/printers`	Флот принтерів студії, моделі, робочі зони та стан технічного обслуговування
`placraftic://catalog/finishings`	Послуги постобробки (фарбування, хімполірування, зняття підтримок)
`placraftic://catalog/qualities`	Профілі слайсингу: висота шару, сопла, швидкості та режими заповнення
`placraftic://delivery/settings`	Відправне відділення Нової Пошти, адреса самовивозу та активні методи доставки

Вбудовані робочі промпти#

Сервер реєструє 4 вбудованих робочих сценарії, доступні у вигляді слеш-команд:

daily_production_standup (Ранковий виробничий стендап):
- Аналізує замовлення у станах printing та pending.
- Перевіряє завантаження флоту принтерів.
- Групує деталі за матеріалом та якістю для мінімізації заміни котушок.
- Формує структурований звіт українською мовою з пріоритетами на робочий день.
pack_and_ship_order (Пакування та відправка замовлення):
- Приймає orderId.
- Перевіряє готовність деталей та відділення отримувача.
- Запитує підтвердження ваги та оголошеної вартості у оператора.
- Генерує накладну Нової Пошти (ТТН), посилання на друк стікера та переводить статус замовлення у shipped.
quote_and_consult (Технічна консультація та прорахунок):
- Приймає локальний шлях до файлу filePath та вимоги до деталі requirements.
- Рекомендує оптимальний матеріал (PLA, PETG, ABS, Resin) та висоту шару.
- Розраховує собівартість та формує детальну комерційну пропозицію для клієнта.
customer_support_inquiry (Підтримка клієнтів):
- Приймає повідомлення клієнта customerQuery та контактні дані.
- Знаходить картку клієнта, активні замовлення та поточний статус посилки у Новій Пошті.
- Складає ввічливу відповідь українською мовою з можливістю миттєвої відправки в Telegram чи Instagram.

Доступні інструменти (Tools)#

Сервер містить 39 інструментів, згрупованих за категоріями:

1. Система та ідентифікація#

ping: Перевірка з'єднання та затримки API.
get_studio_info: Дані поточної студії, валюта та активний тариф.

2. Каталог та флот принтерів#

list_materials / get_material: Склад філаментів, залишки та ціни.
list_technologies: Довідник технологій друку (для technologyId при створенні принтера).
list_printers / get_printer: Моніторинг принтерів, черги друку та обслуговування.
create_printer / update_printer / delete_printer: Реєстрація, редагування та видалення принтерів фліту.
list_qualities / get_quality: Профілі якості та параметри шарів.
list_finishings / get_finishing: Каталог операцій постобробки.
list_products / get_product: Каталог серійних виробів студії.

3. Замовлення та канбан#

list_orders: Фільтрація замовлень за статусом канбану (pending, printing, ready, shipped, completed).
get_order_details: Повний маніфест замовлення з файлами та даними доставки.
update_order_status: Перехід між виробничими етапами із записом подій у таймлайн.
update_order: Зміна суми замовлення або службових приміток.
cancel_order: Скасування замовлення з обов'язковою фіксацією причини.

4. Логістика та Нова Пошта#

create_nova_poshta_waybill: Створення електронної накладної (ТТН).
print_waybill: Отримання PDF-посилання на друк стікера маркування.
track_shipment: Отримання реального статусу доставки посилки.
get_delivery_settings: Перегляд налаштувань складу відправника.

5. Клієнтська база та CRM#

list_customers: Пошук клієнтів за телефоном, поштою чи ім'ям.
get_customer_profile: Повна історія замовлень, улюблені матеріали та LTV клієнта.

6. Слайсинг, розрахунок вартості та створення замовлень#

calculate_quote: Завантаження локального 3D-файлу та автоматичний розрахунок вартості друку з урахуванням часу та матеріалу.
submit_slicing_job: Відправка 3D-файлу на фоновий слайсинг.
get_slicing_status: Отримання статусу слайсингу, ваги нитки та часу друку за jobId.
create_order: Оформлення повноцінного замовлення безпосередньо з діалогу з AI.

7. Підтримка клієнтів та омніканальний Inbox#

list_inbox_threads: Список звернень клієнтів з Telegram, Instagram, пошти та кабінету.
get_conversation_messages: Хронологія повідомлень та вкладень у діалозі.
send_inbox_reply: Відправка прямої відповіді в Telegram або Instagram.
list_canned_responses / create_canned_response: Готові швидкі шаблони відповідей.

8. Відновлення покинутих кошиків#

list_abandoned_quotes: Список незавершених прорахунків із контактами та прямими посиланнями.
review_abandoned_quote: Фіксація опрацювання ліда для уникнення дублювання дзвінків.

9. Фінансова та виробнича аналітика#

get_studio_stats: Зведений звіт за період (today, this_week, this_month, last_30_days) - оборот, середня вартість замовлення, навантаження флоту та топ матеріалів.

Безпека та захист даних#

Ізоляція студій: Усі операції суворо обмежені студією вашого API-ключа. Доступ до чужих даних неможливий на рівні архітектури бекенду.
Підтвердження чутливих дій: Дії зі скасування замовлень або створення накладних супроводжуються запитом підтвердження від користувача.
Захист персональних даних: Телефонні номери та адреси використовуються виключно для оформлення відправлень та комунікації.