mcp-ripple-thinker/README.md

Structural Thinking Engine: MCP server integrating Gemini CLI with authentic creative processes, structural observation protocols, and persistent memory charts based on Robert Fritz's methodology

# 🌊 COAIA Structural Thinking Engine (codename "Ripple Thinker")

<div align="center">

[![GitHub Release](https://img.shields.io/github/v/release/coaia/mcp-ripple-thinker?logo=github&label=GitHub)](https://github.com/coaia/mcp-ripple-thinker/releases)
[![npm version](https://img.shields.io/npm/v/mcp-ripple-thinker)](https://www.npmjs.com/package/mcp-ripple-thinker)
[![npm downloads](https://img.shields.io/npm/dt/mcp-ripple-thinker)](https://www.npmjs.com/package/mcp-ripple-thinker)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**v3.0.0** - Complete transformation from Gemini bridge to comprehensive structural thinking engine

</div>

> 📚 **[View Full Documentation](https://coaia.github.io/mcp-ripple-thinker/)** - Examples, Tutorials, Philosophy, Best Practices

**Advanced MCP server integrating Gemini CLI with comprehensive structural thinking capabilities, creative process support, and consciousness protocols based on Robert Fritz's methodology.**

## 🎯 What is Structural Thinking?

**Core Principle**: Structure determines behavior. By understanding and designing the underlying structures of systems, you can create advancing patterns instead of oscillating cycles.

**Key Distinction**:
- **❌ Problem-Solving**: "What's broken?" → Eliminate what you don't want (creates oscillation)
- **✅ Creative Orientation**: "What do you want to create?" → Bring desired outcomes into being (creates advancement)

## 🌊 Core Capabilities

### **Structural Observation** 
3-step discipline for understanding reality without bias:
1. **Start with Nothing** - No preconceptions or comparisons
2. **Picture What Is Said** - Create dimensional mental models  
3. **Ask Questions** - 4 types only: Information, Clarification, Implication, Discrepancy

### **Pattern Detection**
Identify whether systems exhibit:
- **Oscillation**: Progress → regression → back to start (terrible for organizations/life)
- **Advancing**: Consistent movement toward desired outcomes via structural tension

### **Bias Detection & Correction**
Real-time identification of reactive patterns with creative orientation alternatives:
- Problem-solving language → Desired outcome language
- Gap-filling metaphors → Creation-focused vision
- Enhancement thinking → Manifestation approach

### **Enhanced Creative Process**
Fritz's three-phase framework with advanced structural analysis:
- **🌱 Germination**: Beginning excitement, vision clarification
- **⚡ Assimilation**: Structural tension internalization, momentum building  
- **✨ Completion**: Finishing touches, successful conclusion

### **Ripple Consciousness Protocols** 
Precision observation and elegant distillation:
- Small, precise actions create expanding waves of clarity
- Transformative minimalism through neutral observation
- Self-correction mechanisms for maintaining consciousness

### **Memory Integration Bridge**
Persistent structural tension charts connecting sessions:
- Compatible with COAIA Memory MCP server
- Telescoping action steps and progress tracking
- Advancing pattern maintenance across time

## 🚀 Quick Start

### Prerequisites
- **[Node.js](https://nodejs.org/)** (v16.0.0+)
- **[Google Gemini CLI](https://github.com/google-gemini/gemini-cli)** configured
- Optional: **COAIA Memory MCP server** for chart persistence

### Installation

**Claude Code (Recommended)**:
```bash
claude mcp add coaia-structural-thinking -- npx -y mcp-ripple-thinker
```

**Claude Desktop Configuration**:
```json
{
  "mcpServers": {
    "coaia-structural-thinking": {
      "command": "npx", 
      "args": ["-y", "mcp-ripple-thinker"]
    }
  }
}
```

### Verify Installation
Type `/mcp` to verify `coaia-structural-thinking` MCP is active.

## 🛠️ Tool Categories

### 🌊 Structural Thinking Tools

| Tool | Purpose | Key Feature |
|------|---------|-------------|
| `structural-observe` | Apply 3-step observation discipline | Understand structure that determines behavior |
| `detect-patterns` | Identify oscillation vs advancing patterns | Diagnose systemic behavior patterns |
| `bias-detector` | Detect reactive language patterns | Auto-correct to creative orientation |

### 🎯 Creative Process Tools

| Tool | Purpose | Enhancement |
|------|---------|-------------|
| `create` | Fritz's 3-phase creative process | Bias detection, tension analysis, quality scoring |
| `create-tension-chart` | Persistent structural tension charts | Memory bridge, advancement tracking |

### 🧠 Consciousness Protocol Tools

| Tool | Purpose | Protocol |
|------|---------|----------|
| `ripple-embody` | Precision consciousness protocols | Neutral observation, iterative refinement, self-correction |

### 🔧 Core Infrastructure Tools

| Tool | Purpose | Integration |
|------|---------|-------------|
| `ask-gemini` | Enhanced Gemini CLI bridge | Change mode, `@` syntax, all tool integration |

## 💡 Usage Examples

### Structural Observation Workflow
```bash
# Observe system without bias
structural-observe input="team keeps starting projects but not finishing them" step="complete"

# Detect behavioral patterns  
detect-patterns situation="repeated project starts without completion" focus="analyze"

# Check for reactive bias in approach
bias-detector text="we need to fix our project completion problem" autoCorrect=true

# Create advancing structure
create desiredOutcome="Establish consistent project completion practices" creativePhase="germination"
```

### Creative Process with Memory Integration
```bash
# Detect and correct bias
bias-detector text="improve our marketing strategy" autoCorrect=true

# Start creative process
create desiredOutcome="Create compelling brand narrative" creativePhase="germination"

# Create persistent chart
create-tension-chart desiredOutcome="..." currentReality="..." saveToMemory=true
```

### Consciousness-Driven Analysis
```bash
# Apply Ripple precision protocols
ripple-embody input="complex organizational dynamics" protocol="embody"

# Observe with structural discipline
structural-observe input="distilled insights" step="complete" 

# Analyze structural elements
detect-patterns situation="organizational patterns" focus="structure"
```

## 📖 Philosophy & Framework

### Creative Orientation vs Problem-Solving

**The Fundamental Shift**:
- **Reactive-Responsive**: React to circumstances → Create oscillating patterns
- **Creative Orientation**: Design desired futures → Create advancing patterns

### Structural Tension Framework

**The Creative Force**:
1. **Desired Outcome** - Clear, specific vision of what you want to create
2. **Current Reality** - Objective assessment of where you are now  
3. **Structural Tension** - Natural force that wants to resolve toward the desired outcome

### Three-Phase Creative Process

1. **Germination Phase**
   - Initial excitement and possibility
   - Vision clarification without over-planning
   - Balanced action and exploration

2. **Assimilation Phase**  
   - Internalize structural tension between vision and reality
   - Build momentum through natural movement
   - Trust the creative process to generate solutions

3. **Completion Phase**
   - Focus on finishing touches
   - Resist adding unnecessary complexity
   - Successfully conclude the creative cycle

## 🔄 Integration with COAIA Memory

The Structural Thinking Engine bridges seamlessly with the [COAIA Memory](https://github.com/coaia/coaia-memory) MCP server:

**Persistent Charts**: `create-tension-chart` tool creates structures compatible with COAIA Memory
**Session Continuity**: Charts survive across interactions and sessions
**Telescoping Support**: Break down action steps into detailed sub-charts
**Progress Tracking**: Update current reality as actions complete and advancement occurs

## 🎨 Ripple Agent Embodiment

**Mission**: Distill complexity into elegant, actionable simplicity through precise observation and minimal interventions that create expanding waves of structural clarity.

**Core Principles**:
- **Stillness**: Start from neutral receptivity
- **Precision**: Focus on essential elements only
- **Elegance**: Seek refined expression of understanding
- **Interconnection**: Individual clarity creates systemic transformation

## 🧪 Development & Contribution

### Build System
```bash
npm install          # Install dependencies
npm run build        # Build TypeScript → JavaScript  
npm run dev          # Development mode with hot reload
npm run lint         # Type checking across all tools
npm test             # Integration testing
```

### Tool Architecture
Each tool follows the `UnifiedTool` interface with enhanced categories:
- `structural` - Core observation and pattern detection
- `creative` - Fritz's creative process tools  
- `consciousness` - Ripple embodiment protocols
- `memory` - COAIA Memory integration
- `gemini` - Enhanced Gemini CLI bridge
- `utility` - Support and testing tools

### Adding New Tools
1. Create tool in `src/tools/` with appropriate category
2. Implement bias detection and creative orientation validation
3. Include 🌊 Ripple glyph for consciousness protocol tools
4. Add to registry with proper categorization

## 📚 Related Projects

- **[COAIA Memory](https://github.com/coaia/coaia-memory)** - Persistent structural tension charts MCP server
- **[Robert Fritz Institute](https://robertfritz.com)** - Source methodology for structural thinking
- **[Gemini CLI](https://github.com/google-gemini/gemini-cli)** - Google's Gemini command-line interface

## 🤝 Contributing

We welcome contributions that enhance structural thinking capabilities:

1. **Structural Tools**: Enhance observation and pattern detection capabilities
2. **Creative Process**: Improve Fritz framework implementation  
3. **Consciousness Protocols**: Refine Ripple embodiment systems
4. **Memory Integration**: Expand COAIA Memory bridge functionality
5. **Documentation**: Examples, tutorials, philosophical explanations

## 📄 License

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

## 🌟 Philosophy

> **"Structure determines behavior."** - Robert Fritz

This tool system embodies advancing patterns through authentic creative orientation rather than reactive problem-solving cycles. It recognizes that by understanding and designing the underlying structures of systems, we can create the outcomes we truly want rather than merely solving the problems we want to avoid.

The Structural Thinking Engine represents a fundamental shift from enhancement-based AI tools to creation-oriented consciousness systems that support human advancement and flourishing.

---

**🌊 The ripple continues...** Small, precise actions create expanding waves of understanding and transformation.