API des Sequential Thinking Tools

Ein Node.js/TypeScript-Backend zum Verwalten sequenzieller Denksitzungen und Gedanken, mit robuster Eingabevalidierung mit Zod und einem einfachen In-Memory-Sitzungsspeicher.

Inhaltsverzeichnis

• Installation

• Ausführen des Servers

• API-Endpunkte

  • Sitzung erstellen

  • Gedanken zum Beitrag

• Validierung

• Beispiele für Curl-Befehle

• Entwicklung

Installation

1. Klonen Sie das Repository:

   git clone <your-repo-url> cd SQ

2. Installieren Sie Abhängigkeiten:

   npm install

Ausführen des Servers

Verwenden von ts-node (Entwicklung)

Verwenden eines npm-Skripts (falls verfügbar)

Verwenden von kompiliertem JavaScript

Der Server wird standardmäßig auf Port 3000 oder dem in Ihrer Umgebungsvariablen PORT angegebenen Port gestartet.

API-Endpunkte

1. Sitzung mit erstem Gedanken erstellen

• Endpunkt: POST /api/sessions

• Beschreibung: Erstellt eine neue Sitzung und speichert den eingegebenen Gedanken als ersten Gedanken in dieser Sitzung. Gibt die neue Sitzungs-ID und die verarbeiteten Gedankeninformationen zurück.

• Anforderungstext:

  { "thought": "string (required)", "thoughtNumber": 1, "totalThoughts": 3, "nextThoughtNeeded": true, "isRevision": false, // optional "revisesThought": 2, // optional "branchFromThought": 1, // optional "branchId": "string", // optional "needsMoreThoughts": false // optional }

• Antwort:

  { "sessionId": "<uuid>", "thoughtNumber": 1, "totalThoughts": 3, "nextThoughtNeeded": true, "branches": [], "thoughtHistoryLength": 1, "processedThought": "This is my first thought." }

2. Posten Sie zusätzliche Gedanken

• Endpunkt: POST /api/sessions/:sessionId/thoughts

• Beschreibung: Fügt der angegebenen Sitzung einen Gedanken hinzu. Die Eingabe wird mit Zod validiert.

• Anforderungstext:

  { "thought": "string (required)", "thoughtNumber": 2, "totalThoughts": 3, "nextThoughtNeeded": true, "isRevision": false, // optional "revisesThought": 1, // optional "branchFromThought": 1, // optional "branchId": "string", // optional "needsMoreThoughts": false // optional }

• Antwort:

  { "thoughtNumber": 2, "totalThoughts": 3, "nextThoughtNeeded": true, "branches": [], "thoughtHistoryLength": 2, "processedThought": "This is my second thought." }

MCP SSE (Server-Sent Events)

Überblick

Der MCP SSE-Endpunkt ermöglicht das Echtzeit-Streaming von Serverereignissen an Clients mithilfe von Server-Sent Events (SSE). Dies ist nützlich für Clients, die Updates zu Sitzungen oder Gedankenverarbeitung erhalten möchten, ohne den Server abzufragen.

Endpunkt

• GET /api/mcp/sse

• Beschreibung: Stellt eine dauerhafte SSE-Verbindung her. Der Server überträgt Ereignisse an den Client, sobald sie auftreten.

• Antwort:

  • Inhaltstyp: text/event-stream

  • Ereignisse werden als Zeilen gesendet, die mit data: beginnen, gefolgt von einem JSON-codierten Ereignisobjekt.

Beispiel für einen curl-Befehl

Beispiel einer Ereignisantwort

Verwendungshinweise

• Halten Sie die Verbindung offen, um weiterhin Ereignisse zu empfangen.

• Jedes Ereignis ist ein JSON-Objekt. Behandeln Sie jedes Ereignis, sobald es auf der Clientseite eintrifft.

• Wenn Sie auf Ereignisse für eine bestimmte Sitzung warten müssen, schließen Sie Abfrageparameter ein, die von Ihrer Implementierung unterstützt werden (z. B. /api/mcp/sse?sessionId=... ).

Validierung

Alle POST-Anfragen an /thoughts werden mit Zod validiert. Ungültige Anfragen geben den Status 400 und eine Liste mit Validierungsfehlern zurück.

Benutzerfluss: Sitzung beim ersten Gedanken erstellt

1. Der Benutzer sendet seinen ersten Gedanken an

   • Der Server erstellt eine neue Sitzung und speichert den ersten Gedanken.

   • Gibt die neue sessionId und die verarbeiteten Gedankeninformationen zurück.

   Beispiel-Curl:

   curl -X POST http://localhost:3000/api/sessions \ -H "Content-Type: application/json" \ -d '{ "thought": "This is my first thought.", "thoughtNumber": 1, "totalThoughts": 3, "nextThoughtNeeded": true }'

   Beispielantwort:

   { "sessionId": "abc123", "thoughtNumber": 1, "totalThoughts": 3, "nextThoughtNeeded": true, "branches": [], "thoughtHistoryLength": 1, "processedThought": "This is my first thought." }

2. Der Benutzer sendet zusätzliche Gedanken an

   • Der Server fügt den Gedanken der bestehenden Sitzung hinzu.

   Beispiel-Curl:

   curl -X POST http://localhost:3000/api/sessions/abc123/thoughts \ -H "Content-Type: application/json" \ -d '{ "thought": "This is my second thought.", "thoughtNumber": 2, "totalThoughts": 3, "nextThoughtNeeded": true }'

   Beispielantwort:

   { "thoughtNumber": 2, "totalThoughts": 3, "nextThoughtNeeded": true, "branches": [], "thoughtHistoryLength": 2, "processedThought": "This is my second thought." }

Beispiel einer Fehlerantwort (ungültige Eingabe)

Entwicklung

• Die TypeScript-Konfiguration befindet sich in tsconfig.json .

• Zod-Schemas befinden sich in src/types.ts .

• Die Validierungs-Middleware befindet sich in src/api/validationMiddleware.ts .

• Die Hauptserverlogik befindet sich in src/api/httpServer.ts .

Lizenz

MIT