@gotza02/sequential-thinking 2026.2.25 → 2026.2.27

package/README.md

@@ -4,13 +4,15 @@ A comprehensive Model Context Protocol (MCP) server that empowers AI models with
 
 ## Features
 
-- **🧠 Sequential Thinking:** Structured reasoning engine with block-based context management (Analysis -> Planning -> Execution -> Observation).
+- **🧠 Sequential Thinking Engine:** A structured reasoning system that forces the AI to think before acting, using a rigorous `Analysis -> Planning -> Execution -> Observation` loop.
 - **🌐 Web Research:** Built-in web search (Brave, Exa, Google) and webpage reading with ad-blocking/markdown conversion.
 - **🕸️ Project Knowledge Graph:** Automatically scans and maps code dependencies (imports/exports) to understand project architecture.
-- **📝 Persistent Notes:** Save and retrieve long-term project notes.
-- **💾 Code Database:** Store and search reusable code snippets.
+- **📝 Persistent Notes:** Save and retrieve long-term project notes and facts.
+- **💾 Code Database:** Store and search reusable code snippets and architectural patterns.
 - **🛠️ File & Code Tools:** Safe file operations and code analysis utilities.
 
+---
+
 ## Installation & Usage
 
 ### Method 1: Using `npx` (No Install Required)
@@ -35,9 +37,11 @@ If you have cloned this repository, we provide a `smartagent` script for easy ex
     ./smartagent
     ```
 
+---
+
 ## Client Configuration
 
-To use this server with your AI client (Claude Desktop, Gemini CLI, etc.), add the following configuration to your client's config file.
+To use this server with your AI client (Claude Desktop, Gemini CLI, etc.), add the following configuration.
 
 ### 1. Claude Desktop
 
@@ -56,7 +60,13 @@ To use this server with your AI client (Claude Desktop, Gemini CLI, etc.), add t
         "@gotza02/sequential-thinking"
       ],
       "env": {
-        "BRAVE_API_KEY": "your_brave_api_key_here"
+        "BRAVE_API_KEY": "your_brave_api_key_here",
+        "EXA_API_KEY": "your_exa_api_key_here",
+        "GOOGLE_SEARCH_API_KEY": "your_google_api_key",
+        "GOOGLE_SEARCH_CX": "your_google_cx_id",
+        "THOUGHTS_STORAGE_PATH": "/absolute/path/to/thoughts.json",
+        "NOTES_STORAGE_PATH": "/absolute/path/to/notes.json",
+        "DISABLE_THOUGHT_LOGGING": "false"
       }
     }
   }
@@ -73,7 +83,13 @@ To use this server with your AI client (Claude Desktop, Gemini CLI, etc.), add t
         "/absolute/path/to/thinking/dist/index.js"
       ],
       "env": {
-        "BRAVE_API_KEY": "your_brave_api_key_here"
+        "BRAVE_API_KEY": "your_brave_api_key_here",
+        "EXA_API_KEY": "your_exa_api_key_here",
+        "GOOGLE_SEARCH_API_KEY": "your_google_api_key",
+        "GOOGLE_SEARCH_CX": "your_google_cx_id",
+        "THOUGHTS_STORAGE_PATH": "/absolute/path/to/thoughts.json",
+        "NOTES_STORAGE_PATH": "/absolute/path/to/notes.json",
+        "DISABLE_THOUGHT_LOGGING": "false"
       }
     }
   }
@@ -82,7 +98,7 @@ To use this server with your AI client (Claude Desktop, Gemini CLI, etc.), add t
 
 ### 2. Gemini CLI
 
-If you are using a Gemini CLI tool that supports MCP (often via a `config.json` or `mcp_config.json`), use the setup below.
+For Gemini CLI tools that support MCP (often via a `config.json` or `mcp_config.json`):
 
 **Config File Location:**
 - Typically `~/.gemini/config.json` or check your specific CLI's documentation.
@@ -98,46 +114,84 @@ If you are using a Gemini CLI tool that supports MCP (often via a `config.json`
       ],
       "env": {
         "BRAVE_API_KEY": "your_brave_api_key_here",
-        "THOUGHTS_STORAGE_PATH": "/absolute/path/to/thoughts.json"
+        "EXA_API_KEY": "your_exa_api_key_here",
+        "GOOGLE_SEARCH_API_KEY": "your_google_api_key",
+        "GOOGLE_SEARCH_CX": "your_google_cx_id",
+        "THOUGHTS_STORAGE_PATH": "/absolute/path/to/thoughts.json",
+        "NOTES_STORAGE_PATH": "/absolute/path/to/notes.json",
+        "DISABLE_THOUGHT_LOGGING": "false"
       }
     }
   }
 }
 ```
-
 *Note: Replace `/absolute/path/to/...` with the actual full paths on your system.*
 
+---
+
+## 🧠 How to Use Sequential Thinking
+
+This server forces a "Thick Thinking" approach. The AI should not just execute tools randomly but follow a strict cognitive loop.
+
+### The Core Loop (Interleaved Thinking)
+
+The correct workflow for solving complex problems is:
+
+1.  **🔍 Analysis:** Understand the user's request, break it down, and identify what is missing.
+2.  **📋 Planning:** Decide *exactly* which tool to call next and why.
+3.  **⚡ Execution:** Declare the intent to call a tool (e.g., "I will read file X").
+4.  **[Tool Call]**: The actual MCP tool (e.g., `read_file`, `web_search`) is executed.
+5.  **👁️ Observation:** Analyze the *output* of the tool. Did it work? What did we learn?
+6.  **🔄 Reflexion:** (Optional) Critique the progress. Are we on track?
+
+### Thought Types
+
+When using the `sequentialthinking` tool, you must specify a `thoughtType`:
+
+| Type | Description |
+| :--- | :--- |
+| **`analysis`** | Initial problem breakdown or re-evaluating the situation. |
+| **`planning`** | Formulating a plan or next steps. **ALWAYS plan before executing.** |
+| **`execution`** | Stating the action to be taken. Set `relatedToolCall` to the tool name. |
+| **`observation`** | analyzing tool output. **MANDATORY after every tool call.** |
+| **`hypothesis`** | Formulating a theory to test (e.g., "I suspect the bug is in auth.ts"). |
+| **`reflexion`** | Self-correction or review. Use this if stuck. |
+| **`solution`** | The final answer or completion of the task. |
+
+### Best Practices
+
+*   **One Step at a Time:** Do not chain 10 thoughts in one go. Think -> Tool -> Observe -> Think.
+*   **Use Blocks:** When switching topics (e.g., from "Research" to "Coding"), use `start_thinking_block` to reset context and avoid loop detection errors.
+*   **Branching:** If a solution fails, don't keep trying the same thing. Use the `branchFromThought` parameter to "fork" your thinking process from an earlier point and try a different approach.
+
+---
+
 ## 🧰 Complete Tool List
 
 ### 🧠 Core Thinking
-*   **`sequentialthinking`**: The main engine for problem-solving. Handles `analysis`, `planning`, `execution`, and `observation` steps.
-*   **`start_thinking_block`**: Start a new thinking context (e.g., switch from "Planning" to "Coding"). Helps prevent context pollution.
-*   **`get_thinking_blocks`**: View a summary of all discussion topics/blocks.
-*   **`summarize_history`**: Compress past thoughts to save token space.
+*   **`sequentialthinking`**: The main engine for problem-solving.
+*   **`start_thinking_block`**: Start a new thinking context/topic.
+*   **`summarize_history`**: Compress past thoughts to save context window.
 *   **`search_thoughts`**: Search through your thinking history.
 *   **`clear_thought_history`**: Reset the thinking state completely.
 
 ### 🌐 Web & Research (Requires API Keys)
-*   **`web_search`**: Search the internet.
-    *   *Requires:* `BRAVE_API_KEY` OR `EXA_API_KEY` OR (`GOOGLE_SEARCH_API_KEY` + `GOOGLE_SEARCH_CX`).
-*   **`fetch`**: Fetch raw content from a URL (GET/POST).
-*   **`read_webpage`**: Download a webpage and convert it to clean Markdown (removes ads/clutter).
+*   **`web_search`**: Search the internet (Brave, Exa, Google).
+*   **`read_webpage`**: Download a webpage and convert it to clean Markdown.
+*   **`fetch`**: Fetch raw content from a URL.
 
 ### 🕸️ Project Knowledge Graph
 *   **`build_project_graph`**: Scans the current directory to map file dependencies.
-*   **`force_rebuild_graph`**: Clears cache and rebuilds the graph from scratch.
-*   **`get_file_relationships`**: Shows what a specific file imports and what imports it.
+*   **`get_file_relationships`**: Shows imports/exports for a specific file.
 *   **`get_project_graph_summary`**: High-level stats of the project structure.
-*   **`get_project_graph_visualization`**: Generates a Mermaid diagram of the dependency graph.
+*   **`get_project_graph_visualization`**: Generates a Mermaid diagram.
 
 ### 📝 Notes & Memory
 *   **`manage_notes`**: Create, read, update, or delete persistent notes.
-*   **`list_notes`**: List all saved notes.
 *   **`add_code_snippet`**: Save a useful piece of code to the database.
-*   **`search_code_db`**: Find saved code snippets by description or tags.
+*   **`search_code_db`**: Find saved code snippets.
 
-### 💻 System & Coding
-*   (Include standard file system tools provided by the server context, typically `read_file`, `write_file`, etc., if exposed via this MCP, though often provided by the client itself. This server provides specialized graph/analysis tools.)
+---
 
 ## Configuration Variables
 
@@ -149,6 +203,7 @@ If you are using a Gemini CLI tool that supports MCP (often via a `config.json`
 | `GOOGLE_SEARCH_CX` | Google Custom Search Engine ID | `web_search` (Provider: Google) |
 | `THOUGHTS_STORAGE_PATH` | Path to save thinking history (default: `thoughts_history.json`) | Persistence |
 | `NOTES_STORAGE_PATH` | Path to save notes (default: `project_notes.json`) | Persistence |
+| `DISABLE_THOUGHT_LOGGING` | Set to `true` to hide thoughts in console output | Optional |
 
 ## License
 

package/package.json

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