Matrix Pattern MCP Server

Advanced pattern management and synchronization MCP server for Claude applications. The Matrix Pattern System provides a structured approach to organizing and coordinating complex development patterns across multiple dimensions.

🚀 Quick Start

1. Clone and setup:

   git clone <repository-url>
   cd matrix-mcp-server
   ./setup.sh

2. Install dependencies:

   npm install

3. Start the server:

   npm start

4. Add to Claude configuration:

   # Copy the provided configuration
   cp claude_mcp_config.json ~/.claude/mcp_servers.json

📊 Matrix Pattern System Overview

The Matrix Pattern System organizes development patterns in a two-dimensional structure:

• Horizontal (Rows): Different pattern types (requirements, architecture, implementation, etc.)
• Vertical (Columns): Feature domains (authentication, data-processing, ui-components, etc.)

Key Concepts

• Forward-Only Constraint: Cells can only be created once, ensuring pattern integrity
• Horizontal Synchronization: Share patterns across feature domains
• Vertical Synchronization: Cascade updates through development phases
• Metadata Tracking: Comprehensive lifecycle and relationship tracking

🛠️ Available Tools (7 Total)

1. matrix_create_cell - Create Pattern Cells

Create new cells in the matrix pattern system.

// Example: Create authentication requirements cell
{
  "cellId": {
    "row": "requirements", 
    "column": "authentication"
  },
  "data": {
    "content": "# Authentication Requirements\n\n## Functional Requirements\n- User login with email/password\n- Multi-factor authentication support\n- Session management\n\n## Non-Functional Requirements\n- Security: OAuth 2.0 compliance\n- Performance: < 2s login time\n- Availability: 99.9% uptime",
    "metadata": {
      "priority": "high",
      "horizontal_type": "requirements"
    }
  }
}

2. matrix_read_cell - Read Pattern Cells

Retrieve cell content and metadata.

// Example: Read specific cell
{
  "cellId": {
    "row": "architecture",
    "column": "authentication"
  }
}

3. matrix_sync_horizontal - Horizontal Pattern Sync

Synchronize patterns across feature domains within the same development phase.

// Example: Sync requirements from authentication to authorization
{
  "sourceRow": "requirements",
  "targetRow": "requirements", 
  "columns": ["authentication", "authorization"]
}

4. matrix_sync_vertical - Vertical Pattern Sync

Cascade patterns from one development phase to another.

// Example: Sync authentication from requirements to architecture
{
  "column": "authentication",
  "fromRow": "requirements",
  "toRow": "architecture"
}

5. matrix_list_verticals - List Column Cells

Show all cells in a vertical column (feature domain).

// Example: List all authentication-related cells
{
  "column": "authentication"
}

6. matrix_list_horizontals - List Row Cells

Show all cells in a horizontal row (development phase).

// Example: List all requirement cells
{
  "row": "requirements"
}

7. matrix_read_horizontal_instructions - Get Sync Instructions

Retrieve synchronization instructions and metadata for horizontal patterns.

// Example: Get requirements sync instructions
{
  "row": "requirements"
}

📁 Project Structure

matrix-mcp-server/
├── src/                          # Source code
│   ├── index.js                  # Main MCP server
│   ├── validator.js              # Cell content validator
│   ├── matrix-fs.js              # File system utilities
│   ├── sync-engine.js            # Synchronization engine
│   └── test/                     # Test files
├── .matrix_pattern/              # Matrix Pattern system files
│   ├── matrix/                   # Pattern storage (*.json files)
│   ├── metadata/                 # Pattern metadata
│   │   ├── horizontals/          # Horizontal pattern metadata
│   │   └── sync-reports/         # Synchronization reports
│   │       ├── horizontal/       # Horizontal sync reports
│   │       └── vertical/         # Vertical sync reports
│   └── config.json               # System configuration
├── claude_mcp_config.json        # Claude MCP configuration
├── package.json                  # Project configuration
├── setup.sh                      # Setup script
└── README.md                     # This file

⚙️ Configuration

Claude MCP Configuration

The claude_mcp_config.json file contains the complete MCP server configuration for Claude integration.

System Configuration

The Matrix Pattern system is configured via .matrix_pattern/config.json:

{
  "matrix_pattern": {
    "version": "1.0.0",
    "initialized": true,
    "config": {
      "max_patterns": 1000,
      "auto_cleanup": true,
      "sync": {
        "horizontal": {
          "conflict_resolution": "manual"
        },
        "vertical": {
          "auto_cascade": false
        }
      }
    }
  }
}

🎯 Usage Examples

Complete Development Flow

// 1. Create requirements cell
matrix_create_cell({
  cellId: { row: "requirements", column: "user-management" },
  data: { 
    content: "# User Management Requirements\n- User registration\n- Profile management\n- Account deactivation",
    metadata: { horizontal_type: "requirements" }
  }
})

// 2. Sync to architecture phase
matrix_sync_vertical({
  column: "user-management",
  fromRow: "requirements", 
  toRow: "architecture"
})

// 3. List all user-management cells
matrix_list_verticals({
  column: "user-management"
})

// 4. Sync architecture across related features
matrix_sync_horizontal({
  sourceRow: "architecture",
  targetRow: "architecture",
  columns: ["user-management", "authentication"]
})

Content Validation

import { CellValidator } from './src/validator.js';

const validator = new CellValidator();
const result = validator.validateCell(cellData, { 
  horizontal_type: 'requirements' 
});

console.log(validator.getValidationSummary(result));

🧪 Available Scripts

• npm start - Start the MCP server
• npm run dev - Start with file watching
• npm test - Run comprehensive test suite
• npm run build - Build and validate project
• npm run setup - Run setup script
• npm run init-matrix - Initialize pattern management
• npm run validate - Validate pattern integrity
• npm run lint - Code linting
• npm run format - Code formatting

🏗️ Core Features

1. Advanced Pattern Management

• Cell-based Storage: Each pattern stored as individual JSON cell
• Metadata Tracking: Comprehensive lifecycle and relationship tracking
• Version Control: Pattern version management and history
• Schema Validation: Content structure validation with CellValidator

2. Multi-Dimensional Synchronization

• Horizontal Sync: Share patterns across feature domains
• Vertical Sync: Cascade patterns through development phases
• Selective Sync: Choose specific columns/cells to synchronize
• Conflict Detection: Intelligent conflict resolution mechanisms

3. Content Validation System

• Format Validation: Markdown structure and formatting checks
• Section Requirements: Validate required sections per horizontal type
• Quality Assessment: Content quality scoring (0-100)
• Custom Validators: Extensible validation system

4. Intelligent Reporting

• Sync Reports: Detailed synchronization operation reports
• Quality Metrics: Content quality and completeness tracking
• Relationship Mapping: Track dependencies and relationships
• Audit Trail: Complete operation history

🔧 Installation & Setup

Prerequisites

• Node.js >= 18.0.0
• npm package manager
• Claude CLI (for MCP integration)

Step-by-Step Installation

1. Clone repository:

   git clone <repository-url>
   cd matrix-mcp-server

2. Run setup script:

   chmod +x setup.sh
   ./setup.sh

3. Install dependencies:

   npm install

4. Validate installation:

   npm test
   npm run validate

5. Configure Claude MCP:

   # Copy configuration to Claude
   cp claude_mcp_config.json ~/.claude/mcp_servers.json
      
   # Or merge with existing configuration
   cat claude_mcp_config.json >> ~/.claude/mcp_servers.json

6. Start the server:

   npm start

🚨 Troubleshooting Guide

Common Issues

1. Server Connection Failed

Symptoms: Server not responding, connection timeout Solutions:

• Check Node.js version: node --version (must be >= 18.0.0)
• Verify server is running: npm start
• Check working directory path in claude_mcp_config.json
• Ensure dependencies installed: npm install

2. Cell Creation Validation Errors

Symptoms: Cell creation fails, validation error messages Solutions:

• Verify cell data format matches schema
• Ensure cellId has both row and column properties
• Check content is non-empty string
• Use CellValidator to validate content before creation

3. Synchronization Issues

Symptoms: Sync operations fail, forward-only constraint errors Solutions:

• Verify source cells exist before syncing
• Check target cells don't exist (forward-only constraint)
• Review sync reports in .matrix_pattern/metadata/sync-reports/
• Ensure proper file permissions on .matrix_pattern/ directory

4. File Permission Errors

Symptoms: Cannot read/write matrix files Solutions:

• Check directory permissions: ls -la .matrix_pattern/
• Fix permissions: chmod -R 755 .matrix_pattern/
• Re-run setup: ./setup.sh

Debugging Tools

Log Files

• Server logs: .matrix_pattern/logs/server.log
• Sync reports: .matrix_pattern/metadata/sync-reports/
• Error logs: Check console output during operations

Diagnostic Commands

# Check system status
npm run validate

# Run comprehensive tests
npm test

# Check Node.js version
node --version

# Verify MCP configuration
cat claude_mcp_config.json | jq .

# Check directory structure
ls -la .matrix_pattern/

🔍 Advanced Usage

Custom Validation Rules

import { CellValidator } from './src/validator.js';

const customValidator = CellValidator.createValidator({
  strict_mode: true,
  custom_validators: [
    (cellData) => {
      if (cellData.content.includes('TODO')) {
        return {
          errors: [{
            type: 'content_quality',
            message: 'TODO items not allowed in production cells',
            severity: 'high'
          }]
        };
      }
      return { valid: true };
    }
  ]
});

Batch Operations

// Validate multiple cells
const batchResult = validator.validateBatch([cell1, cell2, cell3]);
console.log(`${batchResult.passed}/${batchResult.total} cells passed validation`);

Pattern Templates

Create reusable pattern templates for consistent cell structure:

const requirementTemplate = {
  content: `# {FEATURE_NAME} Requirements

## Functional Requirements
- TODO: Add functional requirements

## Non-Functional Requirements  
- Performance: TODO: Add performance requirements
- Security: TODO: Add security requirements
- Scalability: TODO: Add scalability requirements

## Acceptance Criteria
- TODO: Add acceptance criteria`,
  metadata: {
    horizontal_type: "requirements",
    template_version: "1.0.0"
  }
};

📈 Performance Considerations

• File System: Uses efficient JSON file storage with fs-extra
• Caching: Implements intelligent caching for frequently accessed cells
• Batch Operations: Supports batch validation and operations
• Memory Management: Optimized for large pattern collections
• Concurrent Access: Thread-safe operations with proper locking

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open pull request

📄 License

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

🆘 Support

• Documentation: Check this README and inline code comments
• Issues: Create GitHub issues for bugs and feature requests
• Community: Join discussions in the repository
• Professional Support: Contact for enterprise support options

Matrix Pattern System - Organize, synchronize, and scale your development patterns with confidence.