# VK MCP

Удалённый MCP для сообществ ВКонтакте: посты, комментарии, диалоги,
статистика, фото, видео и товары. Сервер использует Streamable HTTP;
агент подключается по HTTPS без локального MCP-процесса.

Версия 0.2 содержит 26 инструментов и 36 действий: 34 метода VK и два сценария
загрузки. Это покрытие каталога, а не обещание доступа с любым токеном.
Реальные права проверяются отдельно для каждого метода и сообщества.

## Начать подключение

- **Агенту и оператору:** [пошаговая установка и выдача ключей](docs/onboarding.md).
- **При ошибке:** [диагностика и проверенные ограничения](docs/troubleshooting.md).
- **После прерванной установки:** [восстановление](docs/recovery.md).
- **Перед изменением кода:** [архитектура](docs/design.md),
  [план и границы приёмки](docs/implementation-plan.md), [AGENTS.md](AGENTS.md).
- **Источник методов:** [закреплённая официальная схема VK](src/catalog/SOURCE.md)
  и [происхождение/лицензии](THIRD_PARTY_NOTICES.md).

Инструкции различают проверенные результаты и незавершённые шаги. Новую
проблему подключения фиксируйте в troubleshooting: симптом, причина,
проверка, безопасное решение, дата и граница подтверждения. Используйте
синтетические ID и домены; реальные ключи, переписка и конфигурация в Git не идут.

## Разработка на macOS или Linux

Нужны Git, Node.js >=22, npm и Python 3 (для операторских скриптов и тестов):

```sh
git clone https://github.com/alexfisenkov/vk-mcp.git
cd vk-mcp
npm ci --ignore-scripts
npm run check
```

Сборка и offline-тесты работают без VK credentials и не обращаются к VK.
Это достаточный локальный контур разработки на Mac; production-установщик,
sистемная служба и root-owned подтверждения предназначены для Linux с systemd.
`npm start` требует заранее подготовленных защищённых файлов конфигурации;
не запускайте его на Mac от root ради обхода ошибок доступа.

## Безопасность и ограничения

Сообщества задаются явным allowlist. Group/user/service credentials остаются
на сервере; каталог выбирает подходящий тип, клиент не передаёт ключ в tool args.
`not_configured` отличим от отказа самого VK. Произвольный `execute`, удаление,
реклама, обход прав и личная лента не включены.

Запись выключена по умолчанию. План живёт 10 минут; для исполнения нужны
включённый write-профиль и независимое root-owned подтверждение точного hash
через `deploy/approve.py`. MCP-клиент сам его создать не может.
При `unknown` сначала сверяют исход в VK; повторная отправка запрещена.

Медиа поступают по публичному HTTPS URL. Проверяются адреса/redirects,
размер и HTTP MIME; это не проверка декодером. Лимит по умолчанию 20 MiB,
до трёх redirects, JPEG/PNG/WebP или MP4. Доступ и реальные upload hosts требуют
отдельной живой проверки; video.save не означает завершённую обработку видео.

HTTP ограничен 1 MiB на запрос и 120 авторизованными запросами в минуту;
VK-ответ — 4 MiB, интервал вызовов — 350 ms. Пагинация явная.
Планы содержат исходный payload и хранятся в каталоге службы 0700;
журнал — ID/hash/метод/статус. Автоматической очистки пока нет.

Core использует server bearer. OAuth для ChatGPT/Claude требует отдельного
MCP OAuth proxy/resource server с PKCE, audience и owner gate. Регистрация
приложения VK и её Redirect URL этого OAuth не реализуют.

Перед ручным выпуском оператор проверяет успешный CI точного Git SHA:
установщик сам CI не проверяет. Автообновление проверяет CI автоматически и
включается оператором отдельно; root-loader не заменяется новым приложением.
Исходники и документация — MIT.