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 инструментов, разбитые по категориям:

📅 Записи

👥 Клиенты

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

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

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

Требования

• 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 .

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

Подключение

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"
      }
    }
  }
}

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 клиент

Стек

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

Участие

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

Идеи:

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

Лицензия

MIT