README.md•12.9 kB
# 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.