Skip to main content
Glama

Коннектор VK Teams для ИИ-агентов

English

Бесплатный, с открытым кодом (Apache-2.0). Даёт ИИ-агенту работать в VK Teams или VK WorkSpace от имени одного человека: чаты, сообщения, люди, файлы, ссылки на звонки и боты.

ci License: Apache-2.0

Что это и зачем

У VK Teams два API. Bot API работает от имени бота: он не видит ваших чатов, не ищет по вашей истории и не пишет от вашего имени. Клиентский API, которым пользуются приложения VK Teams, всё это умеет. Но он не документирован, путь в нём зависит от версии сервера, а ошибки приходят с HTTP 200.

Мы проверили клиентский API на живом сервере, запрос за запросом, и построили поверх него MCP-сервер. Через MCP (Model Context Protocol) ИИ-агент вызывает инструменты.

Два принципа:

  • Агенту минимум контекста. 12 инструментов и около 4 200 токенов описаний по умолчанию (14 инструментов и около 4 900 токенов, если включить управление группами; токены посчитаны токенайзером o200k_base). Каждый инструмент отвечает на один вопрос человека.

  • Логику несут инструменты. Сервер сам находит чат и человека по имени, превращает @адрес в упоминание, выбирает нужный из четырёх методов истории и поиска, передаёт файлы через ссылки на несколько минут, мимо контекста модели. И отказывает в том, чего делать нельзя. Каждый отказ мы внесли в требования и закрыли тестом, который падает, если убрать проверку.

Сервер действует как один человек, с его учётной записью VK Teams, и не больше. Правила, по которым мы проверяем каждое изменение, лежат в манифесте.

Related MCP server: vk-mcp-ru

Как это выглядит

Агент подключает коннектор, открывается страница входа. Человек вводит сервер VK Teams, рабочую почту и код из письма. Код видит только эта страница, модель его не видит. Страница говорит на языке браузера: по-русски или по-английски.

Страница входа: сервер VK Teams, рабочая почта, кнопка «Получить код»

Что умеет

Инструмент

Вопрос человека

get_connection

Я подключён? Под кем, к какому серверу?

list_chats

Что нового? Где непрочитанное?

get_chat

Что это за чат, кто в нём?

update_chat

Отметить прочитанным, выключить звук, архивировать, следить за веткой, выйти.

list_messages

Что писали? Найди сообщение про X. Какие реакции и сколько?

save_draft → send_draft

Написать: сначала черновик, отправка только после «да». Упоминания, ответ цитатой, опрос, файлы, отправка по расписанию.

update_message

Исправить, удалить, закрепить, поставить реакцию, проголосовать, закрыть опрос, отменить отложенное.

find_people

Кто это? Какой у него адрес?

download_file

Скачай вложение.

save_call_link

Сделай ссылку на звонок или вебинар.

respond_to_bot

Запусти бота, нажми его кнопку.

save_chat, update_chat_members

Создать или изменить группу, управлять участниками (по умолчанию выключено).

Контракты всех инструментов: docs/requirements.md.

Чего не делает

  • Ничего не уходит людям без отдельного шага. Отправка двухшаговая: черновик, затем send_draft. Каждое действие, которое видят другие, требует user_confirmed: true. Сервер не видит, как человек соглашается: флаг ставит агент, поэтому MCP-клиент должен показывать такие вызовы человеку.

  • Нельзя заспамить. Один лимит на человека: 10 действий сразу, затем одно в 6 секунд. Не больше 20 человек на действие, включая упоминания.

  • Меняются только свои сообщения: правка и удаление проверяют автора.

  • Текст других людей приходит в метках с одноразовым кодом: модель видит, что это данные. Поддельную метку сервер обезвреживает. Данные кнопок бота модель не видит вовсе: кнопка показывается номером, а нажатие сервер собирает сам и отказывает, если бот успел поменять кнопку.

  • Файлы не проходят через модель. Вложение задаётся именем файла в текущей папке, путь не принимается. Команда загрузки запускает curl с --globoff, чтобы {a,b} не раскрылось в чужой файл.

  • Некоторых операций здесь нет совсем: смена профиля, статуса и ника, сброс сессий, жалобы, SMS, очистка истории, списки приватности.

Безопасность сервера

Правило

Как

Код входа не видит модель

Его вводят только на странице входа этого сервера

Сервер ничего не хранит

Сессия VK Teams лежит внутри токенов клиента, зашифрована AES-GCM и привязана к виду блока: без секрета её нельзя ни прочитать, ни подделать, а черновик нельзя выдать за токен

Страница входа не становится инструментом атаки

Адрес сервера — только https-имя настоящей инсталляции VK Teams. Сервер проверяет каждое соединение при открытии, поэтому по умолчанию никакое имя не ведёт во внутреннюю сеть. Исключение: VKTEAMS_MCP_ALLOW_PRIVATE_NETWORKS=1 для установки внутри сети компании, и тогда инсталляцию закрепляют в VKTEAMS_MCP_INSTALLATIONS. Письма с кодом ограничены по частоте

OAuth 2.1, без хранилища

Регистрация клиента, PKCE, токен доступа на час, обновление на 30 дней. Отличие от OAuth 2.1: refresh-токен не одноразовый, украденный работает до своего срока. Защита — отключение: оно закрывает сессию в VK Teams, и все токены с ней мертвы. Украденный refresh-токен продлевает сам себя: доступ живёт, пока жива сессия, и кончается только отключением. Если VK Teams в этот момент недоступен, отключение вернёт ошибку, и его нужно повторить: пока VK не подтвердил, токены живы. Код авторизации живёт 5 минут; реплика помнит использованные коды (до 10 000, до перезапуска), а повтор кода в остальных случаях требует ещё и секрета PKCE, который есть только у клиента

Логи без содержимого

Тест проходит весь сценарий переписки и падает, если в логах есть текст, адрес или aimsid

Как проверено

Проверка

Что доказывает

Объём

Юнит-тесты (pytest)

Каждый инструмент против фейка VK Teams, который отвечает так же, как отвечал живой сервер

больше 400

Карта отказов

Каждая строка «обязан отказать» ссылается на существующий тест

каждая строка

Мутации (scripts/mutation_check.py)

Каждое правило убирается по очереди, и какой-то тест обязан упасть

больше 50

Бюджет токенов (python -m vkteams_mcp.budget --check)

Каталог по умолчанию не выходит за лимит

каждый запуск CI

Фиксация интерфейса инструментов (tool-surface.lock.json)

Изменённый аргумент или аннотация видны в ревью

каждый запуск CI

Чистота (tests/unit/test_gates.py)

В текстовых файлах нет запрещённых имён (список хранится хешами), в документах нет настоящих id чатов

каждый запуск CI

Живая проверка

Все инструменты через OAuth на настоящем сервере VK Teams. Каждый дефект, найденный за три раунда QA, исправлен и закрыт тестом (сценарии и дефекты)

по требованию

На что мы опирались

Источники по убыванию доверия:

  1. Живой сервер. Мы сверили каждый запрос с настоящим VK Teams (API 139). Что сервер делает, описано в docs/live-findings.md. Например, fromMsgId в истории не включает само сообщение, а id сообщений больше 2^53, и JavaScript-клиент их округляет, если передать числом.

  2. Открытый код im-desktop (Apache-2.0, от VK). Десктопный клиент: подпись сессии, параметры групп, бессрочное выключение звука. Мы сверялись с ним как со справочником по форме запросов.

  3. Неофициальные описания API. Там, где они расходятся с живым сервером, прав сервер.

Справочник по клиентскому API с формулами подписи: CHEATSHEET.md.

Подключение

Сервер работает по Streamable HTTP с OAuth 2.1 (авторизация MCP: регистрация клиента, PKCE, обновление токенов). В Claude его добавляют как свой коннектор с адресом /mcp, в Claude Code так:

claude mcp add --transport http vkteams https://vkteams-mcp.example.org/mcp

Запуск

Готовый образ для linux/amd64 и linux/arm64 лежит в GitHub Container Registry, версии описаны в CHANGELOG.md и на странице релизов.

openssl rand -base64 48 > vkteams-mcp.secret   # один раз, одинаковый для всех реплик; новый секрет разлогинит всех
docker run -p 127.0.0.1:8000:8000 \
  -e VKTEAMS_MCP_PUBLIC_URL=https://vkteams-mcp.example.org \
  -e VKTEAMS_MCP_SECRET="$(cat vkteams-mcp.secret)" \
  ghcr.io/widmo-ru/vkteams-mcp:0.2.5

Собрать образ самому: docker build -t vkteams-mcp ..

Переменная

Значение

VKTEAMS_MCP_PUBLIC_URL

https-адрес, по которому клиенты видят сервер (обязательно)

VKTEAMS_MCP_SECRET

Не меньше 32 случайных символов: шифрует сессии и подписывает курсоры (обязательно, храните). Новый секрет отключает всех: при следующем входе браузер покажет страницу «Подключитесь заново»: в ИИ-приложении сбросить авторизацию коннектора и подключиться снова

VKTEAMS_MCP_INSTALLATIONS

Хосты VK Teams через запятую, которые обслуживает коннектор. С одним хостом страница входа спрашивает только почту

VKTEAMS_MCP_ALLOW_PRIVATE_NETWORKS

1, если сервер стоит внутри сети компании рядом с её VK Teams

VKTEAMS_MCP_AREAS

Какие области включить (по умолчанию все, кроме chat_admin)

VKTEAMS_MCP_TIMEZONE

Часовой пояс для времени в ответах и в send_at (по умолчанию Europe/Moscow)

PORT

Порт внутри контейнера (по умолчанию 8000)

VKTEAMS_MCP_DEV_ID

developer id VK Teams (по умолчанию публичный id десктопного клиента из открытого im-desktop)

Контейнер работает по HTTP на порту 8000. Поставьте перед ним обратный прокси с TLS на адрес VKTEAMS_MCP_PUBLIC_URL: OAuth и коды входа должны идти по HTTPS.

Сервер ничего не хранит, у него нет базы. Всё, что нужно следующему шагу, лежит в зашифрованном блоке (AES-GCM, ключ из VKTEAMS_MCP_SECRET), и этот блок приносит тот, кому он нужен:

Что

Где лежит

Сколько живёт

сессия VK Teams

внутри OAuth-токенов у клиента; клиент обновляет их сам, по стандарту

доступ 1 час, обновление 30 дней

регистрация клиента

внутри client_id

10 лет

черновик

в значении draft, которое возвращает save_draft

24 часа

шаг ввода кода

в скрытом поле формы входа

15 минут

ссылка на файл

в самой ссылке

5–10 минут

лимит действий

в памяти реплики

до перезапуска

свежий aimsid

в памяти реплики, как кэш

час

Поэтому реплик может быть сколько угодно: им нужен только один общий секрет. Повторная отправка того же черновика не создаёт дубль: VK Teams склеивает сообщения с одинаковым localMsgId, а отложенный текст сервер сверяет с очередью. Два исключения: отложенный опрос или ответ с цитатой при повторе встанут в очередь ещё раз, и то же может случиться, если один отложенный черновик отправить одновременно с двух реплик. Лимит действий каждая реплика считает сама. Отключение коннектора закрывает сессию в VK Teams, и после этого все токены с ней мертвы. Отдельный выданный токен до истечения отозвать нельзя. Если сменить секрет, все переподключатся заново.

Большинство корпоративных серверов VK Teams отвечают только внутри сети компании. Тогда коннектор ставят туда же, закрепляют за одной инсталляцией и включают VKTEAMS_MCP_ALLOW_PRIVATE_NETWORKS=1.

Разработка

uv sync
uv run pytest                            # юнит-тесты против фейка VK Teams, который записывает каждый запрос
uv run python scripts/mutation_check.py  # убирает каждое правило по очереди: его тест обязан упасть
uv run python -m vkteams_mcp.budget      # сколько каталог стоит модели
uv run python -m vkteams_mcp.surface --check

Живые тесты (tests/live) ходят на настоящий сервер и запускаются вручную.

Документы

Документ

Что в нём

MANIFESTO.md

Правила; у каждого описано, как выглядит нарушение

docs/requirements.md

Контракты инструментов и все отказы с тестами

docs/live-findings.md

Что делает живой сервер VK Teams

docs/qa-scenarios.md

Сценарии QA по каждому параметру, найденные дефекты и исправления

CHEATSHEET.md

Клиентский API VK Teams: вход, подпись, вызовы, ловушки

SECURITY.md

Как сообщить об уязвимости

CONTRIBUTING.md

Как сделать и проверить изменение

Кто сделал

Widmo разворачивает ИИ-платформу внутри периметра компании, подключает её к системам компании и учит команды делать своих агентов. Этот коннектор — одна из её частей.

Лицензия

Apache-2.0.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI agents to authenticate users, manage calendar events, create meetings, and maintain persistent API sessions for seamless integration with Russian business platforms. Provides comprehensive business productivity capabilities including session management, password operations, and cross-user calendar coordination.
      -
    • A
      license
      A
      quality
      B
      maintenance
      VK API for AI assistants: wall posts, communities, messages, market items, ads and stats. 373 methods in one catalog, each with a read/write/destructive safety class; the agent searches methods in plain language instead of receiving 373 tools.
      18
      158 PyPI
      3
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to interact with Microsoft Teams and Microsoft Graph through OAuth-authenticated tools for messaging, chat and channel management, message search, file uploads and downloads, and user directory lookups. Supports rich Markdown formatting, mentions, attachments, and LLM-friendly HTML-to-Markdown content conversion.
      12 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to interact with Microsoft Teams and Microsoft Graph, covering channel and chat messaging, message editing and search, user and team member lookup, attachment downloads, and file uploads. Supports Markdown-formatted messages, HTML-to-Markdown conversion for LLM-friendly output, and OAuth device-code authentication with an optional read-only mode.
      12 npm
      MIT