Список проектов через MCP: поиск рабочих пространств и ID проектов

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

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

Назначение

Инструмент list_projects получает все проекты, доступные в вашем рабочем пространстве. Используйте этот инструмент, когда вам нужно найти ID проекта перед созданием задач, генерацией отчётов или привязкой работы к конкретному проекту.

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

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

Инструмент принимает необязательные параметры поиска и постраничной навигации.

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

Инструмент возвращает постранично разбитый список объектов проектов:

{
  "data": [
    {
      "id": 456,
      "name": "Q1 Product Launch",
      "description": "Launch new product features for Q1 2026",
      "created_at": "2026-01-01T10:00:00Z",
      "updated_at": "2026-03-10T14:30:00Z",
      "task_count": 42,
      "board_count": 3,
      "member_count": 5
    },
    {
      "id": 789,
      "name": "Marketing Campaign",
      "description": "Spring marketing campaign",
      "created_at": "2026-02-01T09:00:00Z",
      "updated_at": "2026-03-08T11:15:00Z",
      "task_count": 18,
      "board_count": 1,
      "member_count": 3
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 2
  }
}

Поля ответа

• id: уникальный идентификатор проекта (используйте его в других инструментах, таких как create_task, list_tasks)
• name: название проекта
• description: описание проекта (может быть null)
• created_at / updated_at: временные метки
• task_count: общее количество задач в проекте
• board_count: количество досок
• member_count: количество участников

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

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

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

{
  "tool": "list_projects",
  "arguments": {}
}

Возвращает: все проекты в вашем рабочем пространстве

Пример 2: поиск по имени

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

{
  "tool": "list_projects",
  "arguments": {
    "search": "Product Launch"
  }
}

Возвращает: проекты, соответствующие «Product Launch» в имени

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

Claude Desktop / общий ИИ

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

"Какие у меня есть проекты?"

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

1. ИИ вызывает list_projects без фильтров
2. ИИ получает список всех проектов
3. ИИ представляет названия проектов и количество задач

Поиск конкретного проекта

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

"Найди проект Q1 launch и создай в нём задачу"

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

1. ИИ вызывает list_projects с search: "Q1 launch"
2. ИИ находит ID проекта (456)
3. ИИ вызывает create_task с project_id: 456

Группировка задач по проекту

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

"Покажи мои задачи, сгруппированные по проектам"

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

1. ИИ вызывает list_projects, чтобы получить все названия и ID проектов
2. ИИ вызывает list_tasks для каждого проекта
3. ИИ группирует и представляет задачи по названию проекта

Распространённые сценарии использования

• Планирование спринта — поиск ID проектов для привязки задач спринта
• Отчёты о статусе — получение названий проектов для заголовков отчётов
• Еженедельное планирование — группировка задач по проектам
• Кросс-проектный поиск — сопоставление ID проектов с именами в результатах поиска

Краевые случаи

Проекты не найдены

Ситуация: в рабочем пространстве нет проектов или поиск ничего не находит

Ответ:

{
  "data": [],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 0
  }
}

Обработка: проверьте поисковый запрос или убедитесь, что в рабочем пространстве есть проекты

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

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

Ответ:

{
  "error": "forbidden",
  "message": "You don't have permission to access projects in this workspace"
}

Обработка: проверьте конфигурацию API-ключа

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

Лучшие практики

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

• ✅ Всегда сначала вызывайте list_projects, когда вам нужен ID проекта
• ✅ Используйте параметр search, чтобы сузить результаты, когда вы знаете название проекта
• ✅ Кэшируйте ID проектов в рамках разговора, чтобы избежать избыточных вызовов
• ✅ Используйте названия проектов из ответа, чтобы сделать отчёты читаемыми для человека

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

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

• get_project — получить полные детали конкретного проекта по ID
• create_task — создание задач в проекте (требуется project_id)
• list_tasks — фильтрация задач по project_id
• list_boards — поиск досок в проекте