Skip to main content
Glama

mcp-sequential-thinking-ts

by Axefield

MseeP.ai Security Assessment Badge

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.

Node Version TypeScript License: MIT

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

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

mcp-sequential-thinking-ts/ ├── src/ │ ├── server.ts # Main server implementation and MCP tools │ ├── models.ts # Data models with Zod validation │ ├── storage/ │ │ ├── index.ts # High-level storage API │ │ └── utils.ts # Shared utilities for storage operations │ ├── analysis.ts # Thought analysis and pattern detection │ ├── testing.ts # Test utilities and helper functions │ ├── utils.ts # Common utilities and helper functions │ └── logging.ts # Centralized logging configuration ├── bin/ │ ├── run-server.ts # CLI entry point │ └── debug-mcp.ts # Debug tool for MCP connections ├── tests/ │ ├── analysis.spec.ts # Tests for analysis functionality │ ├── models.spec.ts # Tests for data models │ └── storage.spec.ts # Tests for persistence layer ├── package.json ├── package-lock.json ├── tsconfig.json ├── tsconfig.build.json ├── vitest.config.ts ├── .gitignore ├── README.md ├── CHANGELOG.md ├── example.md └── LICENSE

Quick Start

Installation

  1. Clone the Repository

    git clone https://github.com/your-username/mcp-sequential-thinking-ts.git cd mcp-sequential-thinking-ts
  2. Install Dependencies

    # Using pnpm (recommended) pnpm install # Or using npm npm install # Or using yarn yarn install
  3. Build the Project

    pnpm build

Running the Server

  1. Development Mode

    # Run with hot reload pnpm dev
  2. Production Mode

    # Build first pnpm build # Then run node dist/bin/run-server.js
  3. Global Installation (Optional)

    # Install globally for CLI access npm install -g . # Then run from anywhere mcp-sequential-thinking

Testing

# Run all tests pnpm test # Run tests in watch mode pnpm test:watch # Run tests with coverage pnpm test --coverage

Claude Desktop Integration

Add to your Claude Desktop configuration (%APPDATA%\Claude\claude_desktop_config.json on Windows):

{ "mcpServers": { "sequential-thinking": { "command": "tsx", "args": [ "bin/run-server.ts" ] } } }

Alternatively, if you've built the project, you can use:

{ "mcpServers": { "sequential-thinking": { "command": "node", "args": [ "dist/bin/run-server.js" ] } } }

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 thought

  • thoughtNumber (number): Position in your sequence (e.g., 1 for first thought)

  • totalThoughts (number): Expected total thoughts in the sequence

  • nextThoughtNeeded (boolean): Whether more thoughts are needed after this one

  • stage (string): The thinking stage - must be one of:

    • "Problem Definition"

    • "Research"

    • "Analysis"

    • "Synthesis"

    • "Conclusion"

  • tags (array of strings, optional): Keywords or categories for your thought

  • axiomsUsed (array of strings, optional): Principles or axioms applied in your thought

  • assumptionsChallenged (array of strings, optional): Assumptions your thought questions or challenges

Examples:

// Example 1: First thought in a 5-thought sequence process_thought({ thought: "The problem of climate change requires analysis of multiple factors including emissions, policy, and technology adoption.", thoughtNumber: 1, totalThoughts: 5, nextThoughtNeeded: true, stage: "Problem Definition", tags: ["climate", "global policy", "systems thinking"], axiomsUsed: ["Complex problems require multifaceted solutions"], assumptionsChallenged: ["Technology alone can solve climate change"] }) // Example 2: Research stage thought process_thought({ thought: "Recent studies show that renewable energy costs have dropped 85% in the last decade, making them competitive with fossil fuels.", thoughtNumber: 2, totalThoughts: 5, nextThoughtNeeded: true, stage: "Research", tags: ["renewable energy", "cost analysis", "market trends"], axiomsUsed: ["Economic viability drives adoption"], assumptionsChallenged: ["Renewable energy is too expensive"] }) // Example 3: Analysis stage thought process_thought({ thought: "The data suggests that policy intervention is necessary to accelerate the transition, as market forces alone are insufficient.", thoughtNumber: 3, totalThoughts: 5, nextThoughtNeeded: true, stage: "Analysis", tags: ["policy analysis", "market failure", "intervention"], axiomsUsed: ["Market failures require policy intervention"], assumptionsChallenged: ["Free markets will solve environmental problems"] })

2. generate_summary

Generates a summary of your entire thinking process.

Example output:

{ "summary": { "totalThoughts": 5, "stages": { "Problem Definition": 1, "Research": 1, "Analysis": 1, "Synthesis": 1, "Conclusion": 1 }, "timeline": [ {"number": 1, "stage": "Problem Definition"}, {"number": 2, "stage": "Research"}, {"number": 3, "stage": "Analysis"}, {"number": 4, "stage": "Synthesis"}, {"number": 5, "stage": "Conclusion"} ] } }

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:

# Run the server directly npx tsx bin/run-server.ts # Or if installed globally mcp-sequential-thinking # Debug MCP connections npx tsx bin/debug-mcp.ts

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 reload

  • pnpm build - Build the project for production (ESM/CJS dual output)

  • pnpm test - Run the test suite

  • pnpm test:watch - Run tests in watch mode

  • pnpm lint - Run ESLint

  • pnpm lint:fix - Fix ESLint issues automatically

  • pnpm format - Format code with Prettier

  • pnpm 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

  1. MCP Connection Issues

    # Use the debug tool to test connections npx tsx bin/debug-mcp.ts
  2. Storage Permission Errors

    • Ensure the storage directory is writable

    • Check file permissions on the data directory

  3. TypeScript Build Errors

    # Clean and rebuild rm -rf dist node_modules pnpm install pnpm build
  4. Test 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 formatting

  • Async/Await: All I/O operations are asynchronous for better performance

  • Modern Tooling: Built with tsup, vitest, eslint, and prettier

  • 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.

We thank Arben for creating the original concept and implementation that inspired this TypeScript port.

License

MIT License

typescript sequential thinking mcp services

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Axefield/mcp-sequential-thinking-ts'

If you have feedback or need assistance with the MCP directory API, please join our Discord server