@gotza02/sequential-thinking 2026.1.24 → 2026.1.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +83 -36
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -24,70 +24,117 @@ When connected to this server, you should follow these guidelines to maximize pr
24
24
  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.
25
25
  5. **Persistence**: The thinking process is saved automatically. You can resume previous sessions by reviewing the `thoughts_history.json` file if needed.
26
26
 
27
- ## Tool
27
+ ## Detailed Tool Guide
28
28
 
29
- ### sequentialthinking
29
+ ### 🧠 Cognitive Tools
30
30
 
31
- Facilitates a detailed, step-by-step thinking process for problem-solving and analysis.
31
+ #### `sequentialthinking`
32
+ The core engine for structured problem-solving. It forces a step-by-step analysis before arriving at a conclusion.
32
33
 
33
- **(See inputs above)**
34
+ **Inputs:**
35
+ - `thought` (string, required): The content of the current thinking step.
36
+ - `thoughtNumber` (integer, required): Current step number (starts at 1).
37
+ - `totalThoughts` (integer, required): Estimated total steps needed (can be adjusted dynamically).
38
+ - `nextThoughtNeeded` (boolean, required): `true` if you need to think more, `false` only when the final answer is ready.
39
+ - `thoughtType` (enum): The nature of the thought:
40
+ - `analysis`: Breaking down the problem.
41
+ - `generation`: Brainstorming solutions.
42
+ - `evaluation`: Weighing options (use with `score`).
43
+ - `reflexion`: Reviewing previous thoughts (use with `isRevision`).
44
+ - `selection`: Choosing a path.
45
+ - `isRevision` (boolean): Set to `true` if you are correcting a previous mistake.
46
+ - `revisesThought` (integer): The thought number you are fixing.
47
+ - `branchFromThought` (integer): The parent thought number if creating a new reasoning branch.
48
+ - `branchId` (string): A name for the new branch.
49
+
50
+ **Best Practice:** Use this for ANY non-trivial task. Don't just answer; think first.
51
+
52
+ ### 🌐 External Knowledge
53
+
54
+ #### `web_search`
55
+ Retrieves real-time information from the internet.
34
56
 
35
- ### web_search
57
+ **Inputs:**
58
+ - `query` (string, required): What you want to find.
59
+ - `provider` (enum, optional):
60
+ - `brave`: General web search (Requires `BRAVE_API_KEY`).
61
+ - `exa`: AI-optimized search for deep content (Requires `EXA_API_KEY`).
62
+ - `google`: Google Custom Search (Requires `GOOGLE_SEARCH_API_KEY` & `GOOGLE_SEARCH_CX`).
36
63
 
37
- Search the web using Brave or Exa APIs.
64
+ #### `fetch`
65
+ Performs a direct HTTP request to a URL. Useful for getting raw HTML, JSON, or text from a specific source found via search.
38
66
 
39
67
  **Inputs:**
40
- - `query` (string): The search query.
41
- - `provider` (enum, optional): 'brave', 'exa', or 'google'.
42
-
43
- **Configuration:**
44
- Requires one of the following environment variable sets:
45
- - `BRAVE_API_KEY` (for Brave Search)
46
- - `EXA_API_KEY` (for Exa Search)
47
- - `GOOGLE_SEARCH_API_KEY` and `GOOGLE_SEARCH_CX` (for Google Custom Search)
68
+ - `url` (string, required): The target URL.
69
+ - `method`: `GET` (default), `POST`, `PUT`, `DELETE`.
70
+ - `headers`: JSON object for headers (e.g., `{"Authorization": "Bearer..."}`).
71
+ - `body`: Request body for POST/PUT.
48
72
 
49
- ### fetch
73
+ ### 🏗 Codebase Intelligence
50
74
 
51
- Perform an HTTP request.
75
+ #### `build_project_graph`
76
+ **RUN THIS FIRST** when entering a new project. It scans the directory and builds a map of file dependencies using TypeScript AST analysis.
52
77
 
53
78
  **Inputs:**
54
- - `url` (string): URL to fetch.
55
- - `method` (string, optional): HTTP method (GET, POST, etc.).
56
- - `headers` (object, optional): Request headers.
57
- - `body` (string, optional): Request body.
79
+ - `path` (string, optional): Root directory (defaults to `.`).
58
80
 
59
- ### shell_execute
81
+ #### `get_project_graph_summary`
82
+ Returns high-level stats: total files and the top 5 most-referenced files. Use this to identify the "core" modules of the application.
60
83
 
61
- Execute a shell command. **Use with caution.**
84
+ #### `get_file_relationships`
85
+ Zoom in on a specific file to see its context.
62
86
 
63
87
  **Inputs:**
64
- - `command` (string): The command to run.
88
+ - `filePath` (string, required): Path to the file (e.g., `src/index.ts`).
89
+ **Returns:**
90
+ - `imports`: What this file needs.
91
+ - `importedBy`: Who relies on this file.
65
92
 
66
- ### read_file / write_file
93
+ ### 🛠 System Operations
67
94
 
68
- Manage files on the local system.
95
+ #### `read_file`
96
+ Reads the content of a file. Always read a file before editing it to ensure you have the latest context.
69
97
 
70
98
  **Inputs:**
71
- - `path` (string): File path.
72
- - `content` (string, for write_file): Content to write.
99
+ - `path` (string, required): File path.
73
100
 
74
- ### build_project_graph
101
+ #### `write_file`
102
+ Creates or overwrites a file.
103
+
104
+ **Inputs:**
105
+ - `path` (string, required): File path.
106
+ - `content` (string, required): The full content to write.
75
107
 
76
- Scan directory and build dependency graph.
108
+ #### `shell_execute`
109
+ Executes a shell command. Use for running tests (`npm test`), building (`npm run build`), or file operations (`ls`, `mkdir`).
77
110
 
78
111
  **Inputs:**
79
- - `path` (string, optional): Root directory to scan.
112
+ - `command` (string, required): The command line string.
113
+ **Warning:** Use with caution. Avoid commands that might delete data or expose secrets.
80
114
 
81
- ### get_file_relationships
115
+ ## Recommended System Instruction
82
116
 
83
- Get imports and references for a specific file.
117
+ To optimize your AI agent's performance with these tools, we recommend adding the following instructions to its system prompt:
84
118
 
85
- **Inputs:**
86
- - `filePath` (string): Path to the file.
119
+ ```text
120
+ # Tools & Workflow
121
+
122
+ 1. **Core Reasoning (`sequentialthinking`)**
123
+ * **Mandatory Step:** For any complex query, bug fix, or feature request, you MUST start by using the `sequentialthinking` tool.
124
+ * **Methodology:** Break the problem down. If your first hypothesis fails, use the tool again to revise your plan (`isRevision: true`).
125
+ * **Goal:** Do not output code or final answers until you have a clear, verified plan.
87
126
 
88
- ### get_project_graph_summary
127
+ 2. **Codebase Navigation**
128
+ * **Initial Scan:** On start, run `build_project_graph`.
129
+ * **Context:** Before reading a file, check its context with `get_file_relationships`. This prevents "hallucinating" imports or breaking existing dependencies.
89
130
 
90
- Get overview of project structure and most referenced files.
131
+ 3. **External Verification**
132
+ * **Docs & Facts:** If you need to use a library you aren't 100% sure about, use `web_search` to check the documentation.
133
+
134
+ 4. **Safety & Persistence**
135
+ * **Files:** Always `read_file` before `write_file`.
136
+ * **History:** Your thoughts are saved. If you get stuck, review your previous thoughts.
137
+ ```
91
138
 
92
139
  ## Usage
93
140
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gotza02/sequential-thinking",
3
- "version": "2026.1.24",
3
+ "version": "2026.1.25",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },