Content
# 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
1. **Clone and setup:**
```bash
git clone https://github.com/pronitdas/clarity-mcp.git
cd clarity-mcp
pnpm install
```
2. **Build the server:**
```bash
pnpm run build
```
3. **Run the server:**
```bash
pnpm start
```
### Development
```bash
# 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:
```typescript
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:
```json
{
"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
```json
{
"name": "sequentialthinking",
"arguments": {
"thought": "Let me analyze this step by step...",
"thoughtNumber": 1,
"totalThoughts": 5,
"nextThoughtNeeded": true
}
}
```
#### Mental Models
```json
{
"name": "mentalmodel",
"arguments": {
"modelName": "first_principles",
"problem": "How to optimize database performance"
}
}
```
#### Design Patterns
```json
{
"name": "designpattern",
"arguments": {
"patternName": "modular_architecture",
"context": "Building a scalable web application"
}
}
```
#### Collaborative Reasoning
```json
{
"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`:
```typescript
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
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. 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](https://modelcontextprotocol.io/)
- Inspired by various cognitive science and reasoning frameworks
- Uses TypeScript for type safety and developer experience
## 🐛 Troubleshooting
### Common Issues
**Build Errors:**
```bash
# 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](https://modelcontextprotocol.io/docs)
- [TypeScript Documentation](https://www.typescriptlang.org/docs/)
- [Reasoning and Cognitive Science Resources](https://en.wikipedia.org/wiki/Cognitive_science)
