Sequential Thinking MCP Server
A Model Context Protocol (MCP) server that facilitates structured, progressive thinking through defined stages. This tool helps break down complex problems into sequential thoughts, track the progression of your thinking process, and generate summaries.
Version 0.3.0 - Complete TypeScript port with enhanced features, improved CLI, and comprehensive testing.
Features
Structured Thinking Framework: Organizes thoughts through standard cognitive stages (Problem Definition, Research, Analysis, Synthesis, Conclusion)
Thought Tracking: Records and manages sequential thoughts with metadata
Related Thought Analysis: Identifies connections between similar thoughts
Progress Monitoring: Tracks your position in the overall thinking sequence
Summary Generation: Creates concise overviews of the entire thought process
Persistent Storage: Automatically saves your thinking sessions with thread-safety
Data Import/Export: Share and reuse thinking sessions
Extensible Architecture: Easily customize and extend functionality
Robust Error Handling: Graceful handling of edge cases and corrupted data
Type Safety: Comprehensive type annotations and validation with Zod
Prerequisites
Node.js 20 or higher
pnpm package manager (Install Guide)
Key Technologies
Zod: For data validation and serialization
JSON: For data storage and serialization
proper-lockfile: For thread-safe file access
@modelcontextprotocol/sdk: For Model Context Protocol integration
pino: For structured logging with pretty formatting
uuid: For unique identifier generation
chalk: For terminal styling and colors
boxen: For creating terminal boxes and borders
ora: For elegant terminal spinners
Project Structure
Quick Start
Installation
Clone the Repository
git clone https://github.com/your-username/mcp-sequential-thinking-ts.git cd mcp-sequential-thinking-tsInstall Dependencies
# Using pnpm (recommended) pnpm install # Or using npm npm install # Or using yarn yarn installBuild the Project
pnpm build
Running the Server
Development Mode
# Run with hot reload pnpm devProduction Mode
# Build first pnpm build # Then run node dist/bin/run-server.jsGlobal Installation (Optional)
# Install globally for CLI access npm install -g . # Then run from anywhere mcp-sequential-thinking
Testing
Claude Desktop Integration
Add to your Claude Desktop configuration (%APPDATA%\Claude\claude_desktop_config.json
on Windows):
Alternatively, if you've built the project, you can use:
How It Works
The server maintains a history of thoughts and processes them through a structured workflow. Each thought is validated using Zod schemas, categorized into thinking stages, and stored with relevant metadata in a thread-safe storage system. The server automatically handles data persistence, backup creation, and provides tools for analyzing relationships between thoughts.
Usage Guide
The Sequential Thinking server exposes five main tools:
1. process_thought
Records and analyzes a new thought in your sequential thinking process.
Parameters:
thought
(string): The content of your thoughtthoughtNumber
(number): Position in your sequence (e.g., 1 for first thought)totalThoughts
(number): Expected total thoughts in the sequencenextThoughtNeeded
(boolean): Whether more thoughts are needed after this onestage
(string): The thinking stage - must be one of:"Problem Definition"
"Research"
"Analysis"
"Synthesis"
"Conclusion"
tags
(array of strings, optional): Keywords or categories for your thoughtaxiomsUsed
(array of strings, optional): Principles or axioms applied in your thoughtassumptionsChallenged
(array of strings, optional): Assumptions your thought questions or challenges
Examples:
2. generate_summary
Generates a summary of your entire thinking process.
Example output:
3. clear_history
Resets the thinking process by clearing all recorded thoughts.
4. export_session
Exports the current thinking session to a file.
Parameters:
filePath
(string): Path to save the exported session
5. import_session
Imports a thinking session from a file.
Parameters:
filePath
(string): Path to the file to import
CLI Usage
The server can also be used as a standalone CLI tool:
Practical Applications
Decision Making: Work through important decisions methodically
Problem Solving: Break complex problems into manageable components
Research Planning: Structure your research approach with clear stages
Writing Organization: Develop ideas progressively before writing
Project Analysis: Evaluate projects through defined analytical stages
Strategic Planning: Organize business strategies through structured thinking
Academic Research: Structure research methodology and analysis
Creative Problem Solving: Apply systematic thinking to creative challenges
Development
Scripts
pnpm dev
- Run the server in development mode with hot reloadpnpm build
- Build the project for production (ESM/CJS dual output)pnpm test
- Run the test suitepnpm test:watch
- Run tests in watch modepnpm lint
- Run ESLintpnpm lint:fix
- Fix ESLint issues automaticallypnpm format
- Format code with Prettierpnpm prepare
- Install Husky git hooks
Type Safety
This project uses TypeScript with strict type checking and Zod for runtime validation. All external inputs are validated at runtime, and types are inferred from Zod schemas for compile-time safety.
Testing
Tests are written using Vitest and maintain 100% behavioral parity with the original Python implementation. The test suite covers:
Model validation and serialization
Storage operations with file locking
Analysis algorithms and pattern detection
MCP server tool implementations
Troubleshooting
Common Issues
MCP Connection Issues
# Use the debug tool to test connections npx tsx bin/debug-mcp.tsStorage Permission Errors
Ensure the storage directory is writable
Check file permissions on the data directory
TypeScript Build Errors
# Clean and rebuild rm -rf dist node_modules pnpm install pnpm buildTest Failures
# Run tests with verbose output pnpm test --reporter=verbose
Architecture & Design
This TypeScript implementation is built with modern Node.js best practices and provides a robust, type-safe foundation for sequential thinking workflows:
Type Safety: Full TypeScript support with Zod runtime validation
File Locking: Thread-safe operations using
proper-lockfile
Structured Logging: Comprehensive logging with
pino
and pretty formattingAsync/Await: All I/O operations are asynchronous for better performance
Modern Tooling: Built with
tsup
,vitest
,eslint
, andprettier
Enhanced CLI: Rich terminal experience with colors, progress indicators, and user-friendly output
Robust Error Handling: Comprehensive error handling with descriptive messages and recovery mechanisms
MCP Integration: Full Model Context Protocol support with
@modelcontextprotocol/sdk
Acknowledgments
This TypeScript implementation is based on the original Python version created by Arben Ademi.
Original Author: Arben Ademi arben.ademi@tuta.io
Original Repository: mcp-sequential-thinking
TypeScript Port: Axefield
We thank Arben for creating the original concept and implementation that inspired this TypeScript port.
License
MIT License
This server cannot be installed
typescript sequential thinking mcp services