# SPRLST

> SPRLST ist eine kollaborative Web-App für hierarchische Aufgaben-/Listenbäume ("Nodes"). Neben der Weboberfläche stellt SPRLST eine vollständige REST-API und einen MCP-Server bereit, sodass KI-Agenten dieselben Operationen ausführen können wie ein Mensch: Nodes lesen, anlegen, ändern, verschieben, löschen, kommentieren und Berechtigungen verwalten.

Wichtig für Integrationen:

- Basis-URL der REST-API: `https://sprlst.de/api/v1`
- Authentifizierung: Bearer-Token im `Authorization`-Header (`Authorization: Bearer <token>`). Tokens werden in der Web-Oberfläche unter "Schnittstellen" erzeugt und tragen Abilities (`nodes:read`, `nodes:write`, `nodes:delete`, `nodes:admin`) sowie optional eine Beschränkung auf bestimmte Unterbäume.
- Für KI-Agenten empfohlen: der MCP-Server unter `https://sprlst.de/mcp` (POST). Er stellt dieselben Operationen als Tools bereit, ohne dass HTTP-Routing-Wissen nötig ist.
- Datenmodell "Node": `name` (Pflicht), `description`, `is_completed`, `position`, `parent_id`. Jeder Node besitzt seinen kompletten Unterbaum; Zugriff auf einen Node schließt dessen Nachfahren ein.

## API

- [OpenAPI-Spezifikation (Deutsch, Default)](https://sprlst.de/openapi.yaml): Vollständige, maschinenlesbare Beschreibung aller REST-Endpunkte (OpenAPI 3.1), inkl. Security-Schema und MCP-Hinweisen.
- [OpenAPI-Spezifikation (Deutsch)](https://sprlst.de/openapi.de.yaml): Deutschsprachige Variante der Spezifikation.
- [OpenAPI-Spezifikation (Englisch)](https://sprlst.de/openapi.en.yaml): Englischsprachige Variante der Spezifikation.

## MCP (für KI-Agenten)

MCP-Endpunkt: `POST https://sprlst.de/mcp` (Bearer-Token erforderlich). Beispiel-Konfiguration für Claude Code in `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "sprlst": {
      "type": "http",
      "url": "https://sprlst.de/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}
```

Verfügbare Tools: `list-nodes`, `get-node`, `get-children`, `get-subtree`, `get-ancestors`, `list-comments` (read); `create-node`, `update-node`, `move-node`, `create-tree`, `add-comment` (write); `delete-node` (delete).

## Zentrale REST-Endpunkte

- `GET /api/v1/nodes` — eigene Root-Nodes auflisten
- `POST /api/v1/nodes` — Node anlegen (`name`, optional `parent_id`, `description`)
- `GET /api/v1/nodes/{node}` — einzelnen Node lesen
- `PATCH /api/v1/nodes/{node}` — Node ändern (`name`, `description`, `is_completed`, `position`)
- `DELETE /api/v1/nodes/{node}` — Node samt Unterbaum löschen
- `GET /api/v1/nodes/{node}/subtree` — Node + Nachfahren als Baum (`max_depth` 1–10)
- `GET /api/v1/nodes/{node}/children` — direkte Kinder
- `GET /api/v1/nodes/{node}/ancestors` — Pfad von der Wurzel bis zum Node
- `POST /api/v1/nodes/{node}/move` — Node in einen anderen Teilbaum verschieben
- `GET|POST /api/v1/nodes/{node}/comments` — Kommentare lesen/anlegen
- `GET|POST|PUT|DELETE /api/v1/nodes/{node}/permissions` — Berechtigungen verwalten
- `POST /api/v1/batch/nodes` und `POST /api/v1/batch/nodes/tree` — bis zu 50 Nodes transaktional anlegen/ändern
- `GET /api/v1/user` — aktuellen Token-Inhaber ermitteln
- `GET|POST|DELETE /api/v1/tokens` — API-Tokens verwalten

## Fehlercodes

- `401` — Token fehlt oder ist ungültig
- `403` — Token hat keine passende Ability oder kein Recht auf den Node
- `404` — Ressource nicht gefunden (oder durch Node-Beschränkung verborgen)
- `422` — Validierungsfehler (Details im Response-Body)