hyunjae-labs/structured-thinking-mcp

Structured Thinking MCP

⚠️ Migration Notice: This package was previously known as semantic-prompt-mcp. Please update your installations and configurations to use structured-thinking-mcp for future updates.

The Core Thinking Engine for SuperClaude Framework - An MCP server that helps Claude think systematically step-by-step

🎯 What is this?

A meta-cognitive execution engine that transforms Claude's passive responses into active decisions.

v1.4.24 Features

• Enhanced Guidance: All steps now include explicit "Next:" action instructions
• Simplified Configuration: YAML-first approach with inheritance support
• DRY Principle: Unified duplicate messages, removed redundant JSON configs
• Domain Neutral: Core server implementation is now framework-agnostic
• Improved Clarity: Better MCP response messages for smoother Claude interactions

⚡ Quick Start

1. Run Directly

npx structured-thinking-mcp superclaude

2. Add to Claude Code (Production)

{
  "mcpServers": {
    "structured-thinking": {
      "command": "npx",
      "args": ["-y", "structured-thinking-mcp@latest", "superclaude"]
    }
  }
}

3. Local Development Setup

For testing local changes before publishing:

# 1. Clone and build
git clone https://github.com/hyunjae-labs/structured-thinking-mcp.git
cd structured-thinking-mcp
npm install && npm run build

{
  "mcpServers": {
    "structured-thinking": {
      "command": "node",
      "args": ["/path/to/structured-thinking-mcp/dist/index.js", "superclaude"],
      "env": {}
    }
  }
}

Example paths:

• Windows: "C:/dev/projects/structured-thinking-mcp/dist/index.js"
• macOS/Linux: "/Users/username/projects/structured-thinking-mcp/dist/index.js"

Important: Always use absolute paths and ensure npm run build is executed after code changes.

🎭 Framework Modes

1️⃣ superclaude - SuperClaude Framework ⭐

npx structured-thinking-mcp superclaude

• 3-step systematic thinking
• Command selection enforcement
• Document caching system

2️⃣ supergemini - SuperGemini Framework

npx structured-thinking-mcp supergemini  

• 4-step structure with agent selection
• TOML command files (.toml)
• Multi-agent coordination

3️⃣ default - Basic Mode

npx structured-thinking-mcp  # or: default

• General purpose thinking
• No specific framework requirements

🔄 How It Works

Meta-Cognitive Execution (3 Steps)

User: "Build authentication system"

Step 1️⃣ → Analyze intent → Scope: 5 files → Outcome: JWT auth
Step 2️⃣ → EXECUTE matrix[command-matrix] → SELECT: build
Step 3️⃣ → CALCULATE score: 6 → Executing: Task tool delegation

Key Change: Not "consider delegation" but "Score: 6 → Delegating NOW"

🚀 Core Feature: Document Caching System

Documents are never read twice!

First Request:
Claude: "Selecting 'analyze' command"
System: Reads analyze.md → Cache saved ✅

Second Request:
Claude: "Selecting 'analyze' command"
System: "Already read. Refer to system-reminder" ⚡

This significantly reduces token usage and speeds up execution!

🎨 Custom Framework

Configuration Format

• Recommended: YAML format with extends: base.yaml for inheritance
• Supported: JSON format for custom configurations (no inheritance)

Create my-framework.yaml:

extends: base.yaml  # Inherit common settings
config:
  mode: my-framework
  defaultCommandExtension: .xml
  defaultAgentsExtension: .txt
  commandPath: ./my-commands/
  availableCommands: [analyze, build, test]

💡 Note: While JSON format is still supported for backward compatibility, YAML is recommended for better maintainability through inheritance

Use it:

npx structured-thinking-mcp my-framework

Built-in: superclaude, supergemini, default (YAML format)
Custom: Any .yaml file (recommended) or .json file

📁 Project Structure

structured-thinking-mcp/
├── prompts/
│   ├── base.yaml          # Base configuration (SSOT)
│   ├── default.yaml       # Basic mode (extends base)
│   ├── superclaude.yaml   # SuperClaude framework
│   └── supergemini.yaml   # SuperGemini framework
├── index.ts               # Domain-neutral engine
├── LICENSE                # MIT License
└── README.md              # This document

🤝 For Developers

Local Development

git clone <repo>
cd structured-thinking-mcp
npm install && npm run build

🔧 Troubleshooting

"Document already read" - Normal! Documents are cached for performance.

Too many logs - Set DISABLE_THOUGHT_LOGGING=true

📜 License & Attribution

This project is based on sequential-thinking MCP server.

License

MIT License - Free to use, modify, and distribute

Copyright Notice

• Original Work: Copyright (c) Model Context Protocol Contributors (sequential-thinking)
• This Work: Copyright (c) 2025 Hyunjae Lim (thecurrent.lim@gmail.com)

Major Changes from Original

• Extended 3-step structure to adaptive 3-4 step structure
• Added SuperClaude/SuperGemini Framework specific profiles
• Implemented document caching system
• Added meta-cognitive attention mechanisms
• Implemented multi-profile system

🔗 Related Links

• Model Context Protocol
• Structured Thinking MCP Repository
• SuperClaude Framework
• SuperGemini Framework
• Original sequential-thinking

🚀 Version History

v1.4.22 (Current)

• Unified Processing: Single engine for all steps (70% less code)
• Context-Aware: Responses adapt to your command & execution choices
• FLAGS Integration: Auto-detects needs (--think, --delegate, etc.)
• Dynamic Guidance: Step 3 now respects your execution mode

v1.4.21

• Framework-agnostic configuration system
• Extension-agnostic file discovery
• Custom framework support via configuration

v1.4.20

• SuperClaude/SuperGemini profiles
• Document caching system
• Meta-cognitive attention mechanisms

💡 Need Help?

• Open an issue: GitHub Issues
• Refer to SuperClaude Framework or SuperGemini Framework
• Contact: Hyunjae Lim (thecurrent.lim@gmail.com)