# 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:**
   ```bash
   git clone <repository-url>
   cd matrix-mcp-server
   ./setup.sh
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Start the server:**
   ```bash
   npm start
   ```

4. **Add to Claude configuration:**
   ```bash
   # 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.

```javascript
// 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.

```javascript
// 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.

```javascript
// 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.

```javascript
// 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).

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

### 6. `matrix_list_horizontals` - List Row Cells
Show all cells in a horizontal row (development phase).

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

### 7. `matrix_read_horizontal_instructions` - Get Sync Instructions
Retrieve synchronization instructions and metadata for horizontal patterns.

```javascript
// 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`:

```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

```javascript
// 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

```javascript
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:**
   ```bash
   git clone <repository-url>
   cd matrix-mcp-server
   ```

2. **Run setup script:**
   ```bash
   chmod +x setup.sh
   ./setup.sh
   ```

3. **Install dependencies:**
   ```bash
   npm install
   ```

4. **Validate installation:**
   ```bash
   npm test
   npm run validate
   ```

5. **Configure Claude MCP:**
   ```bash
   # 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:**
   ```bash
   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
```bash
# 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
```javascript
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
```javascript
// 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:

```javascript
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.