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

Clone and setup:
git clone <repository-url> cd matrix-mcp-server ./setup.sh
Install dependencies:
npm install
Start the server:
npm start
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

Clone repository:
git clone <repository-url> cd matrix-mcp-server
Run setup script:
chmod +x setup.sh ./setup.sh
Install dependencies:
npm install
Validate installation:
npm test npm run validate
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
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

Fork the repository
Create feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
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.

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables advanced pattern management and synchronization for development workflows using a two-dimensional matrix structure. Organizes patterns by development phases and feature domains with intelligent horizontal/vertical synchronization capabilities.

Related MCP Servers

Project Handoffs MCP Server
davidorex
A
security
F
license
A
quality
Facilitates AI session handoffs and next steps tracking through project-based organization, supporting task prioritization and seamless workflow management.
Last updated -
8
7
Software Planning Tool
NightTrek
A
security
A
license
A
quality
Facilitates interactive software development planning by managing tasks, tracking progress, and creating detailed implementation plans through the Model Context Protocol.
Last updated -
6
308
353
MIT License
MCP Design System Bridge
brunonepomuceno
-
security
F
license
-
quality
Enables bidirectional synchronization between IDEs and Figma for Design System management, allowing developers to generate React components and synchronize design tokens, icons, and components across platforms.
Last updated -
Spec Workflow MCP
Pimzino
A
security
A
license
A
quality
Provides structured spec-driven development workflow tools for AI-assisted software development with sequential spec creation (Requirements → Design → Tasks). Features a real-time web dashboard for monitoring project progress and managing development workflows.
Last updated -
14
1,359
493
GPL 3.0

View all related MCP servers