MCP-сервер

Проекты VK WorkSpace поддерживает подключение по протоколу Model Context Protocol (MCP). Это позволяет AI-агентам работать с данными Проекты VK WorkSpace напрямую из совместимых клиентов — находить и создавать задачи, вести списания, редактировать документы и многое другое.

MCP — это открытый стандарт, описывающий способ взаимодействия больших языковых моделей (LLM) с внешними системами. Подробнее о протоколе — на сайте modelcontextprotocol.io.

MCP-сервер Проекты VK WorkSpace использует streamable-http и работает с любым MCP-клиентом, поддерживающим этот транспорт.

Добавьте в конфигурационный файл MCP-клиента блок с описанием сервера:

 
{  "mcp": {    "servers": {      "projects": {        "url": "https://<адрес-сервера>/mcp",        "transport": "streamable-http",        "headers": {          "Authorization": "Bearer ${PRIVATE_TOKEN}"        }      }    }  }}

Где:

• <адрес-сервера> — адрес Проекты VK WorkSpace
• PRIVATE_TOKEN — переменная окружения со значением персонального токена API. Можно указать значение токена напрямую вместо переменной, но использование переменной окружения безопаснее.

После сохранения перезапустите клиент.

К адресу сервера можно добавить необязательные query-параметры, чтобы ограничить набор доступных агенту инструментов:

• scope — домены инструментов, которые будут доступны агенту. Возможные значения: tasks, wiki или их комбинация через запятую — tasks,wiki. По умолчанию доступны оба домена.
• access — уровень доступа. Возможные значения:
  • readonly — только чтение данных
  • default — чтение, изменение задач и добавление комментариев (значение по умолчанию)
  • full — дополнительно к возможностям default разрешает создание и удаление сущностей.

Например, чтобы работать только с задачами и разрешить агенту создание и удаление сущностей, укажите:

 
https://<адрес-сервера>/mcp?scope=tasks&access=full

Откройте новый чат в MCP-клиенте и убедитесь, что сервер projects появился в списке доступных инструментов. Задайте агенту тестовый запрос, например:

Покажи все мои активные задачи

Если подключение настроено правильно, агент вернёт список задач.

Инструменты сервера разделены на два домена — задачи (scope=tasks) и страницы (scope=wiki). Уровень доступа регулируется параметром access: с readonly доступно только чтение, с default — редактирование задач и добавление комментариев, с full — дополнительно создание связей, вложений и удаление сущностей.

Поиск и чтение

• быстрый поиск задач по названию, в том числе с ограничением по списку пространств
• расширенный постраничный поиск с фильтрами по статусу, категории статуса, исполнителю, автору, типу задачи, родителю, спринту и элементу портфеля
• поиск задач, изменённых за указанный период
• получение карточки задачи по ключу вида TS-15930 (название, описание, тип, статус, исполнитель, родитель, даты, счётчики подзадач, комментариев и вложений)
• получение комментариев, вложений, подзадач, связей (с задачами и страницами), истории изменений и списаний времени
• получение связанных merge-запросов из Git-интеграций
• список пользователей, доступных для назначения исполнителем
• скачивание файлов-вложений
• агрегированные списания времени за период с разбивкой по пользователям и задачам.

Изменение, создание и удаление

• создание задачи в указанной папке пространства (обязательны папка и тип задачи)
• обновление полей задачи (название, описание, тип, статус, исполнитель, даты начала и срока, спринт, оценка во времени и в стори-поинтах, родитель, привязка к элементам портфеля)
• удаление задачи
• добавление комментариев
• добавление и удаление списаний времени
• создание и удаление связей задачи с другой задачей или со страницей
• добавление вложений (файл в base64, до 100 МБ на запрос).

Поиск и чтение

• быстрый поиск страниц по названию
• совместный поиск задач и страниц по названию и опционально по содержимому
• получение страницы (с хлебными крошками и, опционально, по конкретной версии)
• список страниц пространства
• получение вложений, комментариев (в том числе inline-комментариев к версии), версий, дочерних страниц и связей страницы с задачами
• скачивание файлов-вложений.

Изменение, создание и удаление

• создание страницы (заголовок и содержимое, опционально родительская страница)
• обновление страницы (заголовок и содержимое, публикация новой версии)
• удаление страницы целиком или отдельной её версии
• добавление комментариев
• создание и удаление связи страницы с задачей
• добавление вложений (файл в base64, до 100 МБ на запрос).

Создание элементов структуры, к которым привязываются задачи (доступно при access=full):

• создание папок для группировки задач
• создание портфелей и их элементов (релизы, версии, проекты)
• создание спринтов — при отсутствии Agile-настройки в папке она создаётся автоматически.

Доступны независимо от scope:

• список пространств текущего пользователя
• профиль текущего пользователя и получение пользователя по id или логину
• справочники пространства: статусы, категории статусов, типы задач, пользовательские атрибуты, типы связей, папки, портфели и их элементы, спринты и бэклоги
• получение конкретной папки, портфеля, элемента портфеля, спринта или бэклога по id.

Технический писатель: Белова Ирина