@gotza02/sequential-thinking 2026.1.24 → 2026.1.26

package/README.md

@@ -24,70 +24,117 @@ When connected to this server, you should follow these guidelines to maximize pr
 4.  **Local Execution**: Use `shell_execute` to run tests, linters, or build commands to verify your changes. Always read files using `read_file` before attempting to write or modify them.
 5.  **Persistence**: The thinking process is saved automatically. You can resume previous sessions by reviewing the `thoughts_history.json` file if needed.
 
-## Tool
+## Detailed Tool Guide
 
-### sequentialthinking
+### 🧠 Cognitive Tools
 
-Facilitates a detailed, step-by-step thinking process for problem-solving and analysis.
+#### `sequentialthinking`
+The core engine for structured problem-solving. It forces a step-by-step analysis before arriving at a conclusion.
 
-**(See inputs above)**
+**Inputs:**
+- `thought` (string, required): The content of the current thinking step.
+- `thoughtNumber` (integer, required): Current step number (starts at 1).
+- `totalThoughts` (integer, required): Estimated total steps needed (can be adjusted dynamically).
+- `nextThoughtNeeded` (boolean, required): `true` if you need to think more, `false` only when the final answer is ready.
+- `thoughtType` (enum): The nature of the thought:
+  - `analysis`: Breaking down the problem.
+  - `generation`: Brainstorming solutions.
+  - `evaluation`: Weighing options (use with `score`).
+  - `reflexion`: Reviewing previous thoughts (use with `isRevision`).
+  - `selection`: Choosing a path.
+- `isRevision` (boolean): Set to `true` if you are correcting a previous mistake.
+- `revisesThought` (integer): The thought number you are fixing.
+- `branchFromThought` (integer): The parent thought number if creating a new reasoning branch.
+- `branchId` (string): A name for the new branch.
+
+**Best Practice:** Use this for ANY non-trivial task. Don't just answer; think first.
+
+### 🌐 External Knowledge
+
+#### `web_search`
+Retrieves real-time information from the internet.
 
-### web_search
+**Inputs:**
+- `query` (string, required): What you want to find.
+- `provider` (enum, optional):
+  - `brave`: General web search (Requires `BRAVE_API_KEY`).
+  - `exa`: AI-optimized search for deep content (Requires `EXA_API_KEY`).
+  - `google`: Google Custom Search (Requires `GOOGLE_SEARCH_API_KEY` & `GOOGLE_SEARCH_CX`).
 
-Search the web using Brave or Exa APIs.
+#### `fetch`
+Performs a direct HTTP request to a URL. Useful for getting raw HTML, JSON, or text from a specific source found via search.
 
 **Inputs:**
-- `query` (string): The search query.
-- `provider` (enum, optional): 'brave', 'exa', or 'google'.
-
-**Configuration:**
-Requires one of the following environment variable sets:
-- `BRAVE_API_KEY` (for Brave Search)
-- `EXA_API_KEY` (for Exa Search)
-- `GOOGLE_SEARCH_API_KEY` and `GOOGLE_SEARCH_CX` (for Google Custom Search)
+- `url` (string, required): The target URL.
+- `method`: `GET` (default), `POST`, `PUT`, `DELETE`.
+- `headers`: JSON object for headers (e.g., `{"Authorization": "Bearer..."}`).
+- `body`: Request body for POST/PUT.
 
-### fetch
+### 🏗 Codebase Intelligence
 
-Perform an HTTP request.
+#### `build_project_graph`
+**RUN THIS FIRST** when entering a new project. It scans the directory and builds a map of file dependencies using TypeScript AST analysis.
 
 **Inputs:**
-- `url` (string): URL to fetch.
-- `method` (string, optional): HTTP method (GET, POST, etc.).
-- `headers` (object, optional): Request headers.
-- `body` (string, optional): Request body.
+- `path` (string, optional): Root directory (defaults to `.`).
 
-### shell_execute
+#### `get_project_graph_summary`
+Returns high-level stats: total files and the top 5 most-referenced files. Use this to identify the "core" modules of the application.
 
-Execute a shell command. **Use with caution.**
+#### `get_file_relationships`
+Zoom in on a specific file to see its context.
 
 **Inputs:**
-- `command` (string): The command to run.
+- `filePath` (string, required): Path to the file (e.g., `src/index.ts`).
+**Returns:**
+- `imports`: What this file needs.
+- `importedBy`: Who relies on this file.
 
-### read_file / write_file
+### 🛠 System Operations
 
-Manage files on the local system.
+#### `read_file`
+Reads the content of a file. Always read a file before editing it to ensure you have the latest context.
 
 **Inputs:**
-- `path` (string): File path.
-- `content` (string, for write_file): Content to write.
+- `path` (string, required): File path.
 
-### build_project_graph
+#### `write_file`
+Creates or overwrites a file.
 
-Scan directory and build dependency graph.
+**Inputs:**
+- `path` (string, required): File path.
+- `content` (string, required): The full content to write.
+
+#### `shell_execute`
+Executes a shell command. Use for running tests (`npm test`), building (`npm run build`), or file operations (`ls`, `mkdir`).
 
 **Inputs:**
-- `path` (string, optional): Root directory to scan.
+- `command` (string, required): The command line string.
+**Warning:** Use with caution. Avoid commands that might delete data or expose secrets.
 
-### get_file_relationships
+## Recommended System Instruction
 
-Get imports and references for a specific file.
+To optimize your AI agent's performance with these tools, we recommend adding the following instructions to its system prompt:
 
-**Inputs:**
-- `filePath` (string): Path to the file.
+```text
+# Tools & Workflow
 
-### get_project_graph_summary
+1.  **Core Reasoning (`sequentialthinking`)**
+    *   **Mandatory Step:** For any complex query, bug fix, or feature request, you MUST start by using the `sequentialthinking` tool.
+    *   **Methodology:** Break the problem down. If your first hypothesis fails, use the tool again to revise your plan (`isRevision: true`).
+    *   **Goal:** Do not output code or final answers until you have a clear, verified plan.
 
-Get overview of project structure and most referenced files.
+2.  **Codebase Navigation**
+    *   **Initial Scan:** On start, run `build_project_graph`.
+    *   **Context:** Before reading a file, check its context with `get_file_relationships`. This prevents "hallucinating" imports or breaking existing dependencies.
+
+3.  **External Verification**
+    *   **Docs & Facts:** If you need to use a library you aren't 100% sure about, use `web_search` to check the documentation.
+
+4.  **Safety & Persistence**
+    *   **Files:** Always `read_file` before `write_file`.
+    *   **History:** Your thoughts are saved. If you get stuck, review your previous thoughts.
+```
 
 ## Usage
 
@@ -101,6 +148,11 @@ The Sequential Thinking tool is designed for:
 
 ## Configuration
 
+### Environment Variables
+- `THOUGHT_DELAY_MS`: (Optional) Milliseconds to wait before processing each thought. Default: `0`.
+- `DISABLE_THOUGHT_LOGGING`: (Optional) Set to `true` to hide colored logs.
+- `THOUGHTS_STORAGE_PATH`: (Optional) Path to history file. Default: `thoughts_history.json`.
+
 ### Usage with Claude Desktop
 
 Add this to your `claude_desktop_config.json`. You can configure API keys directly here:
@@ -146,6 +198,11 @@ npm run build
 npm test
 ```
 
+## Recent Updates (v2026.1.26)
+
+- **Rate Limiting**:
+  - Added `THOUGHT_DELAY_MS` environment variable to introduce a delay between thought steps. This helps prevent request flooding and rate limit issues.
+
 ## Recent Updates (v2026.1.24)
 
 - **Bug Fixes**:

package/dist/index.js

@@ -12,7 +12,7 @@ const server = new McpServer({
     name: "sequential-thinking-server",
     version: "2026.1.18",
 });
-const thinkingServer = new SequentialThinkingServer(process.env.THOUGHTS_STORAGE_PATH || 'thoughts_history.json');
+const thinkingServer = new SequentialThinkingServer(process.env.THOUGHTS_STORAGE_PATH || 'thoughts_history.json', parseInt(process.env.THOUGHT_DELAY_MS || '0', 10));
 const knowledgeGraph = new ProjectKnowledgeGraph();
 // --- Sequential Thinking Tool ---
 server.tool("sequentialthinking", `A detailed tool for dynamic and reflective problem-solving through thoughts.

package/dist/lib.js

@@ -7,9 +7,11 @@ export class SequentialThinkingServer {
     branches = {};
     disableThoughtLogging;
     storagePath;
-    constructor(storagePath = 'thoughts_history.json') {
+    delayMs;
+    constructor(storagePath = 'thoughts_history.json', delayMs = 0) {
         this.disableThoughtLogging = (process.env.DISABLE_THOUGHT_LOGGING || "").toLowerCase() === "true";
         this.storagePath = path.resolve(storagePath);
+        this.delayMs = delayMs;
         this.loadHistory();
     }
     loadHistory() {
@@ -97,6 +99,9 @@ export class SequentialThinkingServer {
     }
     async processThought(input) {
         try {
+            if (this.delayMs > 0) {
+                await new Promise(resolve => setTimeout(resolve, this.delayMs));
+            }
             this.addToMemory(input);
             await this.saveHistory();
             if (!this.disableThoughtLogging) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotza02/sequential-thinking",
-  "version": "2026.1.24",
+  "version": "2026.1.26",
   "publishConfig": {
     "access": "public"
   },