Список досок через MCP: поиск нужной рабочей доски

Справочник разработчика по MCP-инструменту list_boards. Узнайте, как находить и искать доски в вашем рабочем пространстве, фильтровать их по проекту и использовать постраничную навигацию. Включает примеры вызовов инструмента, запросы на естественном языке, граничные случаи и устранение неполадок.

Обзор инструмента

Назначение

Инструмент list_boards позволяет находить и искать доски в вашем рабочем пространстве Workify. Доски представляют рабочие процессы (например, канбан-доски), где задачи проходят через различные состояния. Используйте этот инструмент, чтобы найти доски по имени, отфильтровать их по проекту или получить обзор всех своих рабочих досок.

Операция только для чтения: этот инструмент только читает данные — он никогда не изменяет доски.

Входные параметры

Все параметры необязательны. Если параметры не указаны, возвращаются все доски, к которым у вас есть доступ (с постраничной навигацией).

Формат вывода

Инструмент возвращает JSON-объект с досками и информацией о постраничной навигации:

{
  "boards": [
    {
      "id": 789,
      "name": "Sprint Board",
      "project_id": 456,
      "project_name": "Q1 Product Launch",
      "created_at": "2026-01-01T10:00:00Z",
      "updated_at": "2026-03-10T14:30:00Z",
      "task_count": 15,
      "column_count": 4
    }
  ],
  "total": 8,
  "limit": 25,
  "offset": 0,
  "has_more": false
}

Поля ответа

• boards: массив объектов досок (пустой массив, если совпадений нет)
• total: общее количество досок, соответствующих фильтрам (по всем страницам)
• limit: максимальное количество досок, возвращённых в этом ответе
• offset: количество пропущенных досок (для постраничной навигации)
• has_more: логическое значение, указывающее, доступны ли ещё доски

Поля объекта доски

• id: уникальный идентификатор доски
• name: имя доски
• project_id: ID проекта, которому принадлежит эта доска
• project_name: имя проекта (для удобства)
• created_at: отметка времени создания доски
• updated_at: отметка времени последнего обновления доски
• task_count: общее количество задач на этой доске
• column_count: количество столбцов/состояний на доске

Примеры вызовов инструмента

Пример 1: список всех досок

Вызов инструмента (JSON):

{
  "tool": "list_boards",
  "arguments": {
    "limit": 50
  }
}

Возвращает: первые 50 досок из вашего рабочего пространства

Пример 2: доски в проекте

Вызов инструмента (JSON):

{
  "tool": "list_boards",
  "arguments": {
    "project_id": 456,
    "limit": 25
  }
}

Возвращает: все доски в проекте 456

Пример 3: поиск досок по имени

Вызов инструмента (JSON):

{
  "tool": "list_boards",
  "arguments": {
    "search": "Sprint",
    "limit": 25
  }
}

Возвращает: доски, в имени которых есть «Sprint»

Примеры запросов на естественном языке

Claude Desktop / общий ИИ

Запрос пользователя:

"Покажи мне все доски в проекте Q1"

Поведение ИИ:

1. ИИ вызывает list_projects, чтобы найти ID проекта Q1
2. ИИ вызывает list_boards с фильтром project_id
3. ИИ получает список досок
4. ИИ форматирует и представляет список досок пользователю

Поиск конкретной доски

Запрос пользователя:

"Найди доску Sprint"

Поведение ИИ:

1. ИИ вызывает list_boards с search: "Sprint"
2. ИИ получает соответствующие доски
3. ИИ показывает соответствующие доски или запрашивает уточнение, если совпадений несколько

Выбор рабочей доски

Запрос пользователя:

"Какие доски доступны для проекта Q1?"

Поведение ИИ:

1. ИИ находит ID проекта с помощью list_projects
2. ИИ вызывает list_boards с фильтром по project_id
3. ИИ представляет варианты досок с количеством задач

Типичные сценарии использования

• Запуск проекта — найдите существующие доски перед созданием новых рабочих процессов
• Узкие места на доске — получите список досок для анализа производительности рабочего процесса
• Управление задачами — найдите доски, чтобы фильтровать задачи по рабочему процессу
• Получить детали доски — найдите ID доски перед получением полных сведений

Граничные случаи

Доски не найдены

Ситуация: поиск не возвращает совпадений или в проекте нет досок

Ответ:

{
  "boards": [],
  "total": 0,
  "limit": 50,
  "offset": 0,
  "has_more": false
}

Обработка: это нормально — пустой массив означает, что нет досок, соответствующих запросу. Проверьте, есть ли в проекте доски, или попробуйте другие поисковые термины.

Недействительный ID проекта

Ситуация: project_id не существует

Ответ:

{
  "error": "validation_error",
  "message": "Project with ID 999 not found",
  "field": "project_id"
}

Обработка: сначала проверьте существование project_id с помощью list_projects

Доступ запрещён (403)

Ситуация: у API-ключа нет доступа к списку досок

Ответ:

{
  "error": "forbidden",
  "message": "You don't have permission to list boards"
}

Обработка: убедитесь, что у API-ключа есть доступ к рабочему пространству

Прочитать руководство по устранению ошибки 403 →

Устранение неполадок

Пустые результаты

Симптом: возвращается пустой массив досок

Причины:

• В проекте нет досок
• Поисковый запрос не совпадает ни с одним именем доски
• У вас нет доступа ни к одной доске

Решение:

• Попробуйте вызвать без параметра search, чтобы увидеть все доски
• Проверьте правильность project_id с помощью list_projects
• Проверьте, существуют ли доски в веб-интерфейсе Workify

Недействительный ID проекта

Симптом: ошибка валидации, связанная с project_id

Причины:

• ID проекта не существует
• Проект принадлежит другому рабочему пространству
• Проект был удалён

Решение:

• Используйте list_projects, чтобы найти действительные ID проектов
• Убедитесь, что проект существует в вашем рабочем пространстве
• Опустите project_id, чтобы получить список досок по всем проектам

Рекомендации

Эффективное использование list_boards

• ✅ Используйте фильтр project_id, чтобы находить доски в рамках конкретного проекта
• ✅ Используйте параметр search, чтобы быстро находить доски по имени
• ✅ Используйте постраничную навигацию (limit/offset) для рабочих пространств с большим количеством досок
• ✅ Вызывайте get_board после нахождения ID доски для получения полных сведений
• ✅ Используйте ID досок из list_boards, чтобы фильтровать задачи с помощью list_tasks

Связанные инструменты

Часто используются вместе с:

• get_board — получить полные сведения о доске после нахождения ID
• list_projects — найти ID проектов перед фильтрацией досок
• list_tasks — фильтровать задачи по board_id из list_boards