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.