Skip to content

Commit aa972f0

Browse files
committed
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.
1 parent f97b432 commit aa972f0

2 files changed

Lines changed: 137 additions & 12 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,15 @@
33
## [Unreleased]
44

55
### 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
615
- **Limit Parameter Support**: Added `limit` parameter to `search_files` and `filter_files` functions
716
- Allows restricting the maximum number of results returned
817
- `search_files` uses fd's native `--max-results` flag for efficiency

‎README.md‎

Lines changed: 128 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,17 @@ SQLite database operations with configurable read/write permissions:
4343
- **Safety features** - Query validation, write operation restrictions, clear error messages
4444
- **Standalone CLI** for testing and direct usage
4545

46+
### 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:
48+
- **Dynamic problem-solving** — break complex problems into discrete, adjustable thinking steps
49+
- **Thought revision** — revise earlier thoughts when understanding deepens (`isRevision` / `revisesThought`)
50+
- **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+
4657
## Prerequisites
4758

4859
### General Requirements
@@ -128,9 +139,6 @@ cd mcp-personal
128139
The easiest way to add MCP servers to Claude Code is using the CLI:
129140

130141
```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-
134142
# Add custom Python servers from this repository
135143
# IMPORTANT: Use -s user for personal tools you want available across all projects
136144
# Without -s flag, servers are only available in current directory and are temporary
@@ -140,16 +148,22 @@ cd /path/to/mcp-personal
140148
claude mcp add file-search -s user -- $(pwd)/mcp_fd_server.py
141149
claude mcp add fuzzy-search -s user -- $(pwd)/mcp_fuzzy_search.py
142150
claude mcp add sqlite -s user -- $(pwd)/mcp_sqlite_server.py
151+
claude mcp add sequential-thinking -s user -- $(pwd)/mcp_sequential_thinking.py
143152

144153
# Or use relative paths (also from project directory)
145154
claude mcp add file-search -s user -- ./mcp_fd_server.py
146155
claude mcp add fuzzy-search -s user -- ./mcp_fuzzy_search.py
147156
claude mcp add sqlite -s user -- ./mcp_sqlite_server.py
157+
claude mcp add sequential-thinking -s user -- ./mcp_sequential_thinking.py
148158

149159
# Using absolute paths (works from anywhere)
150160
claude mcp add file-search -s user -- /path/to/mcp-personal/mcp_fd_server.py
151161
claude mcp add fuzzy-search -s user -- /path/to/mcp-personal/mcp_fuzzy_search.py
152162
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
153167

154168
# Add SQLite server with write permissions enabled
155169
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
197211
"env": {
198212
"MCP_SQLITE_ALLOW_WRITES": "true"
199213
}
214+
},
215+
"sequential-thinking": {
216+
"command": "/path/to/mcp-personal/mcp_sequential_thinking.py",
217+
"env": {
218+
"DISABLE_THOUGHT_LOGGING": "false"
219+
}
200220
}
201221
}
202222
}
@@ -246,6 +266,12 @@ npx @modelcontextprotocol/inspector ./mcp_sqlite_server.py
246266

247267
# Test the SQLite server with write permissions
248268
npx @modelcontextprotocol/inspector ./mcp_sqlite_server.py -- --allow-writes
269+
270+
# Test the sequential thinking server
271+
npx @modelcontextprotocol/inspector ./mcp_sequential_thinking.py
272+
273+
# Test the sequential thinking server with thought logging disabled
274+
npx @modelcontextprotocol/inspector -e "DISABLE_THOUGHT_LOGGING=true" ./mcp_sequential_thinking.py
249275
```
250276

251277
This will:
@@ -441,6 +467,28 @@ The SQLite server also works as a standalone CLI tool:
441467
./mcp_sqlite_server.py query "SELECT sqlite_version()" :memory:
442468
```
443469

470+
### Sequential Thinking Server
471+
472+
#### As an MCP Server
473+
474+
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.
486+
487+
```bash
488+
# Run with thought logging disabled
489+
DISABLE_THOUGHT_LOGGING=true ./mcp_sequential_thinking.py
490+
```
491+
444492
## Multiline Search Mode
445493

446494
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).
11901238
}
11911239
```
11921240

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+
11931296
## Development
11941297

11951298
### Project Structure
11961299
```
11971300
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
1201-
├── tests/ # Test suite
1202-
│ ├── test_simple.py # Direct function tests
1203-
│ ├── test_fd_server.py # File search MCP integration tests
1204-
│ ├── test_fuzzy_search.py # Fuzzy search tests
1205-
│ ├── test_sqlite_server.py # SQLite server tests
1206-
│ └── test_cli.py # CLI interface tests
1301+
├── mcp_fd_server.py # File search MCP server
1302+
├── mcp_fuzzy_search.py # Fuzzy content search MCP server
1303+
├── mcp_sqlite_server.py # SQLite database MCP server
1304+
├── mcp_sequential_thinking.py # Sequential thinking MCP server
1305+
├── tests/ # Test suite
1306+
│ ├── test_simple.py # Direct function tests
1307+
│ ├── test_fd_server.py # File search MCP integration tests
1308+
│ ├── test_fuzzy_search.py # Fuzzy search tests
1309+
│ ├── test_sqlite_server.py # SQLite server tests
1310+
│ ├── test_sequential_thinking.py # Sequential thinking tests
1311+
│ └── test_cli.py # CLI interface tests
12071312
├── pyproject.toml # Project configuration
12081313
├── Makefile # Development commands
12091314
├── CLAUDE.md # Claude-specific instructions
@@ -1275,6 +1380,9 @@ Additionally uses:
12751380
- **ripgrep**: Extremely fast search tool that respects gitignore
12761381
- **fzf**: Command-line fuzzy finder (used in filter mode)
12771382

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+
12781386
## Security Considerations
12791387

12801388
### General
@@ -1308,6 +1416,11 @@ Additionally uses:
13081416
- Be extremely cautious with write permissions on production databases
13091417
- Consider using separate read-only database users when possible
13101418

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+
13111424
## Troubleshooting
13121425

13131426
### "Cannot find the `fd` binary"
@@ -1352,3 +1465,6 @@ This project is open source and available under the [MIT License](LICENSE).
13521465

13531466
### SQLite Server
13541467
- [SQLite](https://www.sqlite.org/) - Self-contained, serverless, zero-configuration SQL database engine
1468+
1469+
### Sequential Thinking Server
1470+
- [@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

Comments
 (0)