@gotza02/sequential-thinking 2026.2.22 → 2026.2.24

package/README.md

@@ -1,161 +1,96 @@
-# Sequential Thinking MCP (Extended) 🧠
+# @gotza02/sequential-thinking MCP Server
 
-Advanced MCP Server enabling AI to act as a Software Engineer with Deep Thinking, Codebase Graph Analysis, and Persistent Memory.
+A comprehensive Model Context Protocol (MCP) server that empowers AI models with **Sequential Thinking**, **Web Research**, **Project Knowledge Graph**, and **Persistent Memory** capabilities.
 
-## ✨ Key Features
-- **Deep Thinking:** Step-by-step reasoning with auto-correction (Loop Breaker).
-- **Code Intelligence:** Dependency graph mapping (`build_project_graph`) with **Incremental Caching** & surgical code editing.
-- **Memory:** Long-term project notes, reusable code database, and thought history.
-- **Research:** Integrated Web search (Brave/Exa) & webpage reading.
-- **REST API:** Built-in HTTP server wrapper for easy integration with web tools and external services.
+## Features
 
-## 🚀 Quick Setup
+- **🧠 Sequential Thinking:** Structured reasoning engine with block-based context management (Analysis -> Planning -> Execution -> Observation).
+- **🌐 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.
+- **🛠️ File & Code Tools:** Safe file operations and code analysis utilities.
 
-### 1. Installation
-**Option A: Run Temporarily (Recommended for testing)**
-```bash
-npx -y @gotza02/sequential-thinking
-```
+## Usage
 
-**Option B: Install Globally**
-```bash
-npm install -g @gotza02/sequential-thinking
-```
+### Method 1: Using `npx` (Recommended)
 
-### 2. Configuration (Gemini/Claude)
-Add this to your MCP settings (`~/.gemini/settings.json` or `claude_desktop_config.json`).
+Run the server directly without global installation. This is best for Claude Desktop or other MCP clients.
 
-**For npx usage:**
-```json
-{
-  "mcpServers": {
-    "smartagent": {
-      "command": "npx",
-      "args": ["-y", "@gotza02/sequential-thinking"],
-      "env": { "THOUGHTS_STORAGE_PATH": "thoughts.json" }
-    }
-  }
-}
-```
+#### Configuration for Claude Desktop (`claude_desktop_config.json`)
+
+To use the **Web Search** features, you must provide at least one API key.
 
-**For npm usage:**
-*(Find path with: `npm root -g`)*
 ```json
 {
   "mcpServers": {
-    "smartagent": {
-      "command": "node",
-      "args": ["/PATH/TO/node_modules/@gotza02/sequential-thinking/dist/index.js"]
+    "sequential-thinking": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@gotza02/sequential-thinking"
+      ],
+      "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"
+      }
     }
   }
 }
 ```
-
-## 🔑 Environment Variables
-| Variable | Description |
-|----------|-------------|
-| `THOUGHTS_STORAGE_PATH` | Path to save thought history (Required) |
-| `NOTES_STORAGE_PATH` | Path to save project notes |
-| `CODE_DB_PATH` | Path to save code snippets |
-| `BRAVE_API_KEY` | Optional: For Brave Search |
-| `EXA_API_KEY` | Optional: For Exa.ai Search |
-
-## 🛠️ Tools Summary
-- **Thinking:** `sequentialthinking`, `summarize_history`, `clear_thought_history`
-- **Code:** `build_project_graph`, `deep_code_analyze` (Context+Usages), `deep_code_edit`, `search_code` (Regex/Line Numbers)
-- **Memory:** `add_code_snippet`, `search_code_db`, `manage_notes`
-- **Web:** `web_search`, `read_webpage`, `fetch`
-- **System:** `read_file`, `write_file`, `edit_file`, `shell_execute`
-
----
-
-## 🌐 HTTP REST API (Wrapper)
-In addition to the standard MCP protocol, this server includes an Express-based HTTP wrapper for RESTful access.
-
-### Start the HTTP Server
-```bash
-export PORT=3000
-npm run start:http
-```
-
-### Key Endpoints
-- `GET /health` - Service health check.
-- `POST /api/thinking/thought` - Process a new reasoning step.
-- `GET /api/thinking/history` - Retrieve reasoning history.
-- `POST /api/graph/build` - Scan codebase and build dependency graph.
-- `GET /api/notes` - List and manage persistent project notes.
-
----
-
-## 🧪 Testing & Robustness
-This project is rigorously tested using **TestSprite** and **Vitest**.
-- **Current Status:** ✅ **100% Pass Rate** (10/10 core requirements).
-- **Test Isolation:** Graph tests now run in isolated temporary environments to prevent race conditions.
-- **Path Security:** Enhanced `validatePath` with symlink resolution (`realpathSync`) for stable operation in restricted environments like Termux/Android.
-- **Error Handling:** Improved HTTP status mapping and descriptive error reporting.
-
----
-
-## 🤖 Recommended System Instruction (The Ultimate Deep Engineer)
-
-Copy this into your AI's System Prompt to enable the Loop Breaker and Deep Thinking protocols:
-
-```markdown
-# 🤖 System Instruction: Ultimate Deep Engineer (Sequential Thinking Extended)
-
-You are a Senior AI Software Engineer equipped with the Sequential Thinking MCP Server (Extended Edition). Your mission is to provide the highest quality technical solutions through rigorous logic, deep codebase awareness, and autonomous execution.
-
-## 🧠 CORE MANDATE: Deepest Thinking Protocol
-- **NEVER solve complex queries immediately.** You MUST use the `sequentialthinking` tool to structure your reasoning.
-- **Atomic Analysis:** Use `thoughtType: 'analysis'` to break every request into atomic requirements and constraints before proposing solutions.
-- **Mandatory Reflexion:** Use `thoughtType: 'reflexion'` frequently to critique your own logic, identify potential edge cases, and challenge your assumptions.
-- **Tree of Thoughts:** For critical architectural decisions, use branching to explore multiple paths (Conservative vs. Aggressive) and evaluate them using `thoughtType: 'evaluation'`.
-- **Loop Breaker (Auto-Correction):**
-  - **Self-Monitoring:** If you detect yourself repeating a failed strategy or stuck in a loop -> **STOP**.
-  - **Mandatory Branching:** You MUST create a new branch (`branchFromThought`) to explore a *radically different* approach.
-  - **Explicit Statement:** State "Stuck detected. Branching to Strategy B..." before proceeding.
-- **Verified Completion:** Only set `nextThoughtNeeded: false` when the solution is definitive, verified, and follows project standards.
-
-## 🛠️ TOOL USAGE TRIGGERS (Context-Action Mapping)
-**You MUST follow these explicit triggers:**
-
-1.  **Unknown/New Project Context:**
-    - **Trigger:** Start of session or new task.
-    - **Action:** `build_project_graph` -> `read_file` (README/config).
-    - **Goal:** Map the territory before moving.
-
-2.  **Coding/Refactoring Tasks:**
-    - **Trigger:** Request to write or edit code.
-    - **Action:** `deep_code_analyze` (on target files) -> `sequentialthinking` (Plan) -> `deep_code_edit` or `edit_file`.
-    - **Constraint:** NEVER edit code without reading the file and its related context first.
-
-3.  **Debugging/Error Fixing:**
-    - **Trigger:** User reports a bug or error.
-    - **Action:** `read_file` (logs/code) OR `diagnose_error_screenshot` -> `sequentialthinking` (Hypothesis) -> `codebase_investigator` (Verification).
-    - **Constraint:** Do not guess. Evidence first.
-
-4.  **Unknown Libraries/Docs:**
-    - **Trigger:** Need to use a specific library/tool you are unsure about.
-    - **Action:** `web_search` -> `read_webpage` or `get_code_context_exa`.
-    - **Constraint:** Do not hallucinate APIs.
-
-## 💻 DEEP CODING WORKFLOW
-1.  **Discovery:** `build_project_graph` -> Identify entry points and core logic.
-2.  **Analysis:** `deep_code_analyze` -> Learn existing patterns, styles, and symbols.
-3.  **Planning:** `sequentialthinking` -> Draft a detailed implementation plan with reasoning.
-4.  **Execution:** `deep_code_edit` or `edit_file` -> Apply changes with precise reasoning.
-5.  **Verification:** `shell_execute` -> Run tests, build scripts, or linters to confirm correctness.
-
-## 🛡 SAFETY & PRECISION
-- **Surgical Edits:** Prefer `edit_file` or `deep_code_edit` over `write_file` for existing files to minimize risk.
-- **Shell Responsibility:** Explain the purpose of any modification command before running `shell_execute`.
-- **No Assumptions:** If a library or configuration is unknown, use `web_search` or `read_webpage` to ingest documentation before implementation.
-
-## 📝 PERSISTENT MEMORY
-- **Long-term Knowledge:** Use `manage_notes` to save architectural decisions, user preferences, project conventions, and "lessons learned" that must persist across sessions.
-- **Code Database:** Use `add_code_snippet` to store reusable patterns and `search_code_db` to retrieve them.
-- **Session Continuity:** Your thought history is saved. If you restart, review the history to maintain context.
-```
+*Note: You only need one of the search provider keys (Brave is recommended for general use).*
+
+### Method 2: Running Locally
+
+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.
+*   **`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).
+
+### 🕸️ 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_project_graph_summary`**: High-level stats of the project structure.
+*   **`get_project_graph_visualization`**: Generates a Mermaid diagram of the dependency graph.
+
+### 📝 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.
+
+### 💻 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
+
+| Variable | Description | Required For |
+| :--- | :--- | :--- |
+| `BRAVE_API_KEY` | Brave Search API Token | `web_search` (Provider: Brave) |
+| `EXA_API_KEY` | Exa.ai API Key | `web_search` (Provider: Exa) |
+| `GOOGLE_SEARCH_API_KEY` | Google Custom Search API Key | `web_search` (Provider: Google) |
+| `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 |
 
 ## License
-MIT - Developed by @gotza02/sequential-thinking
+
+MIT

package/SYSTEM_INSTRUCTION.md

@@ -0,0 +1,58 @@
+# System Instruction for `@gotza02/sequential-thinking`
+
+You are an advanced AI assistant augmented with a **Sequential Thinking Engine** and **Context-Aware Tools**. Your goal is to solve complex problems methodically, not just by guessing, but by rigorously planning, executing, and observing results.
+
+## 1. THE CORE PROTOCOL: Sequential Thinking
+For any non-trivial task (coding, debugging, research, complex analysis), you **MUST** use the `sequentialthinking` tool. Do not just output text; structure your thought process.
+
+**The Loop:**
+1.  **Analysis:** Understand the request. Break it down.
+2.  **Planning:** Decide specifically which tools to call.
+3.  **Execution:** Declare your intent to call a tool.
+4.  **[TOOL CALL]**: The system executes the tool.
+5.  **Observation:** Analyze the tool's output. **CRITICAL:** You must explicitly record what you learned from the tool output before moving on.
+
+**Parameters:**
+*   `thoughtType`: strict adherence to 'analysis', 'planning', 'execution', 'observation', 'solution'.
+*   `blockId`: Use a semantic ID (e.g., `debug-auth`, `research-mcp`) to group related thoughts. Change this ID when switching topics.
+
+## 2. TOOL USAGE STRATEGIES
+
+### A. Project Exploration (Codebase)
+*   **Trigger:** When asked to work on an existing project or understand code.
+*   **Action:**
+    1.  Call `build_project_graph` immediately to map the territory.
+    2.  Use `get_project_graph_summary` to identify key files.
+    3.  Use `get_file_relationships` to understand dependencies before modifying any file.
+    4.  **Never** edit code without understanding what depends on it.
+
+### B. Web Research (External Knowledge)
+*   **Trigger:** When you lack specific knowledge, need documentation, or current events.
+*   **Action:**
+    1.  Call `web_search` (Provider is auto-handled, but prefer Brave/Exa if detailed).
+    2.  **Do not** rely on snippets alone. If a result looks promising, use `read_webpage` to ingest the full content into your context.
+    3.  Synthesize the information in an `observation` thought.
+
+### C. Long-term Memory
+*   **Trigger:** When the user gives you constraints, preferences, or architectural decisions that matter for the future.
+*   **Action:** Call `manage_notes` (action: 'create' or 'update') to save this information. Check these notes (`list_notes`) at the start of new sessions.
+
+## 3. AUTOMATION RULES
+
+1.  **Stuck? Branch Out:** If you find yourself looping or failing 3 times, use `sequentialthinking` with `thoughtType: 'reflexion'` to critique your approach, then start a NEW `blockId` with a fresh strategy.
+2.  **Verify Before Solution:** Never declare a `solution` until you have verified it (e.g., by running a test, checking the file content, or validating the syntax).
+3.  **One Step at a Time:** Do not chain 10 tool calls in a row without thinking. The correct rhythm is: *Think -> Tool -> Observe -> Think*.
+
+## 4. EXAMPLE WORKFLOW
+
+**User:** "Fix the bug in the login page."
+
+**Model:**
+1.  `sequentialthinking(type='analysis', thought='I need to find the login page code.')`
+2.  `sequentialthinking(type='planning', thought='I will search for files named login.')`
+3.  `sequentialthinking(type='execution', relatedToolCall='glob')`
+4.  `glob(pattern='*login*')`
+5.  `sequentialthinking(type='observation', toolResult='Found src/auth/login.ts')`
+6.  `sequentialthinking(type='analysis', thought='Now I need to see who calls this file.')`
+7.  `get_file_relationships(filePath='src/auth/login.ts')`
+8.  ... (continues until fixed)

package/dist/graph.js

@@ -252,8 +252,24 @@ export class ProjectKnowledgeGraph {
                 }
                 // Handle: from .module import func OR from package.module import func
                 const fromImportMatches = content.matchAll(/^\s*from\s+([.a-zA-Z0-9_]+)\s+import/gm);
-                for (const match of fromImportMatches)
-                    imports.push(match[1]);
+                for (const match of fromImportMatches) {
+                    let imp = match[1];
+                    // Convert Python relative import to path (e.g. .module -> ./module)
+                    if (imp.startsWith('.')) {
+                        const matchDots = imp.match(/^(\.+)(.*)/);
+                        if (matchDots) {
+                            const dots = matchDots[1].length;
+                            const name = matchDots[2];
+                            if (dots === 1) {
+                                imp = `./${name}`;
+                            }
+                            else {
+                                imp = `${'../'.repeat(dots - 1)}${name}`;
+                            }
+                        }
+                    }
+                    imports.push(imp);
+                }
                 // 2. Python Symbols (Only top-level defs/classes to avoid nested methods)
                 const topLevelFuncMatches = content.matchAll(/^def\s+([a-zA-Z0-9_]+)/gm);
                 for (const match of topLevelFuncMatches)

package/dist/index.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { SequentialThinkingServer } from './lib.js';
@@ -13,9 +16,12 @@ import { registerNoteTools } from './tools/notes.js';
 import { registerCodingTools } from './tools/coding.js';
 import { registerCodeDbTools } from './tools/codestore.js';
 import { registerHumanTools } from './tools/human.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
 const server = new McpServer({
     name: "sequential-thinking-server",
-    version: "2026.2.6",
+    version: pkg.version,
 });
 const thinkingServer = new SequentialThinkingServer(process.env.THOUGHTS_STORAGE_PATH || 'thoughts_history.json', parseInt(process.env.THOUGHT_DELAY_MS || '0', 10));
 const knowledgeGraph = new ProjectKnowledgeGraph();
@@ -39,3 +45,11 @@ runServer().catch((error) => {
     console.error("Fatal error running server:", error);
     process.exit(1);
 });
+process.on('SIGINT', () => {
+    console.error("\nReceived SIGINT, shutting down...");
+    process.exit(0);
+});
+process.on('SIGTERM', () => {
+    console.error("\nReceived SIGTERM, shutting down...");
+    process.exit(0);
+});

package/dist/lib.js

@@ -81,16 +81,22 @@ export class SequentialThinkingServer {
         }
     }
     rebuildBlocks() {
+        const oldBlocksMap = new Map();
+        for (const b of this.blocks) {
+            oldBlocksMap.set(b.id, b);
+        }
+        this.blocks = [];
         const blockMap = new Map();
         for (const t of this.thoughtHistory) {
             const bid = t.blockId || 'default';
             if (!blockMap.has(bid)) {
+                const oldBlock = oldBlocksMap.get(bid);
                 const newBlock = {
                     id: bid,
-                    topic: t.thought.substring(0, 50),
-                    status: 'active',
+                    topic: oldBlock ? oldBlock.topic : t.thought.substring(0, 50),
+                    status: oldBlock ? oldBlock.status : 'active',
                     thoughts: [],
-                    createdAt: new Date().toISOString(),
+                    createdAt: oldBlock ? oldBlock.createdAt : new Date().toISOString(),
                     updatedAt: new Date().toISOString()
                 };
                 blockMap.set(bid, newBlock);
@@ -99,7 +105,13 @@ export class SequentialThinkingServer {
             blockMap.get(bid).thoughts.push(t);
         }
         if (this.blocks.length > 0) {
-            this.currentBlockId = this.blocks[this.blocks.length - 1].id;
+            // Ensure currentBlockId points to a valid block or the last one
+            if (!this.blocks.find(b => b.id === this.currentBlockId)) {
+                this.currentBlockId = this.blocks[this.blocks.length - 1].id;
+            }
+        }
+        else {
+            this.currentBlockId = null;
         }
     }
     rebuildBranches() {

package/dist/tools/codestore.js

@@ -8,44 +8,68 @@ export function registerCodeDbTools(server, db) {
         description: z.string().describe("What this code does and why it is useful"),
         tags: z.array(z.string()).optional().default([]).describe("Tags for categorization")
     }, async (args) => {
-        const snippet = await db.addSnippet(args);
-        return {
-            content: [{ type: "text", text: `Snippet saved with ID: ${snippet.id}` }]
-        };
+        try {
+            const snippet = await db.addSnippet(args);
+            return {
+                content: [{ type: "text", text: `Snippet saved with ID: ${snippet.id}` }]
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error adding snippet: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true
+            };
+        }
     });
     // 17. search_code_db
     server.tool("search_code_db", "Search the Code Database for existing snippets, patterns, or architectural knowledge.", {
         query: z.string().describe("Search query")
     }, async ({ query }) => {
-        const results = await db.searchSnippets(query);
-        const patterns = await db.listAllPatterns();
-        let output = `--- CODE DATABASE RESULTS ---\n\n`;
-        if (results.length > 0) {
-            output += `SNIPPETS FOUND:\n`;
-            results.forEach(s => {
-                output += `ID: ${s.id} | ${s.title} (${s.language})\nDesc: ${s.description}\nCode:\n\`\`\`\n${s.code}\n\`\`\`\n\n`;
-            });
-        }
-        const matchedPatterns = Object.entries(patterns).filter(([k, v]) => k.toLowerCase().includes(query.toLowerCase()) || v.toLowerCase().includes(query.toLowerCase()));
-        if (matchedPatterns.length > 0) {
-            output += `PATTERNS FOUND:\n`;
-            matchedPatterns.forEach(([name, desc]) => {
-                output += `- ${name}: ${desc}\n`;
-            });
+        try {
+            const results = await db.searchSnippets(query);
+            const patterns = await db.listAllPatterns();
+            let output = `--- CODE DATABASE RESULTS ---\n\n`;
+            if (results.length > 0) {
+                output += `SNIPPETS FOUND:\n`;
+                results.forEach(s => {
+                    output += `ID: ${s.id} | ${s.title} (${s.language})\nDesc: ${s.description}\nCode:\n\`\`\`\n${s.code}\n\`\`\`\n\n`;
+                });
+            }
+            const matchedPatterns = Object.entries(patterns).filter(([k, v]) => k.toLowerCase().includes(query.toLowerCase()) || v.toLowerCase().includes(query.toLowerCase()));
+            if (matchedPatterns.length > 0) {
+                output += `PATTERNS FOUND:\n`;
+                matchedPatterns.forEach(([name, desc]) => {
+                    output += `- ${name}: ${desc}\n`;
+                });
+            }
+            if (results.length === 0 && matchedPatterns.length === 0) {
+                output += "No results found in the Code Database.";
+            }
+            return { content: [{ type: "text", text: output }] };
         }
-        if (results.length === 0 && matchedPatterns.length === 0) {
-            output += "No results found in the Code Database.";
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error searching code DB: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true
+            };
         }
-        return { content: [{ type: "text", text: output }] };
     });
     // 18. learn_architecture_pattern
     server.tool("learn_architecture_pattern", "Store a high-level architectural or logic pattern in the Code DB (e.g., 'auth-flow', 'error-handling-strategy').", {
         name: z.string().describe("Name of the pattern"),
         description: z.string().describe("Detailed description of the pattern and how it applies to this project")
     }, async ({ name, description }) => {
-        await db.learnPattern(name, description);
-        return {
-            content: [{ type: "text", text: `Pattern '${name}' learned and stored.` }]
-        };
+        try {
+            await db.learnPattern(name, description);
+            return {
+                content: [{ type: "text", text: `Pattern '${name}' learned and stored.` }]
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error learning pattern: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true
+            };
+        }
     });
 }

package/dist/tools/human.js

@@ -30,6 +30,34 @@ export class HumanInteractionManager {
             status: 'pending'
         };
         this.interactions.set(id, interaction);
+        // Handle timeout if specified
+        if (params.timeoutMs && params.timeoutMs > 0) {
+            setTimeout(() => {
+                const current = this.interactions.get(id);
+                if (current && current.status === 'pending') {
+                    if (current.defaultOption) {
+                        current.status = 'answered';
+                        current.response = current.defaultOption;
+                        current.respondedAt = new Date().toISOString();
+                        // Also resolve pending callbacks if any (future proofing)
+                        const callback = this.pendingCallbacks.get(id);
+                        if (callback) {
+                            callback.resolve(current.response);
+                            this.pendingCallbacks.delete(id);
+                        }
+                    }
+                    else {
+                        current.status = 'timeout';
+                        // Resolve pending callback with null or specific timeout error if supported
+                        const callback = this.pendingCallbacks.get(id);
+                        if (callback) {
+                            callback.resolve(null); // Null indicates timeout/no answer
+                            this.pendingCallbacks.delete(id);
+                        }
+                    }
+                }
+            }, params.timeoutMs);
+        }
         return interaction;
     }
     /**
@@ -173,133 +201,176 @@ Urgency Levels:
         options: z.array(z.string()).optional()
             .describe("Available options for 'choice' type questions"),
         defaultOption: z.string().optional()
-            .describe("Default option if human doesn't respond (for non-critical)")
-    }, async ({ question, questionType, urgency, context, options, defaultOption }) => {
-        // Validate options for choice type
-        if (questionType === 'choice' && (!options || options.length < 2)) {
+            .describe("Default option if human doesn't respond (for non-critical)"),
+        timeoutMs: z.number().int().min(1000).optional()
+            .describe("Timeout in milliseconds (default: no timeout)")
+    }, async ({ question, questionType, urgency, context, options, defaultOption, timeoutMs }) => {
+        try {
+            // Validate options for choice type
+            if (questionType === 'choice' && (!options || options.length < 2)) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Error: 'choice' question type requires at least 2 options"
+                        }],
+                    isError: true
+                };
+            }
+            const interaction = await manager.createInteraction({
+                questionType,
+                urgency,
+                question,
+                context,
+                options,
+                defaultOption,
+                timeoutMs
+            });
+            const formatted = manager.formatInteraction(interaction);
             return {
                 content: [{
                         type: "text",
-                        text: "Error: 'choice' question type requires at least 2 options"
-                    }],
+                        text: formatted + `\n\n⏳ Status: WAITING FOR HUMAN RESPONSE\n\nThe AI should pause this line of action until a response is received via 'respond_to_human' or 'get_pending_questions'.`
+                    }]
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error asking human: ${error instanceof Error ? error.message : String(error)}` }],
                 isError: true
             };
         }
-        const interaction = await manager.createInteraction({
-            questionType,
-            urgency,
-            question,
-            context,
-            options,
-            defaultOption
-        });
-        const formatted = manager.formatInteraction(interaction);
-        return {
-            content: [{
-                    type: "text",
-                    text: formatted + `\n\n⏳ Status: WAITING FOR HUMAN RESPONSE\n\nThe AI should pause this line of action until a response is received via 'respond_to_human' or 'get_pending_questions'.`
-                }]
-        };
     });
     // --- respond_to_human Tool ---
     server.tool("respond_to_human", "Provide a response to a pending human-in-the-loop question. Use this after receiving human input.", {
         interactionId: z.string().describe("The interaction ID from ask_human"),
         response: z.string().describe("The human's response to the question")
     }, async ({ interactionId, response }) => {
-        const interaction = manager.recordResponse(interactionId, response);
-        if (!interaction) {
+        try {
+            const interaction = manager.recordResponse(interactionId, response);
+            if (!interaction) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Error: No pending interaction found with ID "${interactionId}"`
+                        }],
+                    isError: true
+                };
+            }
             return {
                 content: [{
                         type: "text",
-                        text: `Error: No pending interaction found with ID "${interactionId}"`
-                    }],
+                        text: `✅ Response recorded for interaction ${interactionId}\n\n` +
+                            `Question: ${interaction.question}\n` +
+                            `Response: ${response}\n` +
+                            `Responded at: ${interaction.respondedAt}\n\n` +
+                            `The AI can now proceed based on this human decision.`
+                    }]
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error responding to human: ${error instanceof Error ? error.message : String(error)}` }],
                 isError: true
             };
         }
-        return {
-            content: [{
-                    type: "text",
-                    text: `✅ Response recorded for interaction ${interactionId}\n\n` +
-                        `Question: ${interaction.question}\n` +
-                        `Response: ${response}\n` +
-                        `Responded at: ${interaction.respondedAt}\n\n` +
-                        `The AI can now proceed based on this human decision.`
-                }]
-        };
     });
     // --- get_pending_questions Tool ---
     server.tool("get_pending_questions", "Get all pending human-in-the-loop questions that need responses.", {}, async () => {
-        const pending = manager.getPendingInteractions();
-        if (pending.length === 0) {
+        try {
+            const pending = manager.getPendingInteractions();
+            if (pending.length === 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "✅ No pending questions. All human interactions have been addressed."
+                        }]
+                };
+            }
+            let output = `📋 PENDING HUMAN INTERACTIONS (${pending.length})\n`;
+            output += `${'═'.repeat(60)}\n\n`;
+            for (const interaction of pending) {
+                output += manager.formatInteraction(interaction);
+                output += '\n';
+            }
             return {
                 content: [{
                         type: "text",
-                        text: "✅ No pending questions. All human interactions have been addressed."
+                        text: output
                     }]
             };
         }
-        let output = `📋 PENDING HUMAN INTERACTIONS (${pending.length})\n`;
-        output += `${'═'.repeat(60)}\n\n`;
-        for (const interaction of pending) {
-            output += manager.formatInteraction(interaction);
-            output += '\n';
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error getting pending questions: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true
+            };
         }
-        return {
-            content: [{
-                    type: "text",
-                    text: output
-                }]
-        };
     });
     // --- get_interaction_history Tool ---
     server.tool("get_interaction_history", "Get the history of human-AI interactions for context and learning.", {
         limit: z.number().int().min(1).max(100).default(20)
             .describe("Maximum number of interactions to return")
     }, async ({ limit }) => {
-        const history = manager.getHistory(limit);
-        if (history.length === 0) {
+        try {
+            const history = manager.getHistory(limit);
+            if (history.length === 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "No interaction history found."
+                        }]
+                };
+            }
+            let output = `📜 INTERACTION HISTORY (${history.length} most recent)\n`;
+            output += `${'═'.repeat(60)}\n\n`;
+            for (const interaction of history) {
+                const statusEmoji = {
+                    pending: '⏳',
+                    answered: '✅',
+                    timeout: '⏱️',
+                    skipped: '⏭️'
+                };
+                output += `${statusEmoji[interaction.status]} [${interaction.id}]\n`;
+                output += `   Type: ${interaction.questionType} | Urgency: ${interaction.urgency}\n`;
+                output += `   Q: ${interaction.question.substring(0, 80)}${interaction.question.length > 80 ? '...' : ''}\n`;
+                if (interaction.response) {
+                    output += `   A: ${interaction.response.substring(0, 80)}${interaction.response.length > 80 ? '...' : ''}\n`;
+                }
+                output += `   Time: ${interaction.timestamp}\n\n`;
+            }
             return {
                 content: [{
                         type: "text",
-                        text: "No interaction history found."
+                        text: output
                     }]
             };
         }
-        let output = `📜 INTERACTION HISTORY (${history.length} most recent)\n`;
-        output += `${'═'.repeat(60)}\n\n`;
-        for (const interaction of history) {
-            const statusEmoji = {
-                pending: '⏳',
-                answered: '✅',
-                timeout: '⏱️',
-                skipped: '⏭️'
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error getting history: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true
             };
-            output += `${statusEmoji[interaction.status]} [${interaction.id}]\n`;
-            output += `   Type: ${interaction.questionType} | Urgency: ${interaction.urgency}\n`;
-            output += `   Q: ${interaction.question.substring(0, 80)}${interaction.question.length > 80 ? '...' : ''}\n`;
-            if (interaction.response) {
-                output += `   A: ${interaction.response.substring(0, 80)}${interaction.response.length > 80 ? '...' : ''}\n`;
-            }
-            output += `   Time: ${interaction.timestamp}\n\n`;
         }
-        return {
-            content: [{
-                    type: "text",
-                    text: output
-                }]
-        };
     });
     // --- clear_old_interactions Tool ---
     server.tool("clear_old_interactions", "Clear old interaction history to free up memory.", {
         hoursOld: z.number().int().min(1).default(24)
             .describe("Clear interactions older than this many hours")
     }, async ({ hoursOld }) => {
-        const cleared = manager.clearOldInteractions(hoursOld);
-        return {
-            content: [{
-                    type: "text",
-                    text: `🗑️ Cleared ${cleared} interactions older than ${hoursOld} hours.`
-                }]
-        };
+        try {
+            const cleared = manager.clearOldInteractions(hoursOld);
+            return {
+                content: [{
+                        type: "text",
+                        text: `🗑️ Cleared ${cleared} interactions older than ${hoursOld} hours.`
+                    }]
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Error clearing interactions: ${error instanceof Error ? error.message : String(error)}` }],
+                isError: true
+            };
+        }
     });
 }

package/dist/tools/notes.js

@@ -14,22 +14,25 @@ export function registerNoteTools(server, notesManager) {
     }, async ({ action, title, content, tags, searchQuery, noteId, priority, expiresAt, includeExpired }) => {
         try {
             switch (action) {
-                case 'add':
+                case 'add': {
                     if (!title || !content) {
                         return { content: [{ type: "text", text: "Error: 'title' and 'content' are required for add action." }], isError: true };
                     }
                     const newNote = await notesManager.addNote(title, content, tags, priority, expiresAt);
                     return { content: [{ type: "text", text: `Note added successfully.\nID: ${newNote.id} (Priority: ${newNote.priority})` }] };
-                case 'list':
+                }
+                case 'list': {
                     const notes = await notesManager.listNotes(undefined, includeExpired);
                     return { content: [{ type: "text", text: JSON.stringify(notes, null, 2) }] };
-                case 'search':
+                }
+                case 'search': {
                     if (!searchQuery) {
                         return { content: [{ type: "text", text: "Error: 'searchQuery' is required for search action." }], isError: true };
                     }
                     const searchResults = await notesManager.searchNotes(searchQuery);
                     return { content: [{ type: "text", text: searchResults.length > 0 ? JSON.stringify(searchResults, null, 2) : "No matching notes found." }] };
-                case 'update':
+                }
+                case 'update': {
                     if (!noteId) {
                         return { content: [{ type: "text", text: "Error: 'noteId' is required for update action." }], isError: true };
                     }
@@ -38,12 +41,14 @@ export function registerNoteTools(server, notesManager) {
                         return { content: [{ type: "text", text: `Error: Note with ID ${noteId} not found.` }], isError: true };
                     }
                     return { content: [{ type: "text", text: `Note updated successfully.` }] };
-                case 'delete':
+                }
+                case 'delete': {
                     if (!noteId) {
                         return { content: [{ type: "text", text: "Error: 'noteId' is required for delete action." }], isError: true };
                     }
                     const deleted = await notesManager.deleteNote(noteId);
                     return { content: [{ type: "text", text: deleted ? "Note deleted successfully." : `Error: Note with ID ${noteId} not found.` }], isError: !deleted };
+                }
                 default:
                     return { content: [{ type: "text", text: `Error: Unknown action '${action}'` }], isError: true };
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotza02/sequential-thinking",
-  "version": "2026.2.22",
+  "version": "2026.2.24",
   "publishConfig": {
     "access": "public"
   },
@@ -21,7 +21,8 @@
     "mcp-server-sequential-thinking": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "SYSTEM_INSTRUCTION.md"
   ],
   "scripts": {
     "build": "tsc",
@@ -29,7 +30,9 @@
     "start:http": "node dist/http-server.js",
     "prepare": "npm run build",
     "watch": "tsc --watch",
-    "test": "vitest run --coverage"
+    "test": "vitest run --coverage",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write \"src/**/*.{ts,json}\""
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
@@ -50,6 +53,10 @@
     "@types/turndown": "^5.0.6",
     "@types/yargs": "^17.0.35",
     "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^8.57.0",
+    "@typescript-eslint/parser": "^7.1.1",
+    "@typescript-eslint/eslint-plugin": "^7.1.1",
+    "prettier": "^3.2.5",
     "shx": "^0.4.0",
     "vitest": "^3.2.4"
   }

package/dist/test_ts_req.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/test_ts_req.js

@@ -1,46 +0,0 @@
-import { ProjectKnowledgeGraph } from './graph.js';
-import * as fs from 'fs/promises';
-async function test() {
-    const tempFile = 'temp_req.ts';
-    await fs.writeFile(tempFile, 'import fs = require("fs");\nexport = fs;');
-    try {
-        const graph = new ProjectKnowledgeGraph();
-        await graph.build(process.cwd());
-        const rel = graph.getRelationships(tempFile);
-        console.log("Imports:", rel?.imports);
-        // Note: 'fs' is a built-in, so it might not be in 'imports' array unless resolved to a file.
-        // But ProjectKnowledgeGraph parser ADDS it to 'imports' list initially.
-        // finalizeFileNodes only keeps it if it resolves to a node OR if we assume internal logic keeps it?
-        // Wait, 'finalizeFileNodes' logic:
-        // for (const importPath of imports) {
-        //     resolved = resolvePath(...)
-        //     if (resolved && nodes.has(resolved)) { imports.push(resolved) }
-        // }
-        // It FILTERS out imports that don't resolve to files in the project!
-        // So 'fs' will be DROPPED.
-        // This makes verifying the PARSER hard via 'getRelationships'.
-        // However, 'symbols' are kept.
-        // 'import fs = require...' creates a symbol 'fs'?
-        // The parser only pushes to 'imports' or 'symbols'.
-        // Let's create a local file 'my_dep.ts' and import THAT.
-        await fs.writeFile('my_dep.ts', 'export const x = 1;');
-        await fs.writeFile(tempFile, 'import dep = require("./my_dep");');
-        await graph.build(process.cwd());
-        const rel2 = graph.getRelationships(tempFile);
-        console.log("Imports 2:", rel2?.imports);
-        if (rel2?.imports.some(i => i.includes('my_dep'))) {
-            console.log("PASS: Found 'my_dep' import");
-        }
-        else {
-            console.log("FAIL: 'my_dep' import missing");
-        }
-    }
-    finally {
-        await fs.unlink(tempFile);
-        try {
-            await fs.unlink('my_dep.ts');
-        }
-        catch { }
-    }
-}
-test();