mcp-altegio

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

License: MIT TypeScript Bun Docker MCP SDK Tests

Возможности

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

Установка

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

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

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

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

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

Подключение

Claude Desktop

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

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

{
  "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.

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

mcp-altegio

mcp-altegio

Возможности

Инструменты

📅 Записи

👥 Клиенты

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

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

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

Требования

Установка

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

Подключение

Claude Desktop

Claude Code

Cursor

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

Примеры

Разработка

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

Тесты

Стек

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

Участие

Лицензия

Resources

Latest Blog Posts

MCP directory API