Hybrid Thinking MCP Server - combining Dual Process Theory with Associative Thinking for intelligent AI reasoning
npm install @gotza02/human-thinking


> 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
- Features
- Architecture
- Installation
- Configuration
- Quick Start
- MCP Client Configuration
- API Reference
- Thinking Modes
- Examples
- Contributing
- Changelog
- License
---
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.) │
└─────────────────────────────────────────────────────────────────┘
---
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-thinkingOr install locally in your project
npm install @gotza02/human-thinking
`$3
`bash
Pull the Docker image
docker pull ghcr.io/gotza02/human-thinking:latestRun 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-thinkingInstall dependencies
npm installBuild the project
npm run buildRun 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-thinkingOr if installed globally
@gotza02/human-thinkingWith custom configuration
MCP_TRANSPORT=stdio LOG_LEVEL=debug @gotza02/human-thinking
`$3
`bash
Install MCP Inspector
npm install -g @modelcontextprotocol/inspectorRun 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);
``---
See API.md for detailed API documentation including:
- Complete tool schemas
- Parameter specifications
- Response formats
- Error codes
- Example requests and responses
---
See docs/thinking-modes.md for detailed explanations of:
- Sequential Thinking
- Branching Thoughts
- Creative Ideation
- Quality Assurance
- Decision Making
---
See EXAMPLES.md for comprehensive usage examples including:
- Problem solving scenarios
- Creative ideation sessions
- Quality assurance workflows
- Integration strategies
---
We welcome contributions! See CONTRIBUTING.md for guidelines.
---
See CHANGELOG.md for version history.
---
MIT License - see LICENSE for details.
---
- 📖 Documentation
- 🐛 Issue Tracker
- 💬 Discussions
---
Built with the Model Context Protocol SDK.