You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit aa972f0
Browse filesBrowse the repository at this point in the historyBrowse files
docs: document sequential thinking MCP server in README and CHANGELOG
Thread the new sequential thinking server through every enumerating
section of the README (server list, claude mcp add examples, Claude
Desktop JSON snippet, MCP Inspector examples, Usage section, MCP Tools
documentation with parameter table and examples, Project Structure,
Architecture, Security Considerations, Acknowledgments) and add an
Unreleased entry to CHANGELOG.md covering the port, feature set, and
the modelcontextprotocol/servers#3856 string-coercion fix.
Also remove the stale `claude mcp add sequential-thinking -s user --
npx -y @modelcontextprotocol/server-sequential-thinking` suggestion,
since the current npm release (2025.12.18) rejects valid tool calls
from Claude Code due to the missing coercion fix. Users should now add
the local Python server via `./mcp_sequential_thinking.py` instead.
Copy file name to clipboardExpand all lines: CHANGELOG.md
+9Lines changed: 9 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,6 +3,15 @@
3
3
## [Unreleased]
4
4
5
5
### Added
6
+
-**Sequential Thinking MCP Server**: New `mcp_sequential_thinking.py` server — a single-file Python port of [`@modelcontextprotocol/server-sequential-thinking`](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking)
7
+
- Exposes a single tool, `sequentialthinking`, for dynamic, reflective problem-solving through a chain of thoughts
8
+
-**Thought revision** via `isRevision` / `revisesThought` — revise earlier steps when understanding deepens
9
+
-**Branching** via `branchFromThought` / `branchId` — explore alternative reasoning paths from any prior thought
10
+
-**Dynamic totals** — adjust `totalThoughts` up or down between calls, or extend past the initial estimate with `needsMoreThoughts`
11
+
-**String-coercion fix**: accepts string values for numeric (`thoughtNumber`, `totalThoughts`, `revisesThought`, `branchFromThought`) and boolean (`nextThoughtNeeded`, `isRevision`, `needsMoreThoughts`) fields. Incorporates the fix from [modelcontextprotocol/servers#3856](https://github.com/modelcontextprotocol/servers/issues/3856), which is not yet shipped in the npm release (`2025.12.18`), so Claude Code can call the tool reliably even when it serializes those fields as strings
12
+
-**Optional thought logging**: pretty-printed formatted thoughts are written to stderr by default; set `DISABLE_THOUGHT_LOGGING=true` to silence them while keeping structured tool output intact
13
+
-**Structured output**: each call returns `thoughtNumber`, `totalThoughts`, `nextThoughtNeeded`, active `branches`, and `thoughtHistoryLength`
14
+
- Tests at `tests/test_sequential_thinking.py` covering the happy path, revisions, branching, dynamic total adjustments, string-coerced inputs, and the `DISABLE_THOUGHT_LOGGING` env var
6
15
-**Limit Parameter Support**: Added `limit` parameter to `search_files` and `filter_files` functions
7
16
- Allows restricting the maximum number of results returned
8
17
-`search_files` uses fd's native `--max-results` flag for efficiency
### 4. Sequential Thinking Server (`mcp_sequential_thinking.py`)
47
+
Dynamic, reflective problem-solving through a structured chain of thoughts — a Python port of the official [`@modelcontextprotocol/server-sequential-thinking`](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking) server:
-**Branching** — explore alternative reasoning paths from any prior thought (`branchFromThought` / `branchId`)
51
+
-**Adjustable totals** — scale `totalThoughts` up or down mid-process, or extend past the initial estimate with `needsMoreThoughts`
52
+
-**Hypothesis generation & verification** — generate candidate solutions and verify them against the chain of thought
53
+
-**String-coercion fix** — accepts string inputs for numeric (`thoughtNumber`, `totalThoughts`) and boolean (`nextThoughtNeeded`, `isRevision`, `needsMoreThoughts`) fields, so it works with Claude Code out of the box. Includes the fix from [modelcontextprotocol/servers#3856](https://github.com/modelcontextprotocol/servers/issues/3856), which is not yet shipped in the npm release (`2025.12.18`)
54
+
-**Optional thought logging** — pretty-printed formatted thoughts go to stderr by default; set `DISABLE_THOUGHT_LOGGING=true` to silence them
55
+
-**Single tool**: `sequentialthinking`
56
+
46
57
## Prerequisites
47
58
48
59
### General Requirements
@@ -128,9 +139,6 @@ cd mcp-personal
128
139
The easiest way to add MCP servers to Claude Code is using the CLI:
129
140
130
141
```bash
131
-
# Add published npm servers (recommended to use -s user for global access)
132
-
claude mcp add sequential-thinking -s user -- npx -y @modelcontextprotocol/server-sequential-thinking
133
-
134
142
# Add custom Python servers from this repository
135
143
# IMPORTANT: Use -s user for personal tools you want available across all projects
136
144
# Without -s flag, servers are only available in current directory and are temporary
@@ -140,16 +148,22 @@ cd /path/to/mcp-personal
140
148
claude mcp add file-search -s user -- $(pwd)/mcp_fd_server.py
141
149
claude mcp add fuzzy-search -s user -- $(pwd)/mcp_fuzzy_search.py
142
150
claude mcp add sqlite -s user -- $(pwd)/mcp_sqlite_server.py
151
+
claude mcp add sequential-thinking -s user -- $(pwd)/mcp_sequential_thinking.py
143
152
144
153
# Or use relative paths (also from project directory)
145
154
claude mcp add file-search -s user -- ./mcp_fd_server.py
146
155
claude mcp add fuzzy-search -s user -- ./mcp_fuzzy_search.py
147
156
claude mcp add sqlite -s user -- ./mcp_sqlite_server.py
157
+
claude mcp add sequential-thinking -s user -- ./mcp_sequential_thinking.py
148
158
149
159
# Using absolute paths (works from anywhere)
150
160
claude mcp add file-search -s user -- /path/to/mcp-personal/mcp_fd_server.py
151
161
claude mcp add fuzzy-search -s user -- /path/to/mcp-personal/mcp_fuzzy_search.py
152
162
claude mcp add sqlite -s user -- /path/to/mcp-personal/mcp_sqlite_server.py
163
+
claude mcp add sequential-thinking -s user -- /path/to/mcp-personal/mcp_sequential_thinking.py
164
+
165
+
# Disable thought logging for the sequential thinking server
166
+
claude mcp add sequential-thinking -s user -e DISABLE_THOUGHT_LOGGING=true -- /path/to/mcp-personal/mcp_sequential_thinking.py
153
167
154
168
# Add SQLite server with write permissions enabled
155
169
claude mcp add sqlite -s user -- /path/to/mcp-personal/mcp_sqlite_server.py --allow-writes
@@ -197,6 +211,12 @@ For Claude Desktop, manually add servers to `~/Library/Application Support/Claud
Once configured, Claude can invoke `sequentialthinking` to work through problems in explicit, revisable steps. Natural-language prompts that trigger it:
475
+
476
+
- "Think step by step about how to design this caching layer"
477
+
- "Use sequential thinking to debug why this test is flaky"
478
+
- "Break this refactor down into thoughts and revise as you go"
479
+
- "Plan the migration with the sequential thinking tool, branching if you see alternatives"
480
+
481
+
Each call records one thought and returns the current state (`thoughtNumber`, `totalThoughts`, `nextThoughtNeeded`, active `branches`, and `thoughtHistoryLength`). Claude keeps calling the tool — revising, branching, or extending the total as needed — until `nextThoughtNeeded` is false.
482
+
483
+
#### Logging
484
+
485
+
By default, formatted thoughts are pretty-printed to **stderr** as they arrive (useful when running the server interactively or through the MCP Inspector). Set `DISABLE_THOUGHT_LOGGING=true` in the environment to silence the logging while keeping the structured tool output intact.
Both MCP servers support **multiline search mode** which changes the search behavior:
@@ -1190,20 +1238,77 @@ Create a new table with specified columns (requires write permissions).
1190
1238
}
1191
1239
```
1192
1240
1241
+
### Sequential Thinking Server Tools
1242
+
1243
+
#### `sequentialthinking`
1244
+
Record a single step in a dynamic, revisable chain of thoughts. Call repeatedly — revising, branching, or extending the total — until `nextThoughtNeeded` is false.
1245
+
1246
+
**Parameters:**
1247
+
-`thought` (required, string): The current thinking step. Can be an analytical step, a revision of a previous thought, a question, a hypothesis, or a verification.
1248
+
-`nextThoughtNeeded` (required, boolean): Whether another thought step is needed. Accepts `true`/`false` or the strings `"true"`/`"false"`.
1249
+
-`thoughtNumber` (required, integer ≥ 1): Current thought number in the sequence. Accepts numeric or numeric-string values.
1250
+
-`totalThoughts` (required, integer ≥ 1): Current estimate of total thoughts needed. May be adjusted up or down between calls. Accepts numeric or numeric-string values.
1251
+
-`isRevision` (optional, boolean): Whether this thought revises an earlier one.
1252
+
-`revisesThought` (optional, integer ≥ 1): When `isRevision` is true, the thought number being reconsidered.
1253
+
-`branchFromThought` (optional, integer ≥ 1): When branching, the thought number this branch diverges from.
1254
+
-`branchId` (optional, string): Identifier for the current branch.
1255
+
-`needsMoreThoughts` (optional, boolean): Set to true if you reach the end but realize more thoughts are needed.
1256
+
1257
+
**Output (structured):**
1258
+
-`thoughtNumber`, `totalThoughts`, `nextThoughtNeeded`, `branches` (list of active branch ids), `thoughtHistoryLength`.
1259
+
1260
+
**Example:**
1261
+
```python
1262
+
{
1263
+
"thought": "First, I need to map out the failure modes before proposing a fix.",
1264
+
"nextThoughtNeeded": true,
1265
+
"thoughtNumber": 1,
1266
+
"totalThoughts": 5
1267
+
}
1268
+
```
1269
+
1270
+
**Revision example:**
1271
+
```python
1272
+
{
1273
+
"thought": "Reconsidering thought 2 — the retry logic is actually the root cause, not the timeout.",
1274
+
"nextThoughtNeeded": true,
1275
+
"thoughtNumber": 4,
1276
+
"totalThoughts": 6,
1277
+
"isRevision": true,
1278
+
"revisesThought": 2
1279
+
}
1280
+
```
1281
+
1282
+
**Branching example:**
1283
+
```python
1284
+
{
1285
+
"thought": "Alternative approach: skip the cache entirely and hit the DB directly.",
1286
+
"nextThoughtNeeded": true,
1287
+
"thoughtNumber": 5,
1288
+
"totalThoughts": 7,
1289
+
"branchFromThought": 3,
1290
+
"branchId": "no-cache"
1291
+
}
1292
+
```
1293
+
1294
+
**Note:** All numeric and boolean fields also accept string inputs (e.g. `"1"`, `"true"`). This is the fix from [modelcontextprotocol/servers#3856](https://github.com/modelcontextprotocol/servers/issues/3856) and is what makes the server usable from Claude Code, which sometimes serializes those fields as strings.
1295
+
1193
1296
## Development
1194
1297
1195
1298
### Project Structure
1196
1299
```
1197
1300
mcp-personal/
1198
-
├── mcp_fd_server.py # File search MCP server
1199
-
├── mcp_fuzzy_search.py # Fuzzy content search MCP server
1200
-
├── mcp_sqlite_server.py # SQLite database MCP server
-**ripgrep**: Extremely fast search tool that respects gitignore
1276
1381
-**fzf**: Command-line fuzzy finder (used in filter mode)
1277
1382
1383
+
### Sequential Thinking Server
1384
+
Pure Python — no extra binaries required. Maintains an in-memory list of thoughts and a branch map for the lifetime of the process; state is not persisted between runs.
1385
+
1278
1386
## Security Considerations
1279
1387
1280
1388
### General
@@ -1308,6 +1416,11 @@ Additionally uses:
1308
1416
- Be extremely cautious with write permissions on production databases
1309
1417
- Consider using separate read-only database users when possible
1310
1418
1419
+
### Sequential Thinking Server
1420
+
- No filesystem, network, or database access
1421
+
- Stores thoughts in memory only; no persistence between process runs
1422
+
- Formatted thoughts are written to **stderr** by default — set `DISABLE_THOUGHT_LOGGING=true` if thoughts might contain sensitive content you don't want in the parent process's stderr stream
1423
+
1311
1424
## Troubleshooting
1312
1425
1313
1426
### "Cannot find the `fd` binary"
@@ -1352,3 +1465,6 @@ This project is open source and available under the [MIT License](LICENSE).
-[@modelcontextprotocol/server-sequential-thinking](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking) - The original TypeScript server this one is ported from
0 commit comments