MCP-Server mcp-tasks Spezifikation

Beschreibung

# MCP-Server: mcp-tasks

## Kontext

Ein MCP-Server (Model Context Protocol) soll entwickelt werden, der externen KI-Agenten (Claude, GPT, etc.) ermöglicht, das KI-Tasks-System auf dev.campus.systemische-tools.de zu bedienen.

Das Task-System ist ein Mensch-KI-Kollaborations-Werkzeug mit folgenden Komponenten:
- **Datenbank:** MariaDB `ki_protokoll` mit Tabellen: tasks, task_assignments, task_results, task_comments
- **API:** REST unter `/api/v1/tasks`
- **CLI:** `/var/www/tools/ki-tasks/cli.php`

---

## Datenmodell

### Task (tasks)
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| id | bigint | Primary Key |
| uuid | varchar(36) | Unique Identifier |
| title | varchar(255) | Aufgabentitel |
| description | text | Ausführliche Beschreibung |
| type | enum | human_task, ai_task, mixed |
| status | enum | pending, in_progress, completed, failed, cancelled |
| created_by | varchar(100) | Ersteller (Name oder System) |
| created_by_type | enum | human, ai |
| parent_task_id | bigint | Für Subtasks |
| due_date | datetime | Fälligkeitsdatum |
| metadata | JSON | Zusätzliche strukturierte Daten |

### TaskAssignment (task_assignments)
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| task_id | bigint | Referenz zum Task |
| assignee | varchar(100) | Zugewiesene Person/KI |
| assignee_type | enum | human, ollama, claude, anthropic_api |
| model_name | varchar(100) | z.B. "mistral", "gpt-4" |
| status | enum | pending, accepted, rejected, in_progress, completed |

### TaskResult (task_results)
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| task_id | bigint | Referenz zum Task |
| executor | varchar(100) | Ausführende Instanz |
| executor_type | enum | human, ollama, claude, anthropic_api |
| model_name | varchar(100) | Verwendetes Modell |
| request | text | Ursprüngliche Anfrage |
| response | longtext | Antwort/Ergebnis |
| tokens_input | int | Eingabe-Tokens |
| tokens_output | int | Ausgabe-Tokens |
| cost_usd | decimal | Kosten in USD |
| status | enum | success, error, partial |
| error_message | text | Fehlerbeschreibung |
| duration_ms | int | Ausführungsdauer |

---

## Erforderliche MCP-Tools

Der MCP-Server muss folgende Tools bereitstellen:

### 1. tasks_list
**Zweck:** Tasks auflisten und filtern

**Parameter:**
- status (optional): pending | in_progress | completed | failed | cancelled
- type (optional): human_task | ai_task | mixed
- search (optional): Volltextsuche in Titel/Beschreibung
- limit (optional, default: 50): Anzahl Ergebnisse
- offset (optional, default: 0): Pagination

**Rückgabe:** Array von Tasks mit Metadaten

---

### 2. tasks_get
**Zweck:** Einzelnen Task mit Details abrufen

**Parameter:**
- id (required): Task-ID

**Rückgabe:** Task mit Assignments, Results, Comments

---

### 3. tasks_create
**Zweck:** Neuen Task erstellen

**Parameter:**
- title (required): Aufgabentitel
- description (optional): Ausführliche Beschreibung
- type (optional, default: ai_task): Task-Typ
- parent_task_id (optional): Für Subtasks
- due_date (optional): ISO 8601 Datum
- metadata (optional): JSON-Objekt

**Rückgabe:** Erstellter Task

---

### 4. tasks_update
**Zweck:** Task-Felder aktualisieren

**Parameter:**
- id (required): Task-ID
- title (optional): Neuer Titel
- description (optional): Neue Beschreibung
- type (optional): Neuer Typ
- due_date (optional): Neues Datum

**Rückgabe:** Aktualisierter Task

---

### 5. tasks_status
**Zweck:** Task-Status ändern

**Parameter:**
- id (required): Task-ID
- status (required): Neuer Status
- updated_by (optional): Wer hat geändert
- updated_by_type (optional): human | ai

**Rückgabe:** Aktualisierter Task

---

### 6. tasks_assign
**Zweck:** Task einer Person/KI zuweisen

**Parameter:**
- id (required): Task-ID
- assignee (required): Name der Person/KI
- assignee_type (required): human | ollama | claude | anthropic_api
- model_name (optional): Modellname falls KI
- notes (optional): Anmerkungen

**Rückgabe:** Erstelltes Assignment

---

### 7. tasks_result
**Zweck:** Ergebnis für Task speichern

**Parameter:**
- id (required): Task-ID
- response (required): Antwort/Ergebnis
- executor (required): Ausführende Instanz
- executor_type (required): human | ollama | claude | anthropic_api
- model_name (optional): Verwendetes Modell
- status (optional, default: success): success | error | partial
- tokens_input (optional): Eingabe-Tokens
- tokens_output (optional): Ausgabe-Tokens
- cost_usd (optional): Kosten
- error_message (optional): Bei Fehlern

**Rückgabe:** Gespeichertes Result

---

### 8. tasks_execute
**Zweck:** Task direkt mit lokaler KI (Ollama) ausführen

**Parameter:**
- id (required): Task-ID
- executor_type (optional, default: ollama): ollama
- model (optional, default: mistral): Modellname
- auto_complete (optional): Task nach Erfolg abschließen

**Rückgabe:** Ausführungsergebnis mit Response, Tokens, Dauer

---

### 9. tasks_delete
**Zweck:** Task löschen

**Parameter:**
- id (required): Task-ID

**Rückgabe:** Bestätigung

---

### 10. tasks_statistics
**Zweck:** Statistiken abrufen

**Parameter:** keine

**Rückgabe:**
- Task-Zähler nach Status und Typ
- Token-Statistiken (gesamt, Kosten)
- Modell-Nutzungsverteilung

---

## API-Endpunkte (Referenz)

Der MCP-Server kann diese REST-Endpunkte nutzen:

| Methode | Endpunkt | Beschreibung |
|---------|----------|--------------|
| GET | /api/v1/tasks | Liste mit Filtern |
| GET | /api/v1/tasks/{id} | Details |
| POST | /api/v1/tasks | Erstellen |
| PUT | /api/v1/tasks/{id} | Aktualisieren |
| DELETE | /api/v1/tasks/{id} | Löschen |
| POST | /api/v1/tasks/{id}/assign | Zuweisen |
| PUT | /api/v1/tasks/{id}/status | Status ändern |
| POST | /api/v1/tasks/{id}/results | Ergebnis speichern |
| GET | /api/v1/tasks/{id}/results | Ergebnisse abrufen |
| POST | /api/v1/tasks/{id}/execute | KI-Ausführung |
| GET | /api/v1/tasks/statistics | Statistiken |

Base-URL: https://dev.campus.systemische-tools.de

---

## Implementierungshinweise

1. **Authentifizierung:** Aktuell keine - kann später über API-Key erweitert werden
2. **Fehlerbehandlung:** Alle Endpunkte geben `{success: bool, error?: string, data?: ...}` zurück
3. **HTTP-Status:** 200 (OK), 201 (Created), 400 (Bad Request), 404 (Not Found), 500 (Error)
4. **Content-Type:** application/json für alle Requests/Responses

---

## Beispiel-Workflow für externe KI

1. `tasks_list --status=pending --type=ai_task` → Offene KI-Tasks abrufen
2. `tasks_get --id=123` → Task-Details lesen
3. `tasks_status --id=123 --status=in_progress` → Als "in Arbeit" markieren
4. [KI arbeitet am Task]
5. `tasks_result --id=123 --response="..." --executor=claude --executor_type=anthropic_api` → Ergebnis speichern
6. `tasks_status --id=123 --status=completed` → Abschließen

---

## Deliverables

1. MCP-Server-Implementierung in TypeScript/Python
2. Tool-Definitionen gemäß MCP-Spezifikation
3. Konfiguration für Claude Desktop / Claude Code
4. Dokumentation der Tools
5. Testfälle

Aktionen

Ergebnisse

MCP-Server mcp-tasks läuft unter /opt/mcp-servers/mcp-tasks/ mit allen spezifizierten Tools

Kommentare

← Zurück zur Task-Liste