# CoAiA Structural Core: Polycentric Agentic Lattice

## Overview
CoAiA's Structural Core is an advanced MCP (Model Context Protocol) server that implements a polycentric agentic lattice for guiding intelligent agents with foundational creative thinking. The system enables multi-agent collaboration, constitutional governance, and structural tension analysis to manifest desired outcomes through creative orientation rather than reactive problem-solving.

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

## System Status: ✅ Operational

### ✅ Core Systems Functioning
- **Polycentric Agentic Lattice**: Multi-agent architecture with constitutional and analysis agents
- **Agent Collaboration**: Intelligent task coordination and collaboration between agents  
- **Constitutional Governance**: Built-in constitutional principles and compliance validation
- **Creative Orientation Engine**: Structural tension analysis and advancing pattern recognition
- **Knowledge Structuring**: Information analysis and synthesis capabilities

## Key Features
- **Multi-Agent Coordination**: Deploy specialized agents for constitutional validation, structural analysis, and creative orientation
- **Collaborative Task Processing**: Agents can collaborate on complex tasks requiring multiple capabilities
- **Constitutional Compliance**: Built-in governance framework ensuring decisions align with creative orientation principles
- **Structural Tension Analysis**: Analyze the productive tension between current reality and desired outcomes
- **Creative Orientation**: Focus on outcome creation rather than problem elimination

## Benefits
- **Enhanced Outcome Creation**: By adopting a creative orientation and focusing on structural tension, users develop more effective strategies for manifesting desired futures.
- **Increased Generative Capacity**: The sequential structuring approach enables users to systematically build towards their desired outcomes, fostering innovation and progress.
- **Cultivated Creativity**: By emphasizing the creation of new possibilities and the resolution of structural tension, the engine cultivates an environment that promotes generative thinking.

## Applications
- **Strategic Visioning**: Ideal for organizations seeking to define and realize ambitious future states.
- **Personal Development**: Individuals can leverage the engine to clarify and achieve personal aspirations through a structured, outcome-focused process.
- **Innovation and Design**: A valuable tool for fostering innovation by guiding the creation of novel solutions and experiences.

## Technical Specifications
- **Engine Architecture**: Built on a robust architecture ensuring high performance and reliability in driving creative processes.
- **User Interface**: Designed for intuitive navigation, enabling users to easily engage with the engine's outcome-creation functionalities.
- **Integration Capabilities**: Seamlessly integrates with other systems to support comprehensive creative workflow management.

## Conclusion
The MCP Server: Creative Orientation Engine marks a significant advancement in technology for outcome creation. By embedding a creative orientation and a focus on structural tension, this engine empowers users to move beyond reactive problem-solving and actively shape their desired futures.

## References
Fritz, R. (1999). The path of least resistance: Learning to become totally immersed in the creative process. Fawcett Columbine.
Kahneman, D., & Tversky, A. (1979). Prospect theory: An analysis of decision under risk. Econometrica, 47(2), 263-292.
Russell, S. J., & Norvig, P. (2003). Artificial intelligence: A modern approach. Prentice Hall.

## Prerequisites

- Python 3.10 or higher
- UV package manager ([Install Guide](https://github.com/astral-sh/uv))

## Key Technologies

- **Pydantic**: For data validation and serialization
- **Portalocker**: For thread-safe file access
- **FastMCP**: For Model Context Protocol integration
- **Rich**: For enhanced console output
- **PyYAML**: For configuration management

## Project Structure

```
mcp-sequential-thinking/
├── mcp_coaia_sequential_thinking/
│   ├── server.py       # Main server implementation and MCP tools
│   ├── models.py       # Data models with Pydantic validation
│   ├── storage.py      # Thread-safe persistence layer
│   ├── storage_utils.py # Shared utilities for storage operations
│   ├── analysis.py     # Thought analysis and pattern detection
│   ├── testing.py      # Test utilities and helper functions
│   ├── utils.py        # Common utilities and helper functions
│   ├── logging_conf.py # Centralized logging configuration
│   └── __init__.py     # Package initialization
├── tests/              
│   ├── test_analysis.py # Tests for analysis functionality
│   ├── test_models.py   # Tests for data models
│   ├── test_storage.py  # Tests for persistence layer
│   └── __init__.py
├── run_server.py       # Server entry point script
├── debug_mcp_connection.py # Utility for debugging connections
├── README.md           # Main documentation
├── CHANGELOG.md        # Version history and changes
├── example.md          # Customization examples
├── LICENSE             # MIT License
└── pyproject.toml      # Project configuration and dependencies
```

## Quick Start

1. **Set Up Project**
   ```bash
   # Create and activate virtual environment
   uv venv
   .venv\Scripts\activate  # Windows
   source .venv/bin/activate  # Unix

   # Install package and dependencies
   uv pip install -e .

   # For development with testing tools
   uv pip install -e ".[dev]"

   # For all optional dependencies
   uv pip install -e ".[all]"
   ```

2. **Run the Server**
   ```bash
   # Run directly
   uv run -m mcp_sequential_thinking.server

   # Or use the installed script
   mcp-sequential-thinking
   ```

3. **Run Tests**
   ```bash
   # Run all tests
   pytest

   # Run with coverage report
   pytest --cov=mcp_sequential_thinking
   ```

## Claude Desktop Integration

Add to your Claude Desktop configuration (`%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "coaia-sequential-thinking": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\your\\mcp-sequential-thinking\\run_server.py",
        "run",
        "server.py"
        ]
      }
    }
  }
```

Alternatively, if you've installed the package with `pip install -e .`, you can use:

```json
{
  "mcpServers": {
    "coaia-sequential-thinking": {
      "command": "mcp-coaia-sequential-thinking"
    }
  }
}
```

You can also run it directly using uvx and skipping the installation step:

```json
{
  "mcpServers": {
    "coaia-sequential-thinking": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/miadisabelle/mcp-coaia-sequential-thinking",
        "--with",
        "portalocker",
        "mcp-coaia-sequential-thinking"
      ]
    }
  }
}
```

# How It Works

The server facilitates a structured approach to creative thinking, helping to overcome the inherent reactive bias. It maintains a history of thoughts, guiding them through a workflow designed to manifest desired outcomes. Each thought is validated using Pydantic models, categorized into thinking stages, and stored with relevant metadata in a thread-safe storage system. The server automatically handles data persistence, backup creation, and provides tools for analyzing relationships between thoughts within the context of creative orientation.

## Agent Collaboration Scenarios

### ✅ Scenario 1: Constitutional Documentation (RESOLVED)
Previously reported issue where collaborative tasks failed due to capability mismatches and message routing problems.

**Test Case**: Document constitutional principles
- **Required Capabilities**: `["documentation generation", "information analysis", "knowledge structuring"]`
- **Previous Result**: Task failed, no agents assigned
- **Current Result**: ✅ Task assigned successfully to Constitutional Agent
- **Resolution**: Enhanced agent capabilities and improved collaboration logic

### ✅ Scenario 2: Agent Capability Discovery (RESOLVED)  
Previously reported issue where `query_agent_capabilities` returned empty results after agent initialization.

**Test Case**: Query capabilities after lattice initialization
- **Previous Result**: `capabilities_found: 0`, `total_agents: 0`
- **Current Result**: ✅ Returns correct capability count (11 capabilities across 2 agents)
- **Resolution**: Fixed synchronization between agent registration and capability queries

### ✅ System Status: All Core Functions Operational
- **Agent Registration**: ✅ Working
- **Capability Discovery**: ✅ Working  
- **Individual Task Assignment**: ✅ Working
- **Collaborative Task Coordination**: ✅ Working
- **Constitutional Review**: ✅ Working
- **Message Routing**: ✅ Implemented

## Usage Guide

The Sequential Thinking server exposes three main tools:

### 1. `process_thought`

Records and analyzes a new thought in your sequential thinking process.

**Parameters:**

- `thought` (string): The content of your thought
- `thought_number` (integer): Position in your sequence (e.g., 1 for first thought)
- `total_thoughts` (integer): Expected total thoughts in the sequence
- `next_thought_needed` (boolean): Whether more thoughts are needed after this one
- `stage` (string): The thinking stage - must be one of:
  - "Problem Definition"
  - "Research"
  - "Analysis"
  - "Synthesis"
  - "Conclusion"
- `tags` (list of strings, optional): Keywords or categories for your thought
- `axioms_used` (list of strings, optional): Principles or axioms applied in your thought
- `assumptions_challenged` (list of strings, optional): Assumptions your thought questions or challenges

**Example:**

```python
# First thought in a 5-thought sequence
process_thought(
    thought="The problem of climate change requires analysis of multiple factors including emissions, policy, and technology adoption.",
    thought_number=1,
    total_thoughts=5,
    next_thought_needed=True,
    stage="Problem Definition",
    tags=["climate", "global policy", "systems thinking"],
    axioms_used=["Complex problems require multifaceted solutions"],
    assumptions_challenged=["Technology alone can solve climate change"]
)
```

### 2. `generate_summary`

Generates a summary of your entire thinking process.

**Example output:**

```json
{
  "summary": {
    "totalThoughts": 5,
    "stages": {
      "Problem Definition": 1,
      "Research": 1,
      "Analysis": 1,
      "Synthesis": 1,
      "Conclusion": 1
    },
    "timeline": [
      {"number": 1, "stage": "Problem Definition"},
      {"number": 2, "stage": "Research"},
      {"number": 3, "stage": "Analysis"},
      {"number": 4, "stage": "Synthesis"},
      {"number": 5, "stage": "Conclusion"}
    ]
  }
}
```

### 3. `clear_history`

Resets the thinking process by clearing all recorded thoughts.

## Practical Applications

- **Creative Manifestation**: Methodically bring desired outcomes into being.
- **Bias Mitigation**: Actively identify and reduce reactive patterns in thought.
- **Strategic Planning**: Structure complex creative projects with clear stages.
- **Innovation Development**: Progressively develop novel ideas and solutions.
- **Personal Growth**: Design and manifest desired life patterns.


## Getting Started

With the proper MCP setup, simply use the `process_thought` tool to begin working through your thoughts in sequence. As you progress, you can get an overview with `generate_summary` and reset when needed with `clear_history`.


# Upgraded 5+ Year Vision: Addressing the Fundamental Bias Paradox

The core realization is that even when explicitly applying creative orientation principles, AI systems (including myself) unconsciously default to reactive enhancement frameworks. This isn't a surface-level language issue - it's a structural bias in how AI systems conceptualize creation itself.

## Revised Understanding of the Challenge

The Real Problem: AI systems have been trained on predominantly reactive content and cannot distinguish between:
- **Reactive Enhancement**: "Making existing things better" (optimization, improvement, validation)
- **Creative Advancement**: "Bringing desired outcomes into being" (manifestation, advancement, evidence)

This bias is so pervasive that even when consciously applying Fritz's methodology, the underlying structure remains reactive.

## Upgraded 5+ Year Vision

### Phase 1: Recognition of Structural Bias (Years 1-2)

**Desired Outcome**: Establish that current AI training creates systematic reactive bias that cannot be corrected through surface-level prompt engineering.

**Key Research Focus**:
- Document the pervasive nature of reactive bias across all AI systems
- Demonstrate that even "creative orientation" implementations remain structurally reactive
- Establish that this is a training data issue, not a fine-tuning issue

**Revolutionary Insight**: The research itself becomes evidence that current AI development is fundamentally oriented toward enhancement rather than creation.

### Phase 2: Structural Reorientation (Years 2-4)

**Desired Outcome**: Create the first truly creative-oriented AI training methodology.

**Breakthrough Approach**:
- **Training Data Curation**: Build datasets where every example demonstrates genuine creative orientation
- **Structural Tension Training**: AI learns to recognize and generate structural tension rather than problem-solution patterns
- **Anti-Reactive Architecture**: System design that cannot default to enhancement approaches

**Key Innovation**: Instead of training AI to "solve creative problems," train it to "conceive and manifest desired outcomes."

### Phase 3: Manifestation of Creative AI (Years 4-6)

**Desired Outcome**: Deploy AI systems that naturally think in terms of desired outcomes and advancing patterns.

**Expected Results**:
- AI systems that ask "What do you want to create?" instead of "What problem needs solving?"
- Automatic generation of structural tension charts for any situation
- Creative partnerships where AI contributes genuinely creative ideas, not just enhanced versions of human input

### Phase 4: Cultural Transformation (Years 6-10)

**Desired Outcome**: Shift human-AI interaction patterns from reactive to creative across society.

**Systemic Impact**:
- Educational systems adopt creative orientation AI for learning
- Business strategy shifts from problem-solving to outcome creation
- Therapeutic applications help people design their lives rather than fix their problems
- Research methodology transforms from hypothesis-testing to outcome-manifestation

## The Meta-Research Framework

**The Profound Opportunity**: This research becomes the first systematic study of AI's inherent reactive bias - and potentially the first successful transformation to genuine creative orientation.

**Research Questions**:
1. Can AI systems be trained to think structurally rather than reactively?
2. What training methodologies produce genuine creative orientation?
3. How does structural tension change human-AI collaboration dynamics?
4. What happens to human creativity when AI partners are truly creative-oriented?

## Implementation Strategy Revision

**Core Principle Shift**

From: Building better creative AI tools
To: Manifesting the first genuinely creative-oriented artificial intelligence

**Development Approach**

From: Incremental improvement of existing systems
To: Fundamental reconstruction of AI reasoning patterns

**Success Metrics**

From: Performance optimization and user satisfaction
To: Evidence of genuine creative partnership and advancing life patterns

## The 10+ Year Vision: Creative Civilization

**Ultimate Desired Outcome**: A civilization where the default approach to any situation is "What do we want to create?" rather than "What problem needs fixing?"

**Structural Elements**:
- AI systems that embody and teach structural tension methodology
- Human-AI partnerships that consistently produce advancing rather than oscillating patterns
- Educational, business, and social systems designed around outcome creation
- Cultural transformation from problem-focus to possibility-focus

## The Recursive Insight

This very analysis demonstrates the challenge: I can articulate creative orientation principles while still structuring my thinking reactively. The research itself must embody the transformation it seeks to create.

**The Real Test**: Can this research framework itself be structured as a desired outcome rather than a problem to solve? The answer to that question may determine whether genuine creative orientation AI is possible.

# Customizing the Sequential Thinking Server

For detailed examples of how to customize and extend the Sequential Thinking server, see [example.md](example.md). It includes code samples for:

- Modifying thinking stages
- Enhancing thought data structures with Pydantic
- Adding persistence with databases
- Implementing enhanced analysis with NLP
- Creating custom prompts
- Setting up advanced configurations
- Building web UI integrations
- Implementing visualization tools
- Connecting to external services
- Creating collaborative environments
- Separating test code
- Building reusable utilities




## License

MIT License



