semantic-prompt-mcp/README.md

MCP server for semantic prompt framework - NLP-inspired adaptive reasoning engine for LLM orchestration

# Semantic Prompt MCP

![Version](https://img.shields.io/npm/v/semantic-prompt-mcp)
![License](https://img.shields.io/npm/l/semantic-prompt-mcp)

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

## 🎯 What is this?

Semantic Prompt MCP is a tool that helps Claude solve complex problems by **breaking them down into 3-4 systematic thinking steps**. 
Just like humans solve problems by "understanding first → choosing a method → executing", this makes Claude follow the same process.

### Core Concepts
- **🧠 Step-by-Step Thinking**: Break complex problems into 3-4 manageable steps
- **📚 Document Caching**: Once read, documents are cached and referenced (performance optimization)
- **🎨 Profile System**: Different configuration files for different purposes

## ⚡ Quick Start

### 1. Run without Installation
```bash
npx semantic-prompt-mcp
```

### 2. Add to Claude Code

Add to `.mcp.json` in your project root:
```json
{
  "mcpServers": {
    "semantic-prompt": {
      "command": "npx",
      "args": ["-y", "semantic-prompt-mcp@latest"],
      "env": {
        "CHAIN_OF_THOUGHT_CONFIG": "superclaude.json"
      }
    }
  }
}
```

## 🎭 Three Modes (Profiles)

### 1️⃣ **default.json** - Basic Mode
```bash
npx semantic-prompt-mcp  # or
npx semantic-prompt-mcp default.json
```
- **Purpose**: General problem solving
- **Features**: Flexible thinking process, simple 3-step structure
- **Best for**: General tasks without special framework requirements

### 2️⃣ **superclaude.json** - SuperClaude Mode ⭐
```bash
npx semantic-prompt-mcp superclaude.json
```
- **Purpose**: Use with SuperClaude Framework
- **Features**: 
  - 90% command selection enforcement (systematic execution)
  - Document duplicate read prevention (caching system)
  - 21 dedicated commands support
  - Quality Gates validation system
- **Best for**: Required when using SuperClaude Framework

### 3️⃣ **supergemini.json** - SuperGemini Mode
```bash
npx semantic-prompt-mcp supergemini.json
```
- **Purpose**: Use with SuperGemini Framework
- **Features**: 
  - 4-step structure (Analysis → TOML Command → Agent Selection → Execution)
  - Commands defined in TOML files
  - Multi-Agent system support
- **Best for**: When using SuperGemini Framework

## 🔄 How It Works

### SuperClaude Mode Example (3 Steps)
```
User: "Analyze security issues in this code"

Step 1️⃣ - Intent Analysis
Claude: "User wants security analysis. Related files are..."

Step 2️⃣ - Command Selection (90% enforced)
Claude: "Selecting 'analyze' command and reading analyze.md document"
System: Provides analyze.md content → Cache saved ✅

Step 3️⃣ - Execution Strategy
Claude: "Following document instructions to execute security analysis..."
```

### 🚀 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!

## 🎨 Creating Your Own Custom Profile

### Step 1: Create your custom JSON file
Create a new file `my-custom.json` in any folder (e.g., your project root):

```json
{
  "tool": {
    "name": "my_thinking",
    "description": "My custom thinking process..."
  },
  "config": {
    "availableCommands": ["analyze", "build", "test"],
    "commandPath": "./my-commands/",
    "commandPreference": 0.8
  }
}
```

### Step 2: Use it in Claude Code
Update your `.mcp.json`:

```json
{
  "mcpServers": {
    "semantic-prompt": {
      "command": "npx",
      "args": ["-y", "semantic-prompt-mcp@latest"],
      "env": {
        "CHAIN_OF_THOUGHT_CONFIG": "./my-custom.json"  // ← Just change this!
      }
    }
  }
}
```

That's it! Just change the filename in `CHAIN_OF_THOUGHT_CONFIG`:

**Built-in profiles** (no path needed):
- `"superclaude.json"` - SuperClaude Framework 
- `"supergemini.json"` - SuperGemini Framework
- `"default.json"` - Basic mode

**Your custom profiles** (need path):
- `"./my-custom.json"` - File in your project root
- `"./config/my-profile.json"` - File in a subfolder
- `"/absolute/path/to/profile.json"` - Absolute path

> **Why the difference?** Built-in profiles are packaged with npm, your files are in your project!

## 📁 Project Structure
```
semantic-prompt-mcp/
├── prompts/
│   ├── default.json      # Basic profile
│   ├── superclaude.json  # SuperClaude specific
│   └── supergemini.json  # SuperGemini specific
├── src/
│   └── index.ts          # Main server code
├── LICENSE              # MIT License
└── README.md            # This document
```

## 🤝 For Developers

### Local Development Setup
```bash
git clone https://github.com/hyunjae-labs/semantic-prompt-mcp.git
cd semantic-prompt-mcp
npm install
npm run build
npm link  # For local testing
```


## 🔧 Troubleshooting

### "Document already read" message appears
This is normal! Documents are cached for performance optimization.

### Too many console logs
```bash
export DISABLE_THOUGHT_LOGGING=true
```

### Cannot find specific command
Check your command path:
```bash
export CHAIN_OF_THOUGHT_COMMAND_PATH=/correct/path/to/commands/
```

## 📜 License & Attribution

This project is based on [sequential-thinking MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking).

### 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](https://modelcontextprotocol.io)
- [Semantic Prompt MCP Repository](https://github.com/hyunjae-labs/semantic-prompt-mcp)
- [SuperClaude Framework](https://github.com/SuperClaude-Org/SuperClaude_Framework)
- [SuperGemini Framework](https://github.com/SuperClaude-Org/SuperGemini_Framework)
- [Original sequential-thinking](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking)

## 🚀 Version History

### v1.3.0 (Current)
- Added SuperClaude/SuperGemini profiles
- Implemented document caching system
- Added meta-cognitive attention mechanisms

### v1.0.0
- Initial release (based on sequential-thinking)

---

**💡 Need Help?** 
- Open an issue: [GitHub Issues](https://github.com/hyunjae-labs/semantic-prompt-mcp/issues)
- Refer to [SuperClaude Framework](https://github.com/SuperClaude-Org/SuperClaude_Framework) or [SuperGemini Framework](https://github.com/SuperClaude-Org/SuperGemini_Framework)
- Contact: Hyunjae Lim (thecurrent.lim@gmail.com)