mcp-altegio

MCP-сервер для Altegio API — управление записями, клиентами, услугами, сотрудниками и расписанием через AI-ассистента.

Возможности

• 18 MCP-инструментов — записи, клиенты, услуги, сотрудники, расписание, финансы
• CRUD-операции — полный цикл создания, чтения, обновления и удаления записей и клиентов
• Умный поиск — автоопределение типа запроса (телефон, email, имя)
• Docker-образ — multi-stage build на Alpine (~184MB), готов к продакшну
• 141 тест — unit, API-клиент, интеграционные MCP-тесты
• Dual transport — stdio (локально) и Streamable HTTP (удалённо, Smithery, облако)
• stdio-транспорт — работает с Claude Desktop, Claude Code, Cursor, VS Code Copilot

Инструменты

18 инструментов, разбитые по категориям:

📅 Записи

Инструмент	Описание
get_records	Записи за период с фильтрами по мастеру/клиенту
get_records_by_client	Все записи конкретного клиента
get_records_by_visit	Поиск записей по api_id (привязка к внешней системе)
create_record	Создать запись с полной настройкой параметров
book_service	Быстрое бронирование с привязкой к визиту
update_record	Изменить существующую запись
delete_record	Удалить запись

👥 Клиенты

Инструмент	Описание
search_clients	Поиск по имени, телефону или email (авто-определение)
get_client	Карточка клиента по ID
create_client	Создать нового клиента
update_client	Редактировать данные клиента

🛎️ Услуги и сотрудники

Инструмент	Описание
get_services	Каталог услуг (фильтр по мастеру/категории)
get_service_categories	Категории услуг
get_staff	Список сотрудников (по умолчанию без уволенных)
get_staff_member	Детали конкретного сотрудника

📊 Расписание и финансы

Инструмент	Описание
get_available_times	Свободные слоты на дату
get_available_dates	Рабочие дни мастера
get_transactions	Финансовые транзакции за период

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

Требования

• Bun >= 1.0 или Docker
• Партнёрский и пользовательский токены Altegio API

Установка

<details> <summary><b>Bun (локально)</b></summary>

git clone https://github.com/moro3k/mcp-altegio.git
cd mcp-altegio
bun install

</details>

<details> <summary><b>Docker</b></summary>

git clone https://github.com/moro3k/mcp-altegio.git
cd mcp-altegio
docker build -t mcp-altegio .

</details>

Конфигурация

Переменная	Обязательна	Описание
ALTEGIO_TOKEN	Да	Партнёрский токен API
ALTEGIO_USER_TOKEN	Да	Пользовательский токен
ALTEGIO_COMPANY_ID	Да	ID компании

<details> <summary><b>Где взять токены?</b></summary>

• ALTEGIO_TOKEN — партнёрский токен. Получается в кабинете разработчика после регистрации партнёрского аккаунта
• ALTEGIO_USER_TOKEN — пользовательский токен. Получается через авторизацию к API (POST /auth) с логином и паролем аккаунта Altegio
• ALTEGIO_COMPANY_ID — ID компании. Виден в URL панели управления: app.alteg.io/company/XXXXXX/...

</details>

Подключение

Claude Desktop

Добавьте в конфигурацию (~/Library/Application Support/Claude/claude_desktop_config.json на macOS или %APPDATA%\Claude\claude_desktop_config.json на Windows):

<details> <summary><b>Bun</b></summary>

{
  "mcpServers": {
    "altegio": {
      "command": "bun",
      "args": ["run", "/полный/путь/к/mcp-altegio/src/index.ts"],
      "env": {
        "ALTEGIO_TOKEN": "ваш_токен",
        "ALTEGIO_USER_TOKEN": "ваш_токен",
        "ALTEGIO_COMPANY_ID": "12345"
      }
    }
  }
}

</details>

<details> <summary><b>Docker</b></summary>

{
  "mcpServers": {
    "altegio": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "ALTEGIO_TOKEN",
        "-e", "ALTEGIO_USER_TOKEN",
        "-e", "ALTEGIO_COMPANY_ID",
        "mcp-altegio"],
      "env": {
        "ALTEGIO_TOKEN": "ваш_токен",
        "ALTEGIO_USER_TOKEN": "ваш_токен",
        "ALTEGIO_COMPANY_ID": "12345"
      }
    }
  }
}

Флаг -i обязателен — MCP работает через stdio.

</details>

Claude Code

Добавьте в .mcp.json в корне проекта:

{
  "mcpServers": {
    "altegio": {
      "command": "bun",
      "args": ["run", "/полный/путь/к/mcp-altegio/src/index.ts"],
      "cwd": "/полный/путь/к/mcp-altegio"
    }
  }
}

Cursor

Settings → MCP Servers → Add new server:

{
  "altegio": {
    "command": "bun",
    "args": ["run", "/полный/путь/к/mcp-altegio/src/index.ts"],
    "cwd": "/полный/путь/к/mcp-altegio"
  }
}

Bun автоматически подтягивает .env из директории cwd. Можно использовать .env файл вместо передачи переменных напрямую.

HTTP-транспорт (Streamable HTTP)

Для облачных деплоев и Smithery используйте HTTP-режим:

# Локально
bun run start:http

# Docker
docker run --rm -p 3000:3000 \
  -e ALTEGIO_TOKEN=ваш_токен \
  -e ALTEGIO_USER_TOKEN=ваш_токен \
  -e ALTEGIO_COMPANY_ID=12345 \
  mcp-altegio bun run src/http.ts

Сервер слушает на порту 3000 (переопределяется через PORT). Endpoint: POST /mcp.

Подключение через URL:

{
  "mcpServers": {
    "altegio": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Примеры

> Покажи все записи на сегодня
  → get_records

> Найди клиента по телефону +66812345678
  → search_clients → get_records_by_client

> Запиши Анну на тайский массаж к Kai на завтра в 14:00
  → get_services → get_available_times → create_record

> Покажи свободные слоты у Wanida на эту неделю
  → get_available_dates → get_available_times

Разработка

bun install     # Установить зависимости
bun run start   # Запустить сервер
bun test        # Запустить тесты (141 тест)

Структура проекта

src/
  server.ts     # Фабрика MCP-сервера, регистрация 18 инструментов
  index.ts      # Точка входа stdio
  http.ts       # Точка входа HTTP (Streamable HTTP)
  api.ts        # HTTP-клиент (авторизация, подстановка company_id)
  helpers.ts    # Вспомогательные функции (поиск, фильтры)
tests/
  helpers.test.ts   # Unit-тесты хелперов (39)
  api.test.ts       # Тесты HTTP-клиента (37)
  server.test.ts    # Интеграционные MCP-тесты (55)

Тесты

141 тест с покрытием всех инструментов:

• Unit — автоопределение типа поиска, фильтрация сотрудников и записей
• API-клиент — HTTP-методы, авторизация, query-параметры, обработка ошибок
• Интеграционные — регистрация инструментов, схемы, вызов через MCP SDK клиент

Стек

Компонент	Технология
Runtime	Bun 1.x
Язык	TypeScript 5.7
SDK	@modelcontextprotocol/sdk 1.26
Валидация	Zod v4
Тесты	Bun Test
Контейнер	Docker (Alpine)
Transport	stdio, Streamable HTTP

Особенности Altegio API

Параметр	Описание
api_id	Только number. Строки игнорируются, записывается 0
save_if_busy	true при программном создании записей
seance_length	Длительность в секундах (3600 = 1 час)
attendance	-1 отменён · 0 ожидается · 1 подтверждён · 2 пришёл
fired	0 активный · 1 уволенный

Участие

PR приветствуются. Форкните, улучшите, откройте PR.

Идеи:

• Групповые события (activities)
• Webhook-уведомления
• Кеширование запросов
• Работа с несколькими компаниями
• Складской учёт и товары

Лицензия

MIT