# mcp-vkontakte

MCP для работы с личной страницей и сообществами ВКонтакте. Проект рассчитан на размещение на собственном VPS и подключение разных пользователей со своими VK-токенами.

**Статус: прототип 0.1.0, развёрнутый на VPS.** Проверены HTTPS, реальный вход через Keycloak, MCP по Streamable HTTP и отказ без авторизации. Есть кабинет подключений и подтверждение действий в браузере. Реальные VK-токены и OAuth в конкретных приложениях ещё не проверены; самостоятельная регистрация закрыта до подготовки публичного сервиса.

## Возможности

- Каталог методов из зафиксированной официальной схемы VK API с параметрами и поиском по русским словам. Фактические количества и ограничения приведены в [проверке](docs/VALIDATION.md).
- Чтение стен, профилей и сообществ, диалогов, статистики, товаров, фотографий и других разделов в пределах выданных VK разрешений.
- Подготовка публикаций и изменений с неизменяемыми параметрами. Выполнение возможно только после входа человека на отдельную страницу подтверждения. Модель не получает инструмент для самостоятельного подтверждения.
- Снимки доступных публикаций сообщества с ограничением страниц и явной отметкой неполной выборки.
- Сравнение сообществ за один период: частота постов, реакции, медианы, ER по просмотрам и текущему числу участников, распределение форматов и времени публикации. Расчёты снабжены формулами, ссылками и ограничениями.
- Раздельные подключения пользователей, шифрование VK-токенов и подготовленных действий, проверка OAuth-аудитории, CSRF, ограничения запросов и размеров данных.

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

## Что намеренно отсутствует в первой версии

Нет произвольных HTTP-запросов, выполнения кода, финансовых изменений, смены владельцев и настроек доступа, чтения произвольных файлов VPS. Прямая загрузка двоичных файлов и скачивание медиа по URL ещё не реализованы. Можно передавать существующие идентификаторы вложений, если соответствующий метод VK это разрешает.

Автоматического создания полнофункционального пользовательского токена VK нет. Проект не обходит ограничения VK. Реклама в каталоге относится к соответствующим методам VK API; поддержка отдельного современного API VK Ads не заявлена.

## Документация

- [Сравнение трёх проектов и аудит исходников](docs/RESEARCH.md)
- [Архитектура, границы безопасности и аналитика](docs/DESIGN.md)
- [Развёртывание с Keycloak и HTTPS](docs/DEPLOYMENT.md)
- [Подключение клиентов и фактические границы совместимости](docs/CLIENTS.md)
- [Проверка пользовательского доступа к поиску VK](docs/VK_USER_ACCESS.md)
- [Что проверено и что ещё требуется](docs/VALIDATION.md)
- [Порядок внесения изменений](CONTRIBUTING.md)

## Локальная разработка

Требуется Python 3.12.

```sh
python -m venv .venv
# Активируй окружение средствами своей ОС.
python -m pip install -r requirements.lock pytest==9.1.1 pytest-asyncio==1.4.0
python -m pytest -q
```

Тесты используют вымышленные токены и подставные ответы. Для запуска сервера нужны параметры Keycloak и шифрования из инструкции развёртывания. Небезопасного режима без авторизации нет.

## Лицензия и источники

MIT. Авторские уведомления для использованной схемы VK и заимствованного отбора методов находятся в [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). Код серверов-кандидатов в исполняемую часть не скопирован. Этот проект не является официальным продуктом VK, OpenAI или Anthropic.