# VK API MCP Server (FastMCP)

🚀 **Инструментальный сервер для VK API на базе FastMCP** - единый интерфейс для работы с VKontakte через ИИ-агентов.

## 📋 Содержание
- [Быстрый старт](#быстрый-старт)
- [Возможности](#возможности)
- [Установка и настройка](#установка-и-настройка)
- [Запуск в Gemini CLI](#запуск-в-gemini-cli)
- [Запуск в Cursor](#запуск-в-cursor)
- [Структура проекта](#структура-проекта)
- [API и методы](#api-и-методы)
- [Примеры использования](#примеры-использования)
- [Отладка и тестирование](#отладка-и-тестирование)
- [Troubleshooting](#troubleshooting)

## 🚀 Быстрый старт

### 1. Клонирование и установка
```bash
cd C:\Users\nikol\Projects\mcp_vk_api
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

### 2. Настройка токенов
```bash
# Скопируйте и отредактируйте config.ini
copy config.ini.example config.ini
```

Заполните `config.ini`:
```ini
[vk]
token = vk1.a.your_user_token_here

[google]
speech_api_key = your_google_speech_api_key
gemini_api_key = your_gemini_api_key
```

### 3. Запуск
```bash
# Gemini CLI
mcp run C:\Users\nikol\Projects\mcp_vk_api\main.py

# Или вручную
python -u main.py
```

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

### 🔧 Основные функции
- **10 агрегаторов VK API**: `users`, `groups`, `messages`, `wall`, `likes`, `photos`, `docs`, `video`, `utils`, `recognition`
- **Единый интерфейс**: по одной функции на раздел VK API
- **Long Poll**: ожидание событий в реальном времени
- **Автоматическое распознавание**: речи и изображений
- **Имитация человеческого поведения**: задержки, статусы печати
- **Кэширование**: результатов распознавания
- **Пагинация и retry**: надежная работа с API

### 🎯 Специальные возможности
- **`await_any_event`**: унифицированное ожидание сообщений/уведомлений
- **Автоформатирование**: сообщения с именами пользователей и эмодзи
- **Batch операции**: массовые вызовы API
- **Capability discovery**: автоматическое обнаружение методов
- **Универсальный клиент**: `vk_client.py` для тестирования

## 📦 Установка и настройка

### Требования
- **Python 3.11+**
- **VK User Token** с правами: `messages`, `wall`, `photos`, `docs`, `video`
- **Опционально**: Google Speech API и Gemini API ключи

### Зависимости
```bash
# Основные
fastmcp          # MCP сервер
vk_api           # VK API клиент
requests         # HTTP запросы

# Опционально для распознавания
google-genai     # Gemini API
```

### Получение токенов

#### VK Token
1. Перейдите на https://vkhost.github.io/
2. Выберите "Kate Mobile"
3. Авторизуйтесь и скопируйте токен

#### Google API (опционально)
1. **Speech API**: https://console.cloud.google.com/apis/library/speech.googleapis.com
2. **Gemini API**: https://makersuite.google.com/app/apikey

## 🎮 Запуск в Gemini CLI

### Глобальная установка
```bash
# Установите MCP CLI
pip install mcp

# Запустите сервер
mcp run C:\Users\nikol\Projects\mcp_vk_api\main.py
```

### Локальный запуск
```bash
cd C:\Users\nikol\Projects\mcp_vk_api
python -u main.py
```

### Примеры команд в Gemini CLI
```
# Получить информацию о пользователе
vk-api users get_user_info {"user_ids": "1", "fields": "photo_200"}

# Ожидать сообщения 5 минут
vk-api messages await_any_event {"duration_s": 300}

# Отправить сообщение
vk-api messages send_message {"peer_id": 123, "message": "Привет!"}
```

## 🖥️ Запуск в Cursor

### Настройка MCP в Cursor
1. Откройте `C:\Users\nikol\.cursor\mcp.json`
2. Добавьте конфигурацию:

```json
{
  "mcpServers": {
    "vk-api": {
      "command": "mcp",
      "args": ["run", "C:\\Users\\nikol\\Projects\\mcp_vk_api\\main.py"],
      "cwd": "C:\\Users\\nikol\\Projects\\mcp_vk_api"
    }
  }
}
```

3. Перезагрузите серверы: **Cursor Settings → MCP → Reload Servers**

### Использование в Cursor
- Откройте Command Palette (`Ctrl+Shift+P`)
- Выберите "MCP: Call Tool"
- Выберите `vk-api` и нужный агрегатор

## 📁 Структура проекта

```
mcp_vk_api/
├── 📄 main.py                    # MCP сервер, регистрация агрегаторов
├── 📄 vk_provider.py             # Инициализация VK API
├── 📄 config.py                  # Загрузка конфигурации
├── 📄 vk_client.py               # Универсальный тестовый клиент
├── 📄 requirements.txt           # Python зависимости
├── 📄 goal.txt                   # Цель проекта
├── 📄 config.ini                 # Токены и настройки
│
├── 📁 tools/                     # Агрегаторы VK API
│   ├── 📁 users/                 # Пользователи VK
│   │   └── 📄 tools.py           # get_user_info, search_users, get_friends, etc.
│   │
│   ├── 📁 groups/                # Группы VK
│   │   └── 📄 tools.py           # get_group_info, search_groups, get_members
│   │
│   ├── 📁 messages/              # Сообщения и Long Poll
│   │   ├── 📄 tools.py           # send_message, get_history, await_any_event
│   │   ├── 📄 formatting.py      # Форматирование сообщений
│   │   └── 📄 human_behavior.py  # Имитация человеческого поведения
│   │
│   ├── 📁 wall/                  # Стена и посты
│   │   └── 📄 tools.py           # get_wall_posts, create_comment, post_photo
│   │
│   ├── 📁 likes/                 # Лайки
│   │   └── 📄 tools.py           # is_liked, add, delete
│   │
│   ├── 📁 photos/                # Фотографии
│   │   └── 📄 tools.py           # photos_get, photos_get_albums
│   │
│   ├── 📁 docs/                  # Документы
│   │   └── 📄 tools.py           # docs_get, docs_search
│   │
│   ├── 📁 video/                 # Видео
│   │   └── 📄 tools.py           # video_search, video_get, video_get_direct_url
│   │
│   ├── 📁 utils/                 # Утилиты
│   │   └── 📄 tools.py           # paginate, vk_retry, resolve_screen_name
│   │
│   ├── 📁 recognition/           # Распознавание речи и изображений
│   │   ├── 📄 tools.py           # Агрегатор распознавания
│   │   ├── 📄 speech.py          # Google Speech API
│   │   ├── 📄 gemini.py          # Google Gemini API
│   │   ├── 📄 auto.py            # Автоматическое распознавание
│   │   └── 📄 cache.py           # Кэширование результатов
│   │
│   └── 📁 smart/                 # Умные функции (заготовка)
│
├── 📁 data/                      # Данные и кэш
│   ├── 📄 last_notifications.json # Время последних уведомлений
│   ├── 📄 last_ts.json           # Время последних сообщений
│   └── 📁 recognition_cache/     # Кэш распознавания
│
├── 📁 logs/                      # Логи
│   └── 📁 prompts/               # Логи промптов
│
├── 📁 tests/                     # Тесты
│   ├── 📄 mcp_likes_test.py      # Тест лайков
│   └── 📄 mcp_longpoll_test.py   # Тест Long Poll
│
└── 📁 scripts/                   # Скрипты (пусто)
```

## 🔌 API и методы

### Принцип работы
Каждый агрегатор принимает два параметра:
- `method` — строка, имя под-метода
- `params` — объект с параметрами

### Список агрегаторов

#### 1. `users` - Пользователи VK
```json
{
  "method": "get_user_info",
  "params": {"user_ids": "1,durov", "fields": "photo_200"}
}
```

**Доступные методы:**
- `get_user_info` - информация о пользователях
- `search_users` - поиск пользователей
- `get_friends` - друзья пользователя
- `get_followers` - подписчики
- `get_subscriptions` - подписки
- `get_mutual` - общие друзья
- `get_friend_requests` - заявки в друзья
- `add_friend` - добавить в друзья
- `delete_friend` - удалить из друзей

#### 2. `groups` - Группы VK
```json
{
  "method": "get_group_info",
  "params": {"group_ids": "durov", "fields": "description"}
}
```

**Доступные методы:**
- `get_group_info` - информация о группе
- `search_groups` - поиск групп
- `get_group_members` - участники группы

#### 3. `messages` - Сообщения и Long Poll
```json
{
  "method": "send_message",
  "params": {"peer_id": 123, "message": "Привет!", "reply_to": 456}
}
```

**Доступные методы:**
- `send_message` - отправить сообщение
- `get_conversations` - список диалогов
- `get_history` - история сообщений
- `get_unread_messages` - непрочитанные сообщения
- `mark_as_read` - отметить как прочитанное
- `delete_message` - удалить сообщение
- `edit_message` - редактировать сообщение
- `send_photo` - отправить фото
- `search_messages` - поиск сообщений
- `set_typing_status` - статус печати
- `await_any_event` - ожидание событий (Long Poll)

#### 4. `wall` - Стена и посты
```json
{
  "method": "get_wall_posts",
  "params": {"owner_id": "-1", "count": 5}
}
```

**Доступные методы:**
- `get_wall_posts` - получить посты
- `get_comments` - комментарии к посту
- `create_comment` - создать комментарий
- `post_photo` - пост с фото
- `pin_post` - закрепить пост
- `unpin_post` - открепить пост
- `edit_post` - редактировать пост
- `delete_post` - удалить пост
- `watch_wall_posts` - наблюдение за постами

#### 5. `likes` - Лайки
```json
{
  "method": "is_liked",
  "params": {"type": "post", "owner_id": "-1", "item_id": 123}
}
```

**Доступные методы:**
- `is_liked` - проверить лайк
- `add` - поставить лайк
- `delete` - убрать лайк

#### 6. `photos` - Фотографии
```json
{
  "method": "photos_get",
  "params": {"owner_id": "1", "album_id": "profile", "count": 3}
}
```

**Доступные методы:**
- `photos_get` - получить фотографии
- `photos_get_albums` - альбомы фотографий
- `photos_get_comments` - комментарии к фото
- `photos_create_comment` - создать комментарий к фото

#### 7. `docs` - Документы
```json
{
  "method": "docs_search",
  "params": {"q": "инструкция", "count": 10}
}
```

**Доступные методы:**
- `docs_get` - получить документы
- `docs_search` - поиск документов

#### 8. `video` - Видео
```json
{
  "method": "video_search",
  "params": {"q": "vk", "count": 10}
}
```

**Доступные методы:**
- `video_search` - поиск видео
- `video_get` - получить видео
- `video_get_comments` - комментарии к видео
- `video_get_direct_url` - прямая ссылка на видео

#### 9. `utils` - Утилиты
```json
{
  "method": "list_capabilities",
  "params": {}
}
```

**Доступные методы:**
- `list_capabilities` - список всех методов
- `describe` - описание метода
- `paginate` - пагинация
- `vk_retry` - надежный вызов API
- `resolve_screen_name` - разрешение короткого имени
- `resolve_cached` - кэшируемое разрешение
- `execute_batch` - пакетный вызов

#### 10. `recognition` - Распознавание
```json
{
  "method": "transcribe_speech",
  "params": {"audio_source": "https://example.com/audio.mp3", "language": "ru-RU"}
}
```

**Доступные методы:**
- `transcribe_speech` - распознавание речи
- `analyze_image` - анализ изображения
- `get_supported_languages` - поддерживаемые языки
- `get_available_features` - доступные функции

## 💡 Примеры использования

### Базовые операции

#### Получение информации о пользователе
```json
{
  "method": "get_user_info",
  "params": {
    "user_ids": "1,durov",
    "fields": "photo_200,city,verified"
  }
}
```

#### Поиск пользователей
```json
{
  "method": "search_users",
  "params": {
    "q": "Павел Дуров",
    "count": 5
  }
}
```

#### Отправка сообщения
```json
{
  "method": "send_message",
  "params": {
    "peer_id": 123456789,
    "message": "Привет! Как дела?",
    "reply_to": 987654321
  }
}
```

#### Ожидание событий (Long Poll)
```json
{
  "method": "await_any_event",
  "params": {
    "duration_s": 300
  }
}
```

### Продвинутые операции

#### Пагинация диалогов
```json
{
  "method": "paginate",
  "params": {
    "api_method": "messages.getConversations",
    "params": {},
    "max_items": 50,
    "page_size": 20
  }
}
```

#### Пакетный вызов API
```json
{
  "method": "execute_batch",
  "params": {
    "calls": [
      {"method": "users.get", "params": {"user_ids": "1"}},
      {"method": "users.get", "params": {"user_ids": "2"}}
    ]
  }
}
```

#### Распознавание речи
```json
{
  "method": "transcribe_speech",
  "params": {
    "audio_source": "C:/path/to/voice_message.mp3",
    "language": "ru-RU",
    "source_type": "file"
  }
}
```

#### Анализ изображения
```json
{
  "method": "analyze_image",
  "params": {
    "image_source": "https://example.com/image.jpg",
    "source_type": "url"
  }
}
```

## 🧪 Отладка и тестирование

### Универсальный клиент
```bash
# Тестирование через vk_client.py
python vk_client.py messages --args '{"method":"await_any_event","params":{"duration_s":60}}'

# Красивый вывод
python vk_client.py users --args '{"method":"get_user_info","params":{"user_ids":"1"}}' --pretty

# Из файла
python vk_client.py messages --args-file test_args.json
```

### Прямой вызов (без MCP)
```bash
# Для отладки
python vk_client.py messages --direct --args '{"method":"get_conversations","params":{"count":5}}'
```

### Логирование
```bash
# Запуск с подробными логами
python -u main.py 2>&1 | tee vk_api.log
```

### Проверка токенов
```bash
# Тест VK API
python vk_client.py users --args '{"method":"get_user_info","params":{"user_ids":"1"}}'

# Тест Google API (если настроены)
python vk_client.py recognition --args '{"method":"get_supported_languages","params":{}}'
```

## 🔧 Troubleshooting

### Частые проблемы

#### 1. "VK API not initialized"
**Причина:** Неверный токен или отсутствует `config.ini`
**Решение:**
```bash
# Проверьте config.ini
cat config.ini

# Получите новый токен на https://vkhost.github.io/
```

#### 2. "Skipping tool ... missing types"
**Причина:** Проблема с MCP сервером
**Решение:**
```bash
# Перезагрузите MCP servers в Cursor
# Или перезапустите сервер
python -u main.py
```

#### 3. "No prompts or tools found"
**Причина:** Неправильная конфигурация MCP
**Решение:**
```json
// Проверьте C:\Users\nikol\.cursor\mcp.json
{
  "mcpServers": {
    "vk-api": {
      "command": "mcp",
      "args": ["run", "C:\\Users\\nikol\\Projects\\mcp_vk_api\\main.py"],
      "cwd": "C:\\Users\\nikol\\Projects\\mcp_vk_api"
    }
  }
}
```

#### 4. Ошибки распознавания
**Причина:** Отсутствуют Google API ключи
**Решение:**
```bash
# Установите google-genai
pip install google-genai

# Добавьте ключи в config.ini
[google]
speech_api_key = your_speech_api_key
gemini_api_key = your_gemini_api_key
```

#### 5. "await_any_event" ждет только 60 секунд
**Причина:** Проблема с таймаутом
**Решение:** Обновлено в коде - теперь корректно работает с указанным `duration_s`

### Отладка Long Poll
```bash
# Тест ожидания событий
python vk_client.py messages --args '{"method":"await_any_event","params":{"duration_s":120}}'

# Проверка непрочитанных сообщений
python vk_client.py messages --args '{"method":"get_unread_messages","params":{}}'
```

### Проверка прав токена
```bash
# Тест основных функций
python vk_client.py users --args '{"method":"get_user_info","params":{"user_ids":"1"}}'
python vk_client.py messages --args '{"method":"get_conversations","params":{"count":1}}'
python vk_client.py wall --args '{"method":"get_wall_posts","params":{"owner_id":"1","count":1}}'
```

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

### Рекомендации
- ✅ **Не коммитьте** `config.ini` с токенами
- ✅ **Храните токены** только локально
- ✅ **Используйте переменные окружения** для API ключей
- ✅ **Регулярно обновляйте** токены VK
- ❌ **Не передавайте** токены третьим лицам

### Переменные окружения
```bash
# Альтернатива config.ini
export VK_TOKEN="vk1.a.your_token"
export GOOGLE_SPEECH_API_KEY="your_speech_key"
export GOOGLE_GEMINI_API_KEY="your_gemini_key"
```

## 🚀 Особенности и возможности

### Автоматическое распознавание
- **Голосовые сообщения** распознаются автоматически при получении истории
- **Кэширование результатов** для экономии API вызовов
- **Поддержка множества языков** через Google Speech API

### Имитация человеческого поведения
- **Автоматические задержки** при печати сообщений
- **Статусы "печатает"** для реалистичности
- **Настраиваемые интервалы** между действиями

### Красивое форматирование
- **Имена пользователей** вместо ID
- **Эмодзи и иконки** для разных типов контента
- **Структурированный вывод** для удобства чтения

### Универсальные утилиты
- **Пагинация** для больших списков
- **Retry механизм** для надежности
- **Batch операции** для эффективности
- **Кэширование** для оптимизации

## 📞 Поддержка

### Полезные команды
```bash
# Список всех методов
python vk_client.py utils --args '{"method":"list_capabilities","params":{}}'

# Описание конкретного метода
python vk_client.py utils --args '{"method":"describe","params":{"aggregator":"messages","method":"await_any_event"}}'

# Статистика распознавания
python vk_client.py messages --args '{"method":"get_recognition_statistics","params":{}}'

# Очистка кэша
python vk_client.py messages --args '{"method":"clear_recognition_cache_data","params":{}}'
```

### Логи и отладка
- **Логи сервера:** `python -u main.py 2>&1 | tee vk_api.log`
- **Тестовые файлы:** `tests/mcp_*.py`
- **Кэш данных:** `data/recognition_cache/`

---

**🎯 Цель проекта:** Быть проактивным и полезным ассистентом в VK. Проверять новые сообщения и отвечать на них осмысленно.

**📝 Лицензия:** Проект для личного использования и обучения.