# 04 — Интеграции и аналитика

Раздел базы знаний ITG

# 03 — Интеграции и автоматизация

# Интеграции и автоматизация ITG

## MCP
- **ITG BookStack MCP:** инструменты поиска, чтения, создания и обновления страниц, получения списков книг и полок, создания книг.
- **ITG MODX MCP:** управление содержимым сайта.
- **Яндекс Директ и аналитика:** интеграции для рекламных и аналитических задач.

## n8n
Направления автоматизации: заявки с сайта, создание/обновление записей CRM, экспресс-аудит сайтов, отчёты, уведомления.

## Карточка интеграции
- Системы-участники и схема потока данных
- Событие запуска и API-методы
- Поля и преобразования
- Авторизация (только способ, без секретов)
- Повторные попытки и обработка ошибок
- Логи, алерты и тестовые сценарии
- Ответственный и дата последней проверки

## Правило
Тестовый трафик и тестовые заявки маркировать отдельно от реальных.

# 08 — MCP и ChatGPT

# MCP и ChatGPT — ITG

## Назначение
MCP предоставляет ChatGPT контролируемый доступ к рабочим системам ITG.

## ITG BookStack MCP
- Документация: https://wiki.karpiev.ru
- MCP endpoint: https://mcp-wiki.karpiev.ru/mcp
- Проект на ZimaOS: `/DATA/AppData/bookstack-mcp`
- Docker-контейнер: `bookstack-mcp`
- Локальный проброс: `127.0.0.1:18765` → порт 8000 контейнера.
- Авторизация: GitHub OAuth через FastMCP (требуется периодическая проверка ограничений доступа).
- Название подключения: **ITG BookStack MCP**.

## Проверенные операции
- Поиск по BookStack.
- Получение списка книг и полок.
- Чтение страницы.
- Создание и обновление страницы.
- Создание книги.

## Проверка доступности
```bash
curl -sS -o /dev/null -w '%{http_code}\n' https://mcp-wiki.karpiev.ru/mcp
```
Без авторизации `401` ожидаем, но **сам по себе этот код не доказывает корректность OAuth-потока или ограничений пользователей**.

## Безопасность
- Не публиковать MCP без надёжной аутентификации.
- Проверять, что авторизация ограничивает доступ только нужным пользователям.
- Хранить Client Secret и BookStack API-токены вне документации.
- Разделять права чтения и изменения по возможности.
- После обновлений проверять `tools/list` и реальные операции.

## Рекомендации
- Добавить инструменты управления полками и главами.
- Вести журнал изменения схемы MCP.
- Документировать политику доступа и отзыв токенов.

**Статус:** инструменты BookStack MCP доступны в ChatGPT; полный аудит политики OAuth ещё требуется.

# 09 — n8n и автоматизация

# n8n — автоматизация ITG

## Назначение
Связать сайт, CRM, аналитику, электронную почту и уведомления в воспроизводимые процессы.

## Приоритетные сценарии
### 1. Заявка с сайта → Twenty CRM
- Получить заявку из формы.
- Проверить обязательные поля.
- Найти существующую компанию/контакт.
- Создать или обновить запись в CRM.
- Создать задачу follow-up.
- Записать идентификатор события и статус обработки.

### 2. Экспресс-аудит сайта
- Получить URL и контактные данные.
- Проверить валидность URL и разрешённые адреса.
- Запустить разрешённые проверки производительности и SEO.
- Сформировать отчёт.
- Отправить клиенту и сохранить ссылку в CRM.

### 3. Уведомления
- Ошибка автоматизации.
- Новая заявка.
- Просроченный follow-up.
- Изменение статуса интеграции.

## Стандарт workflow
- Уникальный ID события и идемпотентность.
- Таймауты, ретраи и обработка ошибок.
- Секреты только в credentials/хранилище секретов.
- Отдельные тестовые данные.
- Наблюдаемость: журнал выполнения и алерты.
- Явные критерии успешного завершения.

## Фактический инвентарь на 11.10.2026
Через n8n MCP доступно **15 workflow**, из них **3 активных**:
- `itgC8Digest20261007` — IT GROUP — Daily Follow-up digest.
- `itgC7901e7a356f6` — IT GROUP — Twenty opportunity events.
- `puOTAOvlbzAiH0ze` — ITG — BookStack health and quality gate.

Автоматизация аудита сайтов представлена отдельными **неактивными** ручными сценариями: intake (`acvtlYyojy35oxdg`), просмотр очереди (`BIPJOHreI2sCqGPb`), проверка URL (`TnGks4RmPM2KCkVA`), классификатор событий (`q2jEfj4lgS5lBSyy`). Их описания явно ограничивают сетевые вызовы и запись в CRM; полноценный производственный процесс экспресс-аудита этим не подтверждён. Активный контроль BookStack имел ошибку DNS при запуске по расписанию 11.10.2026; детали в [регламенте контроля качества](https://wiki.karpiev.ru/books/itg-baza-znanii/page/20-kontrol-kacestva-i-aktualizaciia).

## Дальнейшая работа
- Актуализировать инвентарь workflows при изменениях.
- Описать webhook-адреса и контракт входных данных без секретов.
- Настроить тестовые сценарии и оповещения.
- Связать статусы выполнения с CRM.

**Статус:** проектная документация, а не подтверждение фактического развёртывания каждого сценария.

# 10 — Веб-аналитика и реклама

# Веб-аналитика и реклама ITG

## Системы
Яндекс Метрика, Google Analytics 4, Яндекс Директ и Twenty CRM.

## Путь клиента
Рекламный переход → посещение сайта → заявка → сделка в CRM → оплата.

## Измерения
- Отправка формы и запрос бесплатного аудита.
- Нажатие на телефон и переход в мессенджер.
- Источник, кампания и UTM-метки.
- Лиды, продажи, расходы и стоимость привлечения.

## Качество данных
Отдельно маркировать тестовые обращения, исключать дубли событий, сопоставлять заявки сайта с CRM и проверять корректность целей.

## Регламент
До изменения рекламных кампаний проверять ограничения бюджета и статус публикации. Включение рекламы требует отдельного подтверждения.

*Названия событий и действующие настройки необходимо сверить с аналитическими системами.*

# 17 — BookStack MCP: эксплуатация

# ITG BookStack MCP — эксплуатационная инструкция

## Подтверждённые сведения
- Книга ITG: https://wiki.karpiev.ru/books/itg-baza-znanii
- Endpoint MCP: https://mcp-wiki.karpiev.ru/mcp
- Каталог: `/DATA/AppData/bookstack-mcp`
- Docker Compose, сервис `bookstack-mcp`.
- FastMCP, GitHub OAuth.

## Проверка конфигурации
```bash
cd /DATA/AppData/bookstack-mcp
sudo env DOCKER_CONFIG=/DATA/AppData/docker-cli-config docker compose ps
sudo env DOCKER_CONFIG=/DATA/AppData/docker-cli-config docker compose logs --tail 50
```

## Обновление кода
1. Сохранить копию `server.py` и Compose-файла.
2. Проверить синтаксис Python.
3. Пересобрать контейнер из существующего каталога.
4. Проверить доступность endpoint и авторизованный вызов списка инструментов.
5. В ChatGPT обновить подключение при изменении состава инструментов.

## Проверенные инструменты
- bookstack_search
- bookstack_books_list
- bookstack_shelves_list
- bookstack_page_get
- bookstack_page_create
- bookstack_page_update
- bookstack_book_create
- bookstack_chapter_create
- bookstack_page_move

## Доступные операции структуры
`bookstack_chapter_create` и `bookstack_page_move` доступны в подключении. Перенос ограничен страницами и главами книги ITG (ID 4); HomeLab (ID 2) не изменять. Доступность инструментов подтверждена 11.10.2026, настройка OAuth allowlist требует отдельной проверки.

## Безопасность
GitHub OAuth сам по себе не доказывает, что доступ ограничен нужным аккаунтом. Проверить allowlist и права BookStack API.

**Статус:** часть сведений подтверждена рабочими вызовами; настройки доступа требуют аудита.