Skip to main content
Glama
VK Community MCP

VK Community MCP

README.md
# VK Community MCP

Собственный удалённый MCP для сообществ ВКонтакте: чтение стен, работа с публикациями, сообщения сообщества и статистика при наличии нужных прав VK API. Python 3.11+, официальный MCP SDK, Streamable HTTP, OAuth 2.1/PKCE. Локальная установка MCP клиенту не нужна.

Версия 0.1.0 — первая реализация, не объединение всех инструментов исследованных серверов. [Источники и лицензии](документы/Источники%20и%20лицензии.md).

## Инструменты

| Инструмент | Назначение |
|---|---|
| `vk_communities` | Сообщества текущего пользователя |
| `vk_capabilities` | Реализованные операции и ограничения |
| `vk_describe_operation` | Параметры конкретной операции |
| `vk_read` | Чтение стены, постов, участников, комментариев, статистики, товаров и сообщений сообщества |
| `vk_prepare_action` | Подготовить изменение и получить ссылку подтверждения |
| `vk_execute_action` | Выполнить подтверждённое действие |

Операции чтения: `wall`, `posts`, `community`, `members`, `comments`, `statistics`, `post_reach`, `conversations`, `history`, `products`. Не более 100 объектов на страницу. Пагинация — через `offset`.

Действия: `publish_post`, `edit_post`, `delete_post`, `pin_post`, `unpin_post`, `reply_comment`, `reply_message`, `mark_read`, `upload_wall_photo`. Фото JPEG/PNG передаётся как base64 (до 4 МиБ), без чтения файлов сервера и скачивания произвольных URL. Загрузка изображения и публикация — два отдельных подтверждаемых действия.

Публикация с готовым вложением:

```json
{"community":"my-community","action":"publish_post","parameters":{"message":"Текст публикации","attachments":"photo-123_456"}}
```

Агент получает `approval_url`. Пользователь входит под учётной записью MCP, проверяет сообщество и точные параметры, подтверждает, затем просит агента выполнить `action_id`. Пароль MCP не является паролем VK. Действие истекает через 10 минут; после неизвестного результата запись автоматически не повторяется. Успешный повтор возвращает сохранённый результат.

## Доступы VK и ограничения

- `token`: токен **конкретного сообщества** с нужными разрешениями, прежде всего messages/wall. История относится к переписке сообщества, личная переписка не реализована.
- `service_key`: сервисный ключ своего приложения VK для публичного чтения. Не равнозначен токену VK ID для входа.
- `user_token`: необязательный отдельно полученный официальным способом пользовательский токен. Статистика, товары, загрузка фотографий и некоторые изменения требуют этого вида доступа; наличие роли администратора не заменяет токен.
- Новые приложения могут не получать необходимые права. Сервер честно возвращает отказ VK, не пытается обходить ограничения через чужие App ID или браузер.
- Официальная схема и поведение живого API могут различаться. Отправка, редактирование и статистика требуют проверки с конкретными разрешёнными токенами.
- Нет рекламы, платежей, произвольных методов API, автоматических ответов и изменения настроек Long Poll.
- Это первая версия без независимого аудита безопасности; подключать других людей следует после проверки изоляции на реальных сценариях.

## Подключение AI-клиента

Адрес размещения: `https://mcp.shmasiki.pro/vk/mcp`. Транспорт Streamable HTTP, авторизация OAuth. Поддерживается DCR; для ручной регистрации нужны `authorization_code`, `refresh_token`, PKCE S256 и redirect URI клиента. Scopes: `vk:read` и при необходимости `vk:write`. По умолчанию выдаётся только чтение. Создание OAuth-клиента не даёт доступа к сообществам без входа пользователя.

В ChatGPT добавьте собственный MCP с OAuth; возможность зависит от разрешений аккаунта. В Codex добавьте HTTP MCP и выполните штатный OAuth-вход. Ключи VK в конфигурацию AI-клиента не передаются.

Другие пользователи получают отдельную учётную запись MCP и свои привязки сообществ. Регистрация пользователей и добавление токенов выполняются администратором сервера, не через инструменты модели. Публичный код не предоставляет доступа к размещённому экземпляру.

## Запуск и проверка

Команды выполняются **на сервере**, в отдельном окружении:

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock
.venv/bin/python -m pip install --no-deps .
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python scripts/check_publication.py
VK_MCP_STATE=/var/lib/mcp-vk .venv/bin/python -m vk_mcp.server
```

Процесс слушает только `127.0.0.1:8310`. [Служба systemd](deploy/vk-community.service) использует пользователя `mcp-vk`, состояние в `/var/lib/mcp-vk` (700), root-владелец кода и отдельное окружение. [Пример Caddy](deploy/Caddyfile.example) показывает нужные пути. DNS менять не требуется. При размещении других MCP общие OAuth-пути нужно согласовать или выделить общий авторизационный сервис.

JSON для `python -m vk_mcp.admin user` передаётся через stdin из защищённого локального ввода, с полями `username`, `password` (от 16 символов). Для `community`: `username`, `alias`, положительный `group_id`, `token`, при наличии `service_key`, `user_token`. Не помещайте значения в shell-команду, историю, чат или Git. Смена пароля инвалидирует существующие OAuth-grants этого небольшого экземпляра для всех пользователей.

## Хранение и безопасность

Токены VK и OAuth-объекты шифруются Fernet; ключ отдельно в файле с правами 600, база с правами 600, каталог 700. Владелец сервера с root-доступом может расшифровать данные: шифрование не защищает от администратора VPS. Пароли — scrypt. Сервер проверяет пользователя, scope и привязку сообщества на каждом вызове. OAuth access token действует час, refresh — до 30 дней с ротацией.

Для резервного копирования нужны **и база, и vault.key**, за пределами Git. Действия ожидающие подтверждения содержат текст и адресата; они зашифрованы и истекают. Просроченные временные объекты удаляются при следующей записи. Журналы HTTP-доступа выключены; не включайте логирование заголовков, тел запросов и query строки login/approval.

## Обновления и откат

Код развивается в этом репозитории. `main` — исходники; автоматическое развёртывание использует отдельную ветку `production`, обновляемую только после проверок. [Порядок обслуживания](документы/Обслуживание.md). Не обновляйте сторонние зависимости или production без прохождения тестов. Каталог инструментов в AI-клиенте может потребовать refresh.

## Карта

`vk_mcp/` — реализация; `tests/` — автономные проверки с искусственными токенами, без VK-запросов; `scripts/` — проверка публикации; `deploy/` — служба и пример прокси; `.github/workflows/` — CI; `requirements.lock` — точные версии; `документы/` — происхождение, лицензии, обслуживание и ограничения.

MIT. Лицензия собственного кода не заменяет условия VK API и лицензии зависимостей.

## Регистрация собственного приложения VK

Для веб-платформы можно зарегистрировать базовый домен `mcp.shmasiki.pro` и HTTPS Redirect URI `https://mcp.shmasiki.pro/vk/oauth/callback`. Этот endpoint подготовлен для регистрации и отклоняет любые непрошенные OAuth-коды, state и токены; он не реализует вход через VK ID и не подменяет OAuth авторизации клиентов MCP. Для получения сервисного ключа из настроек приложения запускать VK ID вход не требуется. Наличие сервисного ключа в конкретном интерфейсе VK нужно подтвердить после создания. Не подставляйте вместо него client secret или VK ID token.

## Расширенный каталог и видео

Сборка включает100 закреплённых методов MCP учителя alexfisenkov/vk-mcp. Через существующие6инструментов: vk_capabilities перечисляет каталог; vk_capabilities(community="seeinmind") показывает готовность ключей; vk_describe_operation(operation="video.get") — точную схему; vk_read(community="seeinmind",operation="video.get",parameters={"count":1}) — ограниченное чтение. Имена методов записи используются в vk_prepare_action/vk_execute_action с обязательным браузерным подтверждением. Старые краткие имена сохранены. Scope owner_id/group_id задаётся сервером и не может переключить сообщество.

Каталог не означает проверенные права VK. Неподключённый подходящий ключ возвращает not_configured; сервисный ключ не используется для записи, сообщения только с ключом сообщества. Уведомления MIT — THIRD_PARTY_NOTICES.md.

upload_video — отдельное действие: source_url (публичный HTTPS MP4 до20МиБ), name/description необязательны. На подготовке файл скачивается для SHA256/размера; после подтверждения скачивается повторно, изменение содержимого останавливает отправку в VK. DNS закрепляется, private IP/небезопасные redirects отклоняются, загрузка только на разрешённые VK-хосты. Локальные пути Mac и вложения чата напрямую не читаются. Требуется user_token по официальной схеме video.save; путь с community token у учителя не подтверждён вживую, здесь не выдаётся за доступный. Успех означает переданную загрузку с processing:true, а не готовый клип/пост. Публикация VK-клипов не реализована, обычный пост автоматически не создаётся.

Для чтения обработки/типа конкретного видео: vk_read(community="seeinmind", operation="videos_by_id", parameters={"video_ids":[123]}). Передаются только положительные локальные ID, owner закреплён за выбранным сообществом. Смотрите фактические processing/converting/type в ответе VK; отсутствующие поля нельзя считать подтверждением готовности или клипа. Отдельная публикация клипа через недокументированные shortVideo-методы не подключается: пользователь выбрала только официальный API.