Boards per MCP auflisten: Das richtige Workflow-Board finden

Entwicklerreferenz für das MCP-Tool list_boards. So entdecken und durchsuchen Sie Boards in Ihrem Arbeitsbereich, filtern nach Projekt und nutzen Paginierung. Inkl. Beispiel-Tool-Aufrufe, natürliche Sprache, Grenzfälle und Fehlerbehebung.

Tool-Überblick

Zweck

Das Tool list_boards ermöglicht das Entdecken und Durchsuchen von Boards in Ihrem Corcava-Arbeitsbereich. Boards repräsentieren Workflows (z. B. Kanban-Boards), in denen Aufgaben verschiedene Zustände durchlaufen. Nutzen Sie es, um Boards nach Namen zu finden, nach Projekt zu filtern oder eine Übersicht aller Workflow-Boards zu erhalten.

Nur-Lesen-Operation: Dieses Tool liest nur Daten – es ändert keine Boards.

Eingabeparameter

Alle Parameter sind optional. Ohne Parameter werden alle Ihnen zugänglichen Boards zurückgegeben (paginiert).

Ausgabeformat

Das Tool liefert ein JSON-Objekt mit Boards und Paginierungsinformationen:

{
  "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
}

Antwortfelder

• boards: Array von Board-Objekten (leeres Array bei keinen Treffern)
• total: Gesamtzahl der den Filtern entsprechenden Boards (über alle Seiten)
• limit: Maximale Anzahl der in dieser Antwort zurückgegebenen Boards
• offset: Anzahl der übersprungenen Boards (für Paginierung)
• has_more: Boolean, ob weitere Boards verfügbar sind

Board-Objektfelder

• id: Eindeutige Board-Kennung
• name: Boardname
• project_id: ID des Projekts, zu dem das Board gehört
• project_name: Name des Projekts (zur Orientierung)
• created_at: Zeitstempel der Erstellung
• updated_at: Zeitstempel der letzten Aktualisierung
• task_count: Gesamtzahl der Aufgaben auf diesem Board
• column_count: Anzahl der Spalten/Zustände im Board

Beispiel-Tool-Aufrufe

Beispiel 1: Alle Boards auflisten

Tool-Aufruf (JSON):

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

Rückgabe: Die ersten 50 Boards aus Ihrem Arbeitsbereich

Beispiel 2: Boards in einem Projekt

Tool-Aufruf (JSON):

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

Rückgabe: Alle Boards in Projekt 456

Beispiel 3: Boards nach Namen suchen

Tool-Aufruf (JSON):

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

Rückgabe: Boards, die „Sprint“ im Namen enthalten

Beispiele für natürliche Sprache

Claude Desktop / Allgemeine KI

Nutzeraufforderung:

"Zeig mir alle Boards im Q1-Projekt"

KI-Verhalten:

1. KI ruft list_projects auf, um die Q1-Projekt-ID zu finden
2. KI ruft list_boards mit project_id-Filter auf
3. KI erhält die Boardliste
4. KI formatiert und präsentiert die Boardliste dem Nutzer

Bestimmtes Board finden

Nutzeraufforderung:

"Finde das Sprint-Board"

KI-Verhalten:

1. KI ruft list_boards mit Suche: "Sprint" auf
2. KI erhält passende Boards
3. KI zeigt passende Boards oder fragt nach, wenn mehrere Treffer

Workflow-Board auswählen

Nutzeraufforderung:

"Welche Boards gibt es für das Q1-Projekt?"

KI-Verhalten:

1. KI findet die Projekt-ID mit list_projects
2. KI ruft list_boards gefiltert nach project_id auf
3. KI präsentiert Board-Optionen mit Aufgabenzahlen

Typische Anwendungsfälle

• Projekt-Kickoff – Bestehende Boards finden, bevor neue Workflows angelegt werden
• Board-Engpässe – Boards auflisten, um die Workflow-Performance zu analysieren
• Aufgabenverwaltung – Boards finden, um Aufgaben nach Workflow zu filtern
• Board-Details abrufen – Board-ID finden, bevor die vollständigen Details abgerufen werden

Grenzfälle

Keine Boards gefunden

Situation: Suche liefert keine Treffer oder das Projekt hat keine Boards

Antwort:

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

Umgang: Das ist normal – leeres Array bedeutet, dass keine Boards entsprechen. Prüfen, ob das Projekt Boards hat oder andere Suchbegriffe versuchen.

Ungültige Projekt-ID

Situation: project_id existiert nicht

Antwort:

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

Umgang: Vorher mit list_projects prüfen, ob project_id existiert

Berechtigung verweigert (403)

Situation: API-Schlüssel hat keinen Zugriff auf die Boardliste

Antwort:

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

Umgang: Prüfen, ob der API-Schlüssel Zugriff auf den Arbeitsbereich hat

403-Fehlerbehebungsanleitung →

Fehlerbehebung

Leere Ergebnisse

Symptom: Leeres boards-Array wird zurückgegeben

Ursachen:

• Projekt hat keine Boards
• Suchanfrage trifft auf keinen Boardnamen
• Sie haben keinen Zugriff auf Boards

Lösung:

• Ohne Suchparameter aufrufen, um alle Boards zu sehen
• Mit list_projects prüfen, ob project_id korrekt ist
• In der Corcava-Weboberfläche prüfen, ob Boards existieren

Ungültige Projekt-ID

Symptom: Validierungsfehler zu project_id

Ursachen:

• Projekt-ID existiert nicht
• Projekt gehört einem anderen Arbeitsbereich
• Projekt wurde gelöscht

Lösung:

• Mit list_projects gültige Projekt-IDs finden
• Prüfen, ob das Projekt in Ihrem Arbeitsbereich existiert
• project_id weglassen, um Boards über alle Projekte aufzulisten

Best Practices

list_boards effektiv nutzen

• ✅ project_id-Filter nutzen, um Boards in einem bestimmten Projekt zu finden
• ✅ search-Parameter nutzen, um Boards schnell nach Namen zu finden
• ✅ Bei vielen Boards Paginierung (limit/offset) nutzen
• ✅ Nach dem Finden der Board-ID get_board für vollständige Details aufrufen
• ✅ Board-IDs aus list_boards nutzen, um mit list_tasks Aufgaben zu filtern

Verwandte Tools

Oft zusammen verwendet mit:

• get_board – Vollständige Board-Details nach dem Finden der ID abrufen
• list_projects – Projekt-IDs finden, bevor Boards gefiltert werden
• list_tasks – Aufgaben nach board_id aus list_boards filtern