@gotza02/human-thinking

v1.1.0

Published

4 days ago

Hybrid Thinking MCP Server - combining Dual Process Theory with Associative Thinking for intelligent AI reasoning

0High
0Medium
0Low

gotza02

mcp thinking cognitive ai system1 system2 associative dual-process lateral-thinking model-context-protocol

Hybrid Thinking MCP Server

A powerful Model Context Protocol (MCP) server that brings structured human-like thinking capabilities to AI assistants. Enable sequential reasoning, branching exploration, and quality assurance for complex problem-solving tasks.

Overview

The Hybrid Thinking MCP Server bridges the gap between AI capabilities and human-like structured reasoning. It provides a comprehensive toolkit for:

Sequential Thinking: Step-by-step problem decomposition
Branching Exploration: Parallel thought paths and alternatives
Quality Assurance: Self-review and validation mechanisms
Creative Ideation: Structured brainstorming sessions
Decision Making: Systematic evaluation frameworks

┌─────────────────────────────────────────────────────────────────┐
│                    Hybrid Thinking MCP Server                    │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   Sequential │  │  Branching  │  │    Quality Assurance    │  │
│  │   Thinking   │  │  Thoughts   │  │                         │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   Creative  │  │   Decision  │  │    Session Management   │  │
│  │   Thinking  │  │   Making    │  │                         │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      MCP Client (Claude, etc.)                   │
└─────────────────────────────────────────────────────────────────┘

New Features

Unified Think Tool

Single tool that combines all thinking modes:

{
  "query": "Your question here",
  "mode": "hybrid_adaptive"  // 15 modes available
}

Performance Optimizations

LRU Caching for pattern recognition
Memoization for similarity calculations
Parallel processing where applicable
Timeout handling for reliability

Repository Pattern

Persistent session storage with:

import { SessionRepository } from '@gotza02/human-thinking';
const repo = new SessionRepository();
await repo.save(session);

Deterministic Testing

Test with predictable randomness:

import { SeededRandom } from '@gotza02/human-thinking';
const rng = new SeededRandom(12345);
// Same seed = same results

Features

Core Thinking Tools

| Tool | Description | Use Case | |------|-------------|----------| | sequentialthinking | Step-by-step reasoning with revision tracking | Complex problem solving | | branchingthoughts | Explore multiple parallel thought paths | Alternative analysis | | creativeideation | Structured creative brainstorming | Innovation sessions | | qualityassurance | Self-review and validation | Quality control | | decisionmaking | Systematic decision framework | Strategic choices |

Session Management

| Tool | Description | Use Case | |------|-------------|----------| | create_session | Initialize thinking session | Start new workflows | | get_session | Retrieve session state | Monitor progress | | update_session | Modify session parameters | Adjust configuration | | delete_session | Clean up sessions | Resource management | | list_sessions | View all active sessions | Overview dashboard |

Utility Tools

| Tool | Description | Use Case | |------|-------------|----------| | validate_thought | Check thought quality | Quality gates | | merge_thoughts | Combine related thoughts | Synthesis | | export_session | Export session data | Reporting |

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         Client Layer                                 │
│  (Claude Desktop, Cursor, Custom MCP Clients)                       │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ MCP Protocol
                                    │ (stdio/sse)
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      MCP Server Layer                                │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                 Tool Registry & Router                       │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                              │                                       │
│          ┌───────────────────┼───────────────────┐                  │
│          ▼                   ▼                   ▼                  │
│  ┌──────────────┐  ┌────────────────┐  ┌────────────────┐          │
│  │   Thinking   │  │    Session     │  │    Utility     │          │
│  │    Engine    │  │   Manager      │  │    Tools       │          │
│  └──────────────┘  └────────────────┘  └────────────────┘          │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      Storage Layer                                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │   Memory     │  │   File       │  │   External   │              │
│  │   Store      │  │   System     │  │   APIs       │              │
│  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────────────────────────┘

Data Flow

┌─────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌─────────┐
│  User   │───▶│  Client  │───▶│  Server  │───▶│  Engine  │───▶│ Storage │
│ Request │    │          │    │          │    │          │    │         │
└─────────┘    └──────────┘    └──────────┘    └──────────┘    └─────────┘
                                    │
                                    ▼
┌─────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌─────────┐
│  User   │◀───│  Client  │◀───│  Server  │◀───│  Engine  │◀───│ Storage │
│ Response│    │          │    │          │    │          │    │         │
└─────────┘    └──────────┘    └──────────┘    └──────────┘    └─────────┘

Installation

Prerequisites

Node.js 18.0 or higher
npm 9.0 or higher
An MCP-compatible client (Claude Desktop, Cursor, etc.)

Option 1: NPM Installation (Recommended)

# Install globally
npm install -g @gotza02/human-thinking

# Or install locally in your project
npm install @gotza02/human-thinking

Option 2: Docker Installation

# Pull the Docker image
docker pull ghcr.io/gotza02/human-thinking:latest

# Run the container
docker run -i --rm \
  -e MCP_TRANSPORT=stdio \
  ghcr.io/gotza02/human-thinking:latest

Option 3: Build from Source

# Clone the repository
git clone https://github.com/gotza02/human-thinking.git
cd human-thinking

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
npm start

Configuration

Environment Variables

| Variable | Type | Default | Description | |----------|------|---------|-------------| | MCP_TRANSPORT | string | stdio | Transport mode: stdio or sse | | MCP_PORT | number | 3000 | Port for SSE transport | | SESSION_TIMEOUT | number | 3600 | Session timeout in seconds | | MAX_THOUGHTS_PER_SESSION | number | 100 | Maximum thoughts per session | | ENABLE_PERSISTENCE | boolean | false | Enable session persistence | | PERSISTENCE_PATH | string | ./sessions | Path for session storage | | LOG_LEVEL | string | info | Logging level: debug, info, warn, error | | ENABLE_METRICS | boolean | false | Enable metrics collection |

Configuration File

Create a mcp-config.json file:

{
  "server": {
    "name": "@gotza02/human-thinking",
    "version": "1.0.0",
    "transport": "stdio"
  },
  "thinking": {
    "defaultMode": "sequential",
    "maxDepth": 10,
    "enableRevision": true
  },
  "session": {
    "timeout": 3600,
    "maxThoughts": 100,
    "persistence": {
      "enabled": false,
      "path": "./sessions"
    }
  },
  "logging": {
    "level": "info",
    "format": "json"
  }
}

Session Configuration

Sessions can be configured per-request:

{
  "sessionConfig": {
    "mode": "sequential",
    "maxDepth": 15,
    "enableBranching": true,
    "qualityChecks": true,
    "metadata": {
      "project": "my-project",
      "tags": ["analysis", "planning"]
    }
  }
}

Quick Start

1. Start the Server

# Using npx (no installation required)
npx @gotza02/human-thinking

# Or if installed globally
@gotza02/human-thinking

# With custom configuration
MCP_TRANSPORT=stdio LOG_LEVEL=debug @gotza02/human-thinking

2. Test with MCP Inspector

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run inspector
mcp-inspector @gotza02/human-thinking

3. Basic Usage Example

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const client = new Client({
  name: 'example-client',
  version: '1.0.0'
});

const transport = new StdioClientTransport({
  command: '@gotza02/human-thinking'
});

await client.connect(transport);

// Create a thinking session
const session = await client.callTool('create_session', {
  mode: 'sequential',
  topic: 'Problem Analysis'
});

// Add a thought
const thought = await client.callTool('sequentialthinking', {
  sessionId: session.id,
  thought: 'First, let me understand the problem...',
  thoughtNumber: 1,
  totalThoughts: 5
});

MCP Client Configuration

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "hybrid-thinking": {
      "command": "npx",
      "args": ["-y", "@gotza02/human-thinking"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "LOG_LEVEL": "info",
        "SESSION_TIMEOUT": "3600"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Cursor Configuration

Add to Cursor's MCP settings:

{
  "mcpServers": {
    "hybrid-thinking": {
      "command": "npx",
      "args": ["-y", "@gotza02/human-thinking"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Custom Client Configuration

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: '@gotza02/human-thinking',
  env: {
    MCP_TRANSPORT: 'stdio',
    SESSION_TIMEOUT: '3600',
    MAX_THOUGHTS_PER_SESSION: '100'
  }
});

const client = new Client({ name: 'my-client', version: '1.0.0' });
await client.connect(transport);

API Reference

See API.md for detailed API documentation including:

Complete tool schemas
Parameter specifications
Response formats
Error codes
Example requests and responses

Thinking Modes

See docs/thinking-modes.md for detailed explanations of:

Sequential Thinking
Branching Thoughts
Creative Ideation
Quality Assurance
Decision Making

Examples

See EXAMPLES.md for comprehensive usage examples including:

Problem solving scenarios
Creative ideation sessions
Quality assurance workflows
Integration strategies

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Changelog

See CHANGELOG.md for version history.

License

MIT License - see LICENSE for details.

Support

Acknowledgments

Built with the Model Context Protocol SDK.