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.

Table of Contents

- Overview
- Features
- Architecture
- Installation
- Configuration
- Quick Start
- MCP Client Configuration
- API Reference
- Thinking Modes
- Examples
- Contributing
- Changelog
- 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

$3


Single tool that combines all thinking modes:
`json
{
"query": "Your question here",
"mode": "hybrid_adaptive" // 15 modes available
}
`

$3

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

$3

Persistent session storage with:
`typescript
import { SessionRepository } from '@gotza02/human-thinking';
const repo = new SessionRepository();
await repo.save(session);
`

$3

Test with predictable randomness:
`typescript
import { SeededRandom } from '@gotza02/human-thinking';
const rng = new SeededRandom(12345);
// Same seed = same results
`

---

Features

$3

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

$3

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

$3

| 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 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
`

$3

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

---

Installation

$3

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

$3

`bash


Install globally

npm install -g @gotza02/human-thinking

Or install locally in your project

npm install @gotza02/human-thinking
`

$3

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

$3

`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

$3

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

$3

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"
}
}
`

$3

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

$3

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

$3

`bash


Install MCP Inspector

npm install -g @modelcontextprotocol/inspector

Run inspector

mcp-inspector @gotza02/human-thinking
`

$3

`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

$3

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": []
}
}
}
`

$3

Add to Cursor's MCP settings:

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

$3

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

- 📖 Documentation
- 🐛 Issue Tracker
- 💬 Discussions

---

Acknowledgments

Built with the Model Context Protocol SDK.