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 servernpm run dev- Start with file watchingnpm test- Run comprehensive test suitenpm run build- Build and validate projectnpm run setup- Run setup scriptnpm run init-matrix- Initialize pattern managementnpm run validate- Validate pattern integritynpm run lint- Code lintingnpm 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.