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

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