@gotza02/sequential-thinking 2026.2.23 → 2026.2.25

package/README.md

@@ -11,16 +11,41 @@ A comprehensive Model Context Protocol (MCP) server that empowers AI models with
 - **💾 Code Database:** Store and search reusable code snippets.
 - **🛠️ File & Code Tools:** Safe file operations and code analysis utilities.
 
-## Usage
+## Installation & Usage
 
-### Method 1: Using `npx` (Recommended)
+### Method 1: Using `npx` (No Install Required)
 
-Run the server directly without global installation. This is best for Claude Desktop or other MCP clients.
+Best for quick use without cloning the repo.
 
-#### Configuration for Claude Desktop (`claude_desktop_config.json`)
+```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 the **Web Search** features, you must provide at least one API key.
+To use this server with your AI client (Claude Desktop, Gemini CLI, etc.), add the following configuration to your client's config file.
 
+### 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": {
@@ -31,22 +56,56 @@ To use the **Web Search** features, you must provide at least one API key.
         "@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"
+        "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"
       }
     }
   }
 }
 ```
-*Note: You only need one of the search provider keys (Brave is recommended for general use).*
 
-### Method 2: Running Locally
+### 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.
+
+**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",
+        "THOUGHTS_STORAGE_PATH": "/absolute/path/to/thoughts.json"
+      }
+    }
+  }
+}
+```
 
-1.  **Install dependencies:** `npm install`
-2.  **Build:** `npm run build`
-3.  **Config:** Point to the built `dist/index.js` file.
+*Note: Replace `/absolute/path/to/...` with the actual full paths on your system.*
 
 ## 🧰 Complete Tool List
 
@@ -93,4 +152,4 @@ To use the **Web Search** features, you must provide at least one API key.
 
 ## License
 
-MIT
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotza02/sequential-thinking",
-  "version": "2026.2.23",
+  "version": "2026.2.25",
   "publishConfig": {
     "access": "public"
   },
@@ -18,10 +18,12 @@
   "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"
+    "dist",
+    "SYSTEM_INSTRUCTION.md"
   ],
   "scripts": {
     "build": "tsc",