Sequential Thinking Tool API

Sequential Thinking Tool API

A Node.js/TypeScript backend for managing sequential thinking sessions and thoughts, featuring robust input validation with Zod and a simple in-memory session store.

Table of Contents

• Installation
• Running the Server
• API Endpoints
  • Create Session
  • Post Thought
• Validation
• Example curl Commands
• Development

Installation

1. Clone the repository:

   git clone <your-repo-url>
   cd SQ
   

2. Install dependencies:

   npm install
   

Running the Server

Using ts-node (development)

npx ts-node src/api/httpServer.ts

Using npm script (if available)

npm run dev

Using compiled JavaScript

npx tsc
node dist/api/httpServer.js

The server will start on port 3000 by default, or the port specified in your PORT environment variable.

API Endpoints

1. Create Session with First Thought

• Endpoint: POST /api/sessions
• Description: Creates a new session and stores the provided thought as the first thought in that session. Returns the new session ID and processed thought info.
• Request Body:

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

• Response:

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

2. Post Additional Thought

• Endpoint: POST /api/sessions/:sessionId/thoughts
• Description: Adds a thought to the specified session. Input is validated using Zod.
• Request Body:

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

• Response:

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

MCP SSE (Server-Sent Events)

Overview

The MCP SSE endpoint enables real-time, one-way streaming of server events to clients using Server-Sent Events (SSE). This is useful for clients that want to receive updates about session or thought processing as they happen, without polling the server.

Endpoint

• GET /api/mcp/sse
• Description: Establishes a persistent SSE connection. The server will push events to the client as they occur.
• Response:
  • Content-Type: text/event-stream
  • Events are sent as lines beginning with data:, followed by a JSON-encoded event object.

Example curl Command

curl -N http://localhost:3000/api/mcp/sse

Example Event Response

data: {"event":"thoughtProcessed","sessionId":"...","thoughtNumber":1,"message":"Thought processed successfully."}

Usage Notes

• Keep the connection open to continue receiving events.
• Each event is a JSON object. Handle each event as it arrives on the client side.
• If you need to listen for events for a specific session, include query parameters as supported by your implementation (e.g., /api/mcp/sse?sessionId=...).

Validation

All POST requests to /thoughts are validated using Zod. Invalid requests will return a 400 status and a list of validation errors.

User Flow: Session Created on First Thought

1. User sends their first thought to /api/sessions

   • The server creates a new session and stores the first thought.
   • Returns the new sessionId and processed thought info.

   Example 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
     }'
   

   Example response:

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

2. User sends additional thoughts to /api/sessions/:sessionId/thoughts

   • The server adds the thought to the existing session.

   Example 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
     }'
   

   Example response:

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

Example Error Response (invalid input)

{
  "errors": [
    {
      "path": ["thought"],
      "message": "Thought cannot be empty"
    }
  ]
}

Development

• TypeScript configuration is in tsconfig.json.
• Zod schemas are in src/types.ts.
• Validation middleware is in src/api/validationMiddleware.ts.
• Main server logic is in src/api/httpServer.ts.

License

MIT