@gotza02/sequential-thinking 2026.2.24 → 2026.2.26

package/README.md

@@ -4,23 +4,52 @@ 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.
 
-## Usage
+---
 
-### Method 1: Using `npx` (Recommended)
+## Installation & Usage
 
-Run the server directly without global installation. This is best for Claude Desktop or other MCP clients.
+### Method 1: Using `npx` (No Install Required)
 
-#### Configuration for Claude Desktop (`claude_desktop_config.json`)
+Best for quick use without cloning the repo.
 
-To use the **Web Search** features, you must provide at least one API key.
+```bash
+npx -y @gotza02/sequential-thinking
+```
+
+### Method 2: Running from Source (Local)
+
+If you have cloned this repository, we provide a `smartagent` script for easy execution.
+
+1.  **Install dependencies:**
+    ```bash
+    npm install
+    npm run build
+    ```
+2.  **Run directly:**
+    ```bash
+    ./smartagent
+    ```
+
+---
+
+## Client Configuration
 
+To use this server with your AI client (Claude Desktop, Gemini CLI, etc.), add the following configuration.
+
+### 1. Claude Desktop
+
+**Config File Location:**
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+**Configuration (NPX - Recommended):**
 ```json
 {
   "mcpServers": {
@@ -30,55 +59,122 @@ To use the **Web Search** features, you must provide at least one API key.
         "-y",
         "@gotza02/sequential-thinking"
       ],
+      "env": {
+        "BRAVE_API_KEY": "your_brave_api_key_here"
+      }
+    }
+  }
+}
+```
+
+**Configuration (Local Source):**
+```json
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/thinking/dist/index.js"
+      ],
+      "env": {
+        "BRAVE_API_KEY": "your_brave_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### 2. Gemini CLI
+
+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.
+
+**Configuration:**
+```json
+{
+  "mcpServers": {
+    "smartagent": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/thinking/dist/index.js"
+      ],
       "env": {
         "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"
       }
     }
   }
 }
 ```
-*Note: You only need one of the search provider keys (Brave is recommended for general use).*
+*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
 
-### Method 2: Running Locally
+*   **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.
 
-1.  **Install dependencies:** `npm install`
-2.  **Build:** `npm run build`
-3.  **Config:** Point to the built `dist/index.js` file.
+---
 
 ## 🧰 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
 
@@ -90,6 +186,7 @@ To use the **Web Search** features, you must provide at least one API key.
 | `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.24",
+  "version": "2026.2.26",
   "publishConfig": {
     "access": "public"
   },
@@ -18,7 +18,8 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "mcp-server-sequential-thinking": "dist/index.js"
+    "mcp-server-sequential-thinking": "dist/index.js",
+    "smartagent": "dist/index.js"
   },
   "files": [
     "dist",