MCP Altegio

1# mcp-altegio
2 
3MCP-сервер для [Altegio API](https://developer.alteg.io/api) — управление записями, клиентами, услугами, сотрудниками и расписанием через AI-ассистента.
4 
5[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
6[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
7[![Bun](https://img.shields.io/badge/Bun-1.x-f9f1e1?logo=bun&logoColor=black)](https://bun.sh)
8[![Docker](https://img.shields.io/badge/Docker-ready-2496ed?logo=docker&logoColor=white)](Dockerfile)
9[![MCP SDK](https://img.shields.io/badge/MCP_SDK-1.26-green?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiI+PHRleHQgeD0iMCIgeT0iMTMiIGZvbnQtc2l6ZT0iMTQiPuKamjwvdGV4dD48L3N2Zz4=)](https://github.com/modelcontextprotocol/typescript-sdk)
10[![Tests](https://img.shields.io/badge/Tests-141_passing-brightgreen)](tests/)
11 
12## Возможности
13 
14- **18 MCP-инструментов** — записи, клиенты, услуги, сотрудники, расписание, финансы
15- **CRUD-операции** — полный цикл создания, чтения, обновления и удаления записей и клиентов
16- **Умный поиск** — автоопределение типа запроса (телефон, email, имя)
17- **Docker-образ** — multi-stage build на Alpine (~184MB), готов к продакшну
18- **141 тест** — unit, API-клиент, интеграционные MCP-тесты
19- **Dual transport** — stdio (локально) и Streamable HTTP (удалённо, Smithery, облако)
20- **stdio-транспорт** — работает с Claude Desktop, Claude Code, Cursor, VS Code Copilot
21 
22## Инструменты
23 
24**18 инструментов**, разбитые по категориям:
25 
26### 📅 Записи
27 
28| Инструмент | Описание |
29|------------|----------|
30| `get_records` | Записи за период с фильтрами по мастеру/клиенту |
31| `get_records_by_client` | Все записи конкретного клиента |
32| `get_records_by_visit` | Поиск записей по `api_id` (привязка к внешней системе) |
33| `create_record` | Создать запись с полной настройкой параметров |
34| `book_service` | Быстрое бронирование с привязкой к визиту |
35| `update_record` | Изменить существующую запись |
36| `delete_record` | Удалить запись |
37 
38### 👥 Клиенты
39 
40| Инструмент | Описание |
41|------------|----------|
42| `search_clients` | Поиск по имени, телефону или email (авто-определение) |
43| `get_client` | Карточка клиента по ID |
44| `create_client` | Создать нового клиента |
45| `update_client` | Редактировать данные клиента |
46 
47### 🛎️ Услуги и сотрудники
48 
49| Инструмент | Описание |
50|------------|----------|
51| `get_services` | Каталог услуг (фильтр по мастеру/категории) |
52| `get_service_categories` | Категории услуг |
53| `get_staff` | Список сотрудников (по умолчанию без уволенных) |
54| `get_staff_member` | Детали конкретного сотрудника |
55 
56### 📊 Расписание и финансы
57 
58| Инструмент | Описание |
59|------------|----------|
60| `get_available_times` | Свободные слоты на дату |
61| `get_available_dates` | Рабочие дни мастера |
62| `get_transactions` | Финансовые транзакции за период |
63 
64## Быстрый старт
65 
66### Требования
67 
68- [Bun](https://bun.sh/) >= 1.0 **или** [Docker](https://www.docker.com/)
69- Партнёрский и пользовательский токены [Altegio API](https://developer.alteg.io)
70 
71### Установка
72 
73<details>
74<summary><b>Bun (локально)</b></summary>
75 
76```bash
77git clone https://github.com/moro3k/mcp-altegio.git
78cd mcp-altegio
79bun install
80```
81 
82</details>
83 
84<details>
85<summary><b>Docker</b></summary>
86 
87```bash
88git clone https://github.com/moro3k/mcp-altegio.git
89cd mcp-altegio
90docker build -t mcp-altegio .
91```
92 
93</details>
94 
95### Конфигурация
96 
97| Переменная | Обязательна | Описание |
98|------------|:-----------:|----------|
99| `ALTEGIO_TOKEN` | Да | Партнёрский токен API |
100| `ALTEGIO_USER_TOKEN` | Да | Пользовательский токен |
101| `ALTEGIO_COMPANY_ID` | Да | ID компании |
102 
103<details>
104<summary><b>Где взять токены?</b></summary>
105 
106- **ALTEGIO_TOKEN** — партнёрский токен. Получается в [кабинете разработчика](https://developer.alteg.io) после регистрации партнёрского аккаунта
107- **ALTEGIO_USER_TOKEN** — пользовательский токен. Получается через авторизацию к API (`POST /auth`) с логином и паролем аккаунта Altegio
108- **ALTEGIO_COMPANY_ID** — ID компании. Виден в URL панели управления: `app.alteg.io/company/XXXXXX/...`
109 
110</details>
111 
112## Подключение
113 
114### Claude Desktop
115 
116Добавьте в конфигурацию (`~/Library/Application Support/Claude/claude_desktop_config.json` на macOS или `%APPDATA%\Claude\claude_desktop_config.json` на Windows):
117 
118<details>
119<summary><b>Bun</b></summary>
120 
121```json
122{
123  "mcpServers": {
124    "altegio": {
125      "command": "bun",
126      "args": ["run", "/полный/путь/к/mcp-altegio/src/index.ts"],
127      "env": {
128        "ALTEGIO_TOKEN": "ваш_токен",
129        "ALTEGIO_USER_TOKEN": "ваш_токен",
130        "ALTEGIO_COMPANY_ID": "12345"
131      }
132    }
133  }
134}
135```
136 
137</details>
138 
139<details>
140<summary><b>Docker</b></summary>
141 
142```json
143{
144  "mcpServers": {
145    "altegio": {
146      "command": "docker",
147      "args": ["run", "-i", "--rm",
148        "-e", "ALTEGIO_TOKEN",
149        "-e", "ALTEGIO_USER_TOKEN",
150        "-e", "ALTEGIO_COMPANY_ID",
151        "mcp-altegio"],
152      "env": {
153        "ALTEGIO_TOKEN": "ваш_токен",
154        "ALTEGIO_USER_TOKEN": "ваш_токен",
155        "ALTEGIO_COMPANY_ID": "12345"
156      }
157    }
158  }
159}
160```
161 
162> Флаг `-i` обязателен — MCP работает через stdio.
163 
164</details>
165 
166### Claude Code
167 
168Добавьте в `.mcp.json` в корне проекта:
169 
170```json
171{
172  "mcpServers": {
173    "altegio": {
174      "command": "bun",
175      "args": ["run", "/полный/путь/к/mcp-altegio/src/index.ts"],
176      "cwd": "/полный/путь/к/mcp-altegio"
177    }
178  }
179}
180```
181 
182### Cursor
183 
184Settings → MCP Servers → Add new server:
185 
186```json
187{
188  "altegio": {
189    "command": "bun",
190    "args": ["run", "/полный/путь/к/mcp-altegio/src/index.ts"],
191    "cwd": "/полный/путь/к/mcp-altegio"
192  }
193}
194```
195 
196> Bun автоматически подтягивает `.env` из директории `cwd`. Можно использовать `.env` файл вместо передачи переменных напрямую.
197 
198### HTTP-транспорт (Streamable HTTP)
199 
200Для облачных деплоев и Smithery используйте HTTP-режим:
201 
202```bash
203# Локально
204bun run start:http
205 
206# Docker
207docker run --rm -p 3000:3000 \
208  -e ALTEGIO_TOKEN=ваш_токен \
209  -e ALTEGIO_USER_TOKEN=ваш_токен \
210  -e ALTEGIO_COMPANY_ID=12345 \
211  mcp-altegio bun run src/http.ts
212```
213 
214Сервер слушает на порту `3000` (переопределяется через `PORT`). Endpoint: `POST /mcp`.
215 
216Подключение через URL:
217 
218```json
219{
220  "mcpServers": {
221    "altegio": {
222      "url": "http://localhost:3000/mcp"
223    }
224  }
225}
226```
227 
228## Примеры
229 
230```
231> Покажи все записи на сегодня
232  → get_records
233 
234> Найди клиента по телефону +66812345678
235  → search_clients → get_records_by_client
236 
237> Запиши Анну на тайский массаж к Kai на завтра в 14:00
238  → get_services → get_available_times → create_record
239 
240> Покажи свободные слоты у Wanida на эту неделю
241  → get_available_dates → get_available_times
242```
243 
244## Разработка
245 
246```bash
247bun install     # Установить зависимости
248bun run start   # Запустить сервер
249bun test        # Запустить тесты (141 тест)
250```
251 
252### Структура проекта
253 
254```
255src/
256  server.ts     # Фабрика MCP-сервера, регистрация 18 инструментов
257  index.ts      # Точка входа stdio
258  http.ts       # Точка входа HTTP (Streamable HTTP)
259  api.ts        # HTTP-клиент (авторизация, подстановка company_id)
260  helpers.ts    # Вспомогательные функции (поиск, фильтры)
261tests/
262  helpers.test.ts   # Unit-тесты хелперов (39)
263  api.test.ts       # Тесты HTTP-клиента (37)
264  server.test.ts    # Интеграционные MCP-тесты (55)
265```
266 
267### Тесты
268 
269141 тест с покрытием всех инструментов:
270 
271- **Unit** — автоопределение типа поиска, фильтрация сотрудников и записей
272- **API-клиент** — HTTP-методы, авторизация, query-параметры, обработка ошибок
273- **Интеграционные** — регистрация инструментов, схемы, вызов через MCP SDK клиент
274 
275## Стек
276 
277| Компонент | Технология |
278|-----------|-----------|
279| Runtime | [Bun](https://bun.sh/) 1.x |
280| Язык | TypeScript 5.7 |
281| SDK | [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) 1.26 |
282| Валидация | Zod v4 |
283| Тесты | Bun Test |
284| Контейнер | Docker (Alpine) |
285| Transport | stdio, Streamable HTTP |
286 
287## Особенности Altegio API
288 
289| Параметр | Описание |
290|----------|----------|
291| `api_id` | Только `number`. Строки игнорируются, записывается `0` |
292| `save_if_busy` | `true` при программном создании записей |
293| `seance_length` | Длительность в **секундах** (3600 = 1 час) |
294| `attendance` | `-1` отменён · `0` ожидается · `1` подтверждён · `2` пришёл |
295| `fired` | `0` активный · `1` уволенный |
296 
297## Участие
298 
299PR приветствуются. Форкните, улучшите, откройте PR.
300 
301Идеи:
302- Групповые события (activities)
303- Webhook-уведомления
304- Кеширование запросов
305- Работа с несколькими компаниями
306- Складской учёт и товары
307 
308## Лицензия
309 
310[MIT](LICENSE)
311