Sequential Thinking Tool API

Sequential Thinking Tool API

A Node.js/TypeScript backend for managing sequential thinking sessions and thoughts, supporting three robust interfaces for agent and human use:

• STDIO (MCP Tool): For local tool/agent/CLI integration using the Model Context Protocol (MCP) over stdin/stdout.
• SSE (Server-Sent Events): For streaming tool use in LLMs, agents, or web clients—enabling real-time, stepwise output.
• REST API: For standard HTTP request/response workflows.

Input validation is handled with Zod, and the app is ready for containerized deployment (e.g., Render).

Table of Contents

• Installation
• Running the Server
• Interfaces & Usage
  • STDIO (MCP Tool)
  • SSE (Streaming Tool/LLM)
  • REST API
• Validation
• Development
• License

Installation

1. Clone the repository:
   git clone <your-repo-url> cd SQ
2. Install dependencies:
   npm install

Running the Server

Using ts-node (development)

Using npm script (if available)

Using compiled JavaScript

Using Docker

The server will start on port 3000 by default, or the port specified in your PORT environment variable. For Render or cloud deployment, ensure the PORT env is set or inherited.

Interfaces & Usage

STDIO (MCP Tool)

For local agent/LLM/CLI integration using Model Context Protocol over stdin/stdout. Start the server in MCP mode:

• The process will accept MCP-compliant JSON messages on stdin and emit responses on stdout.
• Example (JSON-RPC):
  { "jsonrpc": "2.0", "id": 1, "method": "call_tool", "params": { "name": "sequential_thinking", "arguments": { ... }}}
• Streamed or batched responses will be sent back as JSON.

SSE (Streaming Tool/LLM)

For LLMs, agents, or web clients that require real-time, incremental output.

• POST a thought to /api/sessions/:sessionId/thoughts.
• GET /api/sessions/:sessionId/thoughts/stream to receive a live stream of steps/thoughts as they are generated.
• Each SSE event is a JSON object:
  data: {"step":1,"content":"First step..."} data: {"step":2,"content":"Second step..."} data: {"done":true}
• Example (JavaScript):
  const es = new EventSource('https://sq-mcp.onrender.com/api/sessions/12345/thoughts/stream'); es.onmessage = e => console.log(JSON.parse(e.data));
• Useful for LLM tool wrappers, browser clients, or any agent needing streaming output.

REST API

Standard HTTP request/response endpoints for synchronous workflows.

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

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)

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.
• MCP/STDIO logic is in src/mcp/mcpServer.ts.
• Dockerfile is provided for containerized deployments.

License

MIT