# b24-mcp

Локальный MCP-сервер к Битрикс24. Даёт AI-агенту **свежие данные твоего портала** — календарь, задачи и обсуждения в них, чаты, проекты-коллабы, AI-разборы звонков, карточки людей.

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

## Зачем это, если агент и так умеет HTTP

Агент может ходить в REST сам. Но тогда:

- на каждый запрос он собирает URL, помнит имена методов и версии API, парсит ответ;
- токен проходит через его окружение на каждом вызове;
- ничто не мешает ему вызвать метод, меняющий портал.

Сервер убирает это: агент вызывает **бизнес-операцию** (`tasks_list`, `task_chat`), а транспорт, версии, пагинация и нормализация живут внутри. Наружу выставлены только чтение и только перечисленные операции — raw-REST не выставлен вообще.

## Что умеет (14 инструментов)

| Инструмент | Что делает |
|---|---|
| `whoami` | Кто владелец вебхука — быстрая проверка, что связь живая |
| `person_find` | Найти человека: должность, отдел, контакты, активен ли |
| `calendar_events` | События за окно: время, участники, кто организатор, встреча это или личный блок |
| `tasks_list` | Задачи человека в роли `responsible` / `originator` / `auditor` |
| `task_get` | Шапка задачи: описание, статус, дедлайн, есть ли чат |
| `task_chat` | Обсуждение внутри задачи — там суть, а не в полях |
| `task_result` | Результаты задачи: их нет в чате, там только системная строка без текста |
| `tasks_updates` | Что шевелится в своих задачах за окно + какие появились новые |
| `chat_read` | Прочитать диалог: групповой чат или личку |
| `projects_list` | Проекты-коллабы по свежести активности |
| `project_chats` | Из чего состоит проект: дочерние чаты |
| `project_read` | Обсуждение в чате проекта |
| `followups_list` | Звонки с готовым AI-разбором за окно |
| `followup_get` | Разбор звонка: тема, договорённости, action items, расшифровка |

Ответы нормализованы: списки приходят как `{items, count, limit}`, разметка вычищена, лимиты зажаты.

## Установка

Нужен Python 3.11+.

```bash
git clone <этот-репозиторий> b24-mcp && cd b24-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -e .
```

## Настройка

**1. Выпусти входящий вебхук на своём портале.** Раздел разработчика: *Приложения → Разработчикам → Другое → Входящий вебхук*.

Права (scope), которые использует сервер:

| Scope | Для чего |
|---|---|
| `user`, `department` | люди и оргструктура |
| `calendar` | события |
| `task`, `tasks_extended` | задачи |
| `im` | чаты: задач, личные, групповые, проектов |
| `call` | AI-разборы звонков (без него работает всё остальное) |

Меньше прав — меньше риск. Начни без `call`, добавишь, когда понадобятся звонки.

**2. Положи вебхук в `.env`:**

```bash
cp .env.example .env
chmod 600 .env          # сервер откажется читать файл, доступный другим
```

```ini
B24_WEBHOOK=https://<твой-портал>/rest/<число>/<токен>/
B24_USER_ID=<твой id>   # необязательно: определится сам через user.current
```

**3. Подключи к своему MCP-клиенту.** Пример для Claude Code (`~/.claude.json`):

```json
{
  "mcpServers": {
    "b24": {
      "command": "/абсолютный/путь/b24-mcp/.venv/bin/python",
      "args": ["-m", "b24_mcp.server"],
      "env": { "B24_MCP_ENV": "/абсолютный/путь/b24-mcp/.env" }
    }
  }
}
```

Перезапусти клиент и спроси агента: «проверь связь с порталом» — он вызовет `whoami`.

## Безопасность

- **Токен живёт в `.env` с правами `600`.** Сервер проверяет права при старте и отказывается работать, если файл читается другими.
- **Токен не попадает ни в ответы инструментов, ни в логи, ни в тексты ошибок.** Логируется имя операции и время, не URL.
- **Только чтение.** Клиент создаётся с запретом write-методов на уровне транспорта, а наружу выставлены лишь перечисленные операции. Даже ошибка в коде инструмента не создаст задачу и не отправит сообщение.
- **Честная граница:** это снимает класс «секрет случайно утёк в вывод команды», но не отбирает у агента шелл. Если у него есть доступ к файловой системе, он по-прежнему может прочитать `.env` — как и любой процесс под твоим пользователем.
- Видно только то, где владелец вебхука участник. Чужие приватные чаты и события сервер не достанет.
- Утёк токен — отзови вебхук на портале и выпусти новый; менять придётся только `.env`.

## Разработка

```bash
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest -q --asyncio-mode=auto
```

Тесты идут без сети. Они пинят список инструментов (новый не появится молча), барьер «только чтение», контракт нормализации и формы ответов портала — включая те, на которых легко промахнуться.

**Две ловушки контракта, стоившие отладки** (зафиксированы тестами):

- Расшифровка звонка лежит в поле `transcription` (не `transcript`), саммари приходит **сегментами** (`{segments: [{title, summary}]}`), договорённости и задачи — под ключами `agreement` / `actionItem`, а не `text`. Промах даёт молча пустой ответ, а не ошибку.
- Участник звонка идентифицируется полем `userId`, не `id`. Чтение `id` вернёт `None` — и участника не связать с человеком.

## Границы

Сервер намеренно не делает:

- **write-операции** — не создаёт задачи, не отправляет сообщения, не меняет портал;
- **тяжёлые прогоны** — сплошной прочёс всей переписки за месяц, выгрузку отчётов за квартал, резюмируемые обходы с чекпоинтами. Вызов инструмента живёт внутри одного обращения агента: там есть потолок времени и негде сохранить прогресс. Такие задачи решаются отдельным скриптом, а не MCP-инструментом.

## Лицензия

MIT.