clarity-mcp-server

Clarity Mcp Server

A Model Context Protocol (MCP) server that provides structured reasoning and thinking tools for AI assistants. This server implements multiple cognitive frameworks and reasoning methodologies to enhance problem-solving capabilities.

🧠 Features

The Clarity Mcp Server provides the following reasoning tools:

Core Reasoning Tools

• 🧠 Sequential Thinking: Step-by-step reasoning with revision and branching capabilities
• 🔍 Mental Models: Apply structured mental models (first principles, opportunity cost, etc.)
• 🏗️ Design Patterns: Software architecture and implementation patterns
• ⚡ Programming Paradigms: Different programming approaches (functional, OOP, etc.)
• 🔍 Debugging Approaches: Systematic debugging methodologies
• 🧮 Memory Management: Persistent memory graph with semantic search capabilities

Advanced Reasoning Tools

• 👥 Collaborative Reasoning: Multi-perspective problem solving with virtual personas
• ⚖️ Decision Framework: Structured decision analysis and evaluation
• 🧮 Metacognitive Monitoring: Self-assessment of knowledge and reasoning quality
• 🔬 Scientific Method: Formal scientific reasoning and hypothesis testing
• 📝 Structured Argumentation: Dialectical reasoning and argument analysis
• 🎨 Visual Reasoning: Visual thinking and diagram-based problem solving

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn

Installation

• Clone and setup:

git clone https://github.com/pronitdas/clarity-mcp.git
cd clarity-mcp
pnpm install

• Build the server:

pnpm run build

• Run the server:

pnpm start

Development

# Watch mode for development
pnpm run dev

# Clean build files
pnpm run clean

🛠️ Usage

MCP Integration Guide

The Clear Thought MCP Server is designed to be integrated with AI assistants through the Model Context Protocol (MCP). Here's how to integrate and use the server:

1. Server Connection

• The server runs on stdio transport by default
• Ensure your MCP client is configured to connect via stdio
• Connection URL format: mcp://localhost:0/clear-thinking

2. Authentication

• No authentication required for local development
• For production, implement your authentication strategy in index.ts

3. Tool Registration

Register the tools with your MCP client:

const tools = {
  sequentialthinking: {
    name: "sequentialthinking",
    description: "Step-by-step reasoning with revision capabilities",
    parameters: {
      thought: "string",
      thoughtNumber: "number",
      totalThoughts: "number",
      nextThoughtNeeded: "boolean"
    }
  },
  // ... other tools ...
};

4. Error Handling

• Tools return structured error responses
• Check response.error for error details
• Handle timeouts and connection issues appropriately

MCP Client Configuration

The server can be integrated with MCP-compatible clients using a simple configuration file. Here's a typical example:

{
  "command": "npx",
  "args": [
    "clarity-mcp-server"
  ],
}

Place this configuration in your client's MCP configuration file (e.g., mcp.json). The server will be started automatically when the client needs to use the reasoning tools.

Example Tool Usage

Sequential Thinking

{
  "name": "sequentialthinking",
  "arguments": {
    "thought": "Let me analyze this step by step...",
    "thoughtNumber": 1,
    "totalThoughts": 5,
    "nextThoughtNeeded": true
  }
}

Mental Models

{
  "name": "mentalmodel",
  "arguments": {
    "modelName": "first_principles",
    "problem": "How to optimize database performance"
  }
}

Design Patterns

{
  "name": "designpattern",
  "arguments": {
    "patternName": "modular_architecture",
    "context": "Building a scalable web application"
  }
}

Collaborative Reasoning

{
  "name": "collaborativereasoning",
  "arguments": {
    "topic": "Should we implement microservices?",
    "personas": [
      {
        "id": "architect",
        "name": "Senior Architect",
        "expertise": ["system design", "scalability"],
        "background": "10+ years in enterprise architecture"
      }
    ],
    "stage": "problem-definition",
    "sessionId": "session-1",
    "iteration": 0,
    "nextContributionNeeded": true
  }
}

📋 Tool Reference

Server Components

• SequentialThinkingServer: Manages step-by-step reasoning processes
• MentalModelServer: Handles mental model application
• DesignPatternServer: Processes software design patterns
• ProgrammingParadigmServer: Manages programming approach selection
• DebuggingApproachServer: Handles debugging methodologies
• CollaborativeReasoningServer: Manages multi-perspective analysis
• DecisionFrameworkServer: Handles decision analysis
• MetacognitiveMonitoringServer: Manages self-assessment
• ScientificMethodServer: Handles scientific reasoning
• StructuredArgumentationServer: Manages dialectical analysis
• VisualReasoningServer: Handles visual thinking tools
• MemoryServer: Manages persistent memory operations

Mental Models Available

• first_principles - Break down to fundamental truths
• opportunity_cost - Analyze trade-offs and alternatives
• error_propagation - Understand how errors compound
• rubber_duck - Explain problems step-by-step
• pareto_principle - Focus on vital few factors
• occams_razor - Prefer simpler explanations

Design Patterns Available

• modular_architecture - Component-based design
• api_integration - Service integration patterns
• state_management - State handling strategies
• async_processing - Asynchronous operation patterns
• scalability - Scaling and performance patterns
• security - Security implementation patterns
• agentic_design - Autonomous agent patterns

Programming Paradigms Available

• imperative - Step-by-step instruction style
• procedural - Function-based organization
• object_oriented - Class and object modeling
• functional - Function-based computation
• declarative - Outcome-focused programming
• logic - Rule-based programming
• event_driven - Event-based programming
• aspect_oriented - Cross-cutting concern separation
• concurrent - Parallel execution patterns
• reactive - Event-driven data flows

Debugging Approaches Available

• binary_search - Bisection debugging method
• reverse_engineering - Backward trace analysis
• divide_conquer - Component isolation method
• backtracking - Execution path tracing
• cause_elimination - Process of elimination
• program_slicing - Code dependency analysis

Memory Operations Available

• add - Add new memory nodes
• link - Create relationships between memories
• search - Search across stored memories
• context - Retrieve memory context and relationships

Visual Reasoning Operations

• Operations: create, update, delete, transform, observe
• Diagram Types: graph, flowchart, stateDiagram, conceptMap, treeDiagram, custom
• Element Types: node, edge, container, annotation
• Transform Types: rotate, move, resize, recolor, regroup

🏗️ Architecture

clear-thinking/
├── index.ts              # Main MCP server entry point
├── tools/                # Tool implementations
│   ├── mentalModelServer.ts
│   ├── sequentialThinkingServer.ts
│   ├── designPatternServer.ts
│   ├── programmingParadigmServer.ts
│   ├── debuggingApproachServer.ts
│   ├── collaborativeReasoningServer.ts
│   └── ...               # Other reasoning tools
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

🔧 Configuration

MCP Server Configuration

The server supports the following configuration options in index.ts:

const config = {
  transport: "stdio", // or "tcp" for network transport
  port: 0, // default for stdio
  timeout: 30000, // tool execution timeout in ms
  maxConcurrent: 10, // max concurrent tool executions
  logging: {
    level: "info",
    format: "json"
  }
};

// Server initialization
const server = new Server({
  name: "clarity-mcp-server",
  version: "1.1.2",
  config
}, {
  capabilities: {
    tools: { /* tool definitions */ }
  }
});

🤝 Contributing

• Fork the repository
• Create a feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built on the Model Context Protocol
• Inspired by various cognitive science and reasoning frameworks
• Uses TypeScript for type safety and developer experience

🐛 Troubleshooting

Common Issues

Build Errors:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
npm run build

Runtime Errors:

• Check that all dependencies are installed
• Verify Node.js version (18+)
• Check TypeScript compilation errors

MCP Connection Issues:

• Ensure the server is running on stdio
• Check client MCP configuration
• Verify tool schema compatibility

MCP-Specific Issues

Tool Execution Timeouts:

• Increase timeout in server configuration
• Check for blocking operations in tool implementation
• Monitor system resources

Schema Validation Errors:

• Verify tool parameter types match schema
• Check for required parameters
• Validate enum values are correct

Transport Issues:

• For stdio: Check process stdin/stdout handling
• For TCP: Verify network connectivity and ports
• Check for conflicting transport configurations

📖 Further Reading

• Model Context Protocol Documentation
• TypeScript Documentation
• Reasoning and Cognitive Science Resources