npm package: @neomint-pst/controlled-sequential-thinking
Description: Sequential Thinking MCP server (fork) with controlled thought generation for structured problem-solving
Author: NeoMINT
Latest version: 0.1.0

# Controlled Sequential Thinking MCP Server

**NeoMINT Fork** - Forked from [MCP Sequential Thinking Server](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking)

An MCP server implementation that provides a tool for dynamic and reflective problem-solving through a structured thinking process, with enhanced control features for thought generation.

## Features

- Break down complex problems into manageable steps
- Revise and refine thoughts as understanding deepens
- Branch into alternative paths of reasoning
- Adjust the total number of thoughts dynamically
- Generate and verify solution hypotheses
- **NEW**: Force a specific total number of thoughts via CLI flag or environment variable
- **NEW**: Per-request step control - specify exact number of steps for individual requests
- **NEW**: Phase-based thinking - structure thoughts through predefined phases like brainstorm, analyze, refine

## Per-Request Step Control

You can now control the exact number of thinking steps on a per-request basis. When a user asks for a specific number of steps, the LLM can specify this in the tool call:

### Usage Examples

**User request**: "Think through this problem using exactly 10 steps"

**LLM tool call**:
```json
{
  "thought": "Let me start thinking about this problem systematically...",
  "thoughtNumber": 1, 
  "totalThoughts": 10,
  "requestedTotalThoughts": 10,
  "nextThoughtNeeded": true
}
```

**Alternative parameter names**:
- `requestedTotalThoughts: 10` (primary)
- `steps: 10` (alias)
- `numSteps: 10` (alias)

### Precedence Rules

The system uses this precedence order:
1. **Per-request parameters** (`requestedTotalThoughts`, `steps`, `numSteps`) - highest priority
2. **CLI flag** (`--force-total-thoughts`) - medium priority  
3. **Environment variable** (`FORCE_TOTAL_THOUGHTS`) - low priority
4. **Dynamic mode** (original behavior) - **When no overrides are provided, the system works naturally, allowing the LLM to adjust the number of thoughts as needed during the thinking process**

### Bounds and Safety

- Valid range: 1-200 steps
- Values outside this range are automatically clamped
- The system ensures robust execution even with enforcement enabled

## Phase-Based Thinking

The server now supports structured phase-based thinking, allowing you to guide the thinking process through predefined phases. This is useful for complex problems that benefit from different thinking modes at different stages.

### Available Phases

Each phase has a specific purpose and recommended step count range:

- **`brainstorm`** (2-10 steps): Generate diverse ideas without judgment
- **`analyze`** (3-8 steps): Evaluate and examine ideas critically
- **`synthesize`** (2-6 steps): Combine insights into coherent understanding
- **`critique`** (2-5 steps): Identify flaws, gaps, and weaknesses
- **`refine`** (2-5 steps): Improve and polish based on analysis
- **`revise`** (2-5 steps): Revise and update based on feedback
- **`validate`** (1-3 steps): Verify correctness and completeness
- **`plan`** (3-7 steps): Create strategic approach and steps
- **`explore`** (2-10 steps): Open-ended investigation and discovery
- **`conclude`** (1-3 steps): Summarize findings and outcomes

### Phase Mode Usage

#### Via CLI

```bash
# Simple phase sequence
npx @neomint-pst/controlled-sequential-thinking --phases "brainstorm,analyze,refine"

# Combined with enforced step count (15 steps distributed across phases)
npx @neomint-pst/controlled-sequential-thinking --phases "brainstorm,analyze,conclude" --force-total-thoughts 15
```

#### Via Environment Variables

```bash
FORCE_PHASES="explore,validate,conclude" npx @neomint-pst/controlled-sequential-thinking
```

#### Per-Request Control

The LLM can specify phases in the tool call:

```json
{
  "requestedPhases": "brainstorm,analyze,refine",
  "thought": "Let me start brainstorming solutions...",
  "thoughtNumber": 1,
  "totalThoughts": 12,
  "nextThoughtNeeded": true
}
```

### Phase Mode Response

When using phase mode, the response includes additional phase context:

```json
{
  "currentPhase": "brainstorm",
  "phaseIndex": 0,
  "totalPhases": 3,
  "phaseThoughtNumber": 1,
  "phaseProgress": "1/10",
  "phasePrompt": "Generate creative and diverse ideas...",
  "nextPhase": "analyze"
}
```

### Combined Mode

You can combine phase mode with enforced step counts. The system will distribute the total steps across the specified phases:

```bash
# 20 steps distributed across 4 phases
npx @neomint-pst/controlled-sequential-thinking --phases "plan,implement,validate,conclude" --force-total-thoughts 20
```

## Tool

### sequential_thinking

Facilitates a detailed, step-by-step thinking process for problem-solving and analysis.

**Inputs:**
- `thought` (string): The current thinking step
- `nextThoughtNeeded` (boolean): Whether another thought step is needed
- `thoughtNumber` (integer): Current thought number
- `totalThoughts` (integer): Estimated total thoughts needed
- `isRevision` (boolean, optional): Whether this revises previous thinking
- `revisesThought` (integer, optional): Which thought is being reconsidered
- `branchFromThought` (integer, optional): Branching point thought number
- `branchId` (string, optional): Branch identifier
- `needsMoreThoughts` (boolean, optional): If more thoughts are needed
- `requestedPhases` (string, optional): Comma-separated phase names (e.g., "brainstorm,analyze,refine")
- `phases` (array, optional): Array of phase definitions or phase names
- `phaseTransition` (boolean, optional): Explicitly move to next phase

## Usage

The Sequential Thinking tool is designed for:
- Breaking down complex problems into steps
- Planning and design with room for revision
- Analysis that might need course correction
- Problems where the full scope might not be clear initially
- Tasks that need to maintain context over multiple steps
- Situations where irrelevant information needs to be filtered out

## Installation & Configuration

### NPX Usage (Recommended)

You can use this server directly with `npx`:

```bash
npx @neomint-pst/controlled-sequential-thinking
```

### Usage with MCP Clients

#### Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "controlled-sequential-thinking": {
      "command": "npx",
      "args": [
        "-y",
        "@neomint-pst/controlled-sequential-thinking"
      ]
    }
  }
}
```

#### With CLI flags:

```json
{
  "mcpServers": {
    "controlled-sequential-thinking": {
      "command": "npx",
      "args": [
        "-y", 
        "@neomint-pst/controlled-sequential-thinking",
        "--force-total-thoughts", 
        "5",
        "--phases",
        "brainstorm,analyze,refine"
      ]
    }
  }
}
```

#### VS Code

For manual installation in VS Code, add the configuration to your user-level MCP configuration file. Open the Command Palette (`Ctrl + Shift + P`) and run `MCP: Open User Configuration`. Add this to your `mcp.json` file:

```json
{
  "servers": {
    "controlled-sequential-thinking": {
      "command": "npx",
      "args": [
        "-y",
        "@neomint-pst/controlled-sequential-thinking"
      ],
      "env": {
        "FORCE_TOTAL_THOUGHTS": "8",
        "FORCE_PHASES": "brainstorm,analyze,refine"
      }
    }
  }
}
```

## Environment Variables & CLI Options

### Environment Variables

- `DISABLE_THOUGHT_LOGGING`: Set to `true` to disable logging of thought information
- `FORCE_TOTAL_THOUGHTS`: Force a specific total number of thoughts (e.g., `8`)
- `FORCE_PHASES`: Force a phase configuration (e.g., `brainstorm,analyze,refine`)

### CLI Options

```bash
npx @neomint-pst/controlled-sequential-thinking --help
```

Available options:
- `-f, --force-total-thoughts <number>`: Force a specific total number of thoughts (can be overridden per-request via requestedTotalThoughts parameter)
- `-p, --phases <phases>`: Configure phase-based thinking (e.g., "brainstorm,analyze,refine")
- `-v, --version`: Show version number
- `-h, --help`: Show help

## Development

### Building from Source

```bash
npm install
npm run build
```

#### Claude Desktop Configuration for Local Development

After building locally, add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "controlled-sequential-thinking-local": {
      "command": "node",
      "args": [
        "/path/to/your/controlled-sequential-thinking-mcp/dist/index.js"
      ]
    }
  }
}
```

Replace `/path/to/your/controlled-sequential-thinking-mcp` with the absolute path to your local repository.

You can also use CLI flags:

```json
{
  "mcpServers": {
    "controlled-sequential-thinking-local": {
      "command": "node",
      "args": [
        "/path/to/your/controlled-sequential-thinking-mcp/dist/index.js",
        "--force-total-thoughts", 
        "10",
        "--phases",
        "plan,implement,validate"
      ]
    }
  }
}
```

### Testing

```bash
# Test CLI help
node dist/index.js --help

# Test version
node dist/index.js --version

# Test with forced total thoughts
node dist/index.js --force-total-thoughts 5

# Test with phase mode
node dist/index.js --phases "brainstorm,analyze,refine"

# Test combined mode
node dist/index.js --phases "plan,implement,validate" --force-total-thoughts 15
```

## License

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.