npm package: @gotza02/human-thinking
Description: Hybrid Thinking MCP Server - combining Dual Process Theory with Associative Thinking for intelligent AI reasoning
Author: gotza02
Latest version: 1.1.0

# Hybrid Thinking MCP Server

[![npm version](https://img.shields.io/npm/v/@gotza02/human-thinking)](https://www.npmjs.com/package/@gotza02/human-thinking)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)

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

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Architecture](#architecture)
- [Installation](#installation)
- [Configuration](#configuration)
- [Quick Start](#quick-start)
- [MCP Client Configuration](#mcp-client-configuration)
- [API Reference](#api-reference)
- [Thinking Modes](#thinking-modes)
- [Examples](#examples)
- [Contributing](#contributing)
- [Changelog](#changelog)
- [License](#license)

---

## 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:
```json
{
  "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:
```typescript
import { SessionRepository } from '@gotza02/human-thinking';
const repo = new SessionRepository();
await repo.save(session);
```

### Deterministic Testing
Test with predictable randomness:
```typescript
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)

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

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

### Option 2: Docker Installation

```bash
# 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

```bash
# 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:

```json
{
  "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:

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

---

## Quick Start

### 1. Start the Server

```bash
# 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

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

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

### 3. Basic Usage Example

```typescript
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`

```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:

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

### Custom Client Configuration

```typescript
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](./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](./docs/thinking-modes.md) for detailed explanations of:
- Sequential Thinking
- Branching Thoughts
- Creative Ideation
- Quality Assurance
- Decision Making

---

## Examples

See [EXAMPLES.md](./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](./CONTRIBUTING.md) for guidelines.

---

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for version history.

---

## License

MIT License - see [LICENSE](./LICENSE) for details.

---

## Support

- 📖 [Documentation](https://github.com/gotza02/human-thinking/tree/main/docs)
- 🐛 [Issue Tracker](https://github.com/gotza02/human-thinking/issues)
- 💬 [Discussions](https://github.com/gotza02/human-thinking/discussions)

---

## Acknowledgments

Built with the [Model Context Protocol](https://modelcontextprotocol.io/) SDK.