# MCP Self-Learning Server

A sophisticated Model Context Protocol (MCP) server that autonomously learns from interactions, optimizes performance, and continuously improves its knowledge base through pattern recognition and machine learning techniques.

## 🌟 Features

### 🧠 Autonomous Learning Engine
- **Pattern Recognition**: Automatically identifies and learns from interaction patterns
- **Feature Extraction**: Analyzes tool sequences, context, performance metrics, and semantic embeddings
- **Confidence Scoring**: Evaluates pattern reliability based on frequency, recency, and consistency
- **Memory Consolidation**: Manages short-term and long-term pattern storage

### 🔄 Knowledge Synchronization
- **Auto-sync**: Every 60 seconds between MCP servers
- **Knowledge Export/Import**: JSON and Markdown formats
- **Pattern Merging**: With deduplication
- **Cross-server Learning**: Through shared knowledge directory

### 📊 Self-Improvement Capabilities
- **Performance Optimization**: Identifies redundancies and bottlenecks
- **Predictive Suggestions**: Anticipates next actions based on learned patterns
- **Error Pattern Analysis**: Learns from failures to improve success rates
- **Adaptive Recommendations**: Generates context-aware optimizations

### 💾 Data Persistence
- **Automatic Data Saving**: Every 5 minutes with backup rotation
- **Learning Data Recovery**: Loads previous sessions on startup
- **Export Knowledge**: Multiple formats (JSON, Markdown)
- **Backup System**: Automatic backup creation before saves

### 📝 Advanced Logging
- **Multi-level Logging**: Debug, Info, Warn, Error with colors and emojis
- **File & Console Output**: Simultaneous logging to both
- **Log Rotation**: Prevents disk space issues
- **Performance Monitoring**: Tool execution times and memory usage

## 🚀 Quick Start

### Prerequisites
- Node.js 18+ 
- npm or yarn

### Installation

1. **Clone/Download the Project**
   ```bash
   cd ~/saralegui-solutions-llc/shared/MCPSelfLearningServer
   ```

2. **Install Dependencies**
   ```bash
   npm install
   ```

3. **Configure Claude Desktop**
   
   Add to `~/.config/Claude/claude_desktop_config.json`:
   ```json
   {
     "mcpServers": {
       "self-learning": {
         "command": "node",
         "args": ["/home/ben/saralegui-solutions-llc/shared/MCPSelfLearningServer/mcp-self-learning-server.js"],
         "env": {
           "NODE_ENV": "production",
           "LEARNING_MODE": "autonomous"
         }
       }
     }
   }
   ```

4. **Start the Server**
   ```bash
   npm start
   ```

## 📋 Available Commands

### Development & Testing
```bash
npm run dev          # Start in development mode
npm run debug        # Start with debug logging
npm test             # Run all tests
npm run test:unit    # Run unit tests only
npm run test:integration  # Run integration tests only
```

### Monitoring & Health
```bash
npm run health       # Run comprehensive health check
npm run monitor      # Real-time monitoring
npm run monitor:details  # Detailed monitoring with change tracking
```

### Manual Operations
```bash
# Health check
node tools/health-check.js

# Real-time monitoring
node tools/monitor.js [--interval 5] [--details]

# Start server directly
node mcp-self-learning-server.js
```

## 🛠️ Available MCP Tools

### Core Learning Tools

#### `analyze_pattern`
Analyze and learn from interaction patterns
```json
{
  "interaction": {
    "type": "tool_usage",
    "input": "user input",
    "output": "tool output", 
    "context": {},
    "performance": { "duration": 100 },
    "success": true
  }
}
```

#### `get_insights`
Get current learning analytics and insights
```json
{}
```

#### `trigger_learning`
Manually trigger a learning cycle
```json
{}
```

### Knowledge Management

#### `export_knowledge`
Export learned knowledge to file
```json
{
  "format": "json|markdown"  // Optional, defaults to json
}
```

#### `import_knowledge`
Import knowledge from external source
```json
{
  "source": "file_path_or_url",
  "format": "json"  // Optional
}
```

### Performance & Optimization

#### `optimize_tool`
Get optimization suggestions for specific tools
```json
{
  "tool_name": "example_tool"  // Optional
}
```

#### `predict_next_action`
Get predictive suggestions based on current context
```json
{
  "context": {
    "current_tool": "analyze_pattern",
    "user_intent": "optimization"
  }
}
```

#### `get_performance_metrics`
Get detailed performance analytics
```json
{
  "tool_name": "specific_tool"  // Optional, for tool-specific metrics
}
```

## 📊 Monitoring & Analytics

### Health Check Results
The health check tool verifies:
- ✅ Server startup functionality
- ✅ Data persistence system
- ✅ Logging system
- ✅ Performance metrics (startup time)

### Real-time Monitoring
The monitor displays:
- Learning engine status (patterns, knowledge, cycles)
- Log file metrics and activity
- System resource usage
- Change indicators showing growth over time

### Performance Expectations

| Metric | Target | Excellent |
|--------|--------|-----------|
| Startup Time | <5s | <1s |
| Memory Usage | <100MB | <50MB |
| Response Time | <500ms | <100ms |
| Learning Accuracy | >70% | >90% |

## 🗂️ Directory Structure

```
MCPSelfLearningServer/
├── mcp-self-learning-server.js    # Main server file
├── package.json                   # Dependencies and scripts
├── README.md                      # This file
├── data/                         # Persistent learning data
│   ├── learning-engine.json      # Main learning data
│   └── learning-engine.backup.json # Backup
├── logs/                         # Server logs
│   └── mcp-server.log           # Main log file
├── lib/                         # Shared libraries
│   └── logger.js               # Enhanced logging system
├── test/                       # Test suites
│   ├── unit/                  # Unit tests
│   └── integration/          # Integration tests
└── tools/                    # Development tools
    ├── health-check.js      # Health check tool
    └── monitor.js          # Real-time monitoring
```

## 🔧 Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `NODE_ENV` | `production` | Environment mode |
| `LOG_LEVEL` | `info` | Logging level (debug/info/warn/error) |
| `LOG_CONSOLE` | `true` | Enable console logging |
| `LOG_FILE` | `true` | Enable file logging |
| `LEARNING_MODE` | `autonomous` | Learning behavior mode |

### Learning Engine Settings

- **Max Memory Size**: 1000 patterns in memory
- **Auto-save Interval**: 5 minutes
- **Pattern Confidence Threshold**: 0.5
- **Learning Trigger**: Every 100 interactions or 50 tool uses

## 🚨 Troubleshooting

### Common Issues

1. **Server Won't Start**
   - Check Node.js version (18+ required)
   - Verify all dependencies installed: `npm install`
   - Check file permissions

2. **Data Not Persisting**
   - Verify `data/` directory permissions
   - Check disk space
   - Review logs for errors: `tail -f logs/mcp-server.log`

3. **High Memory Usage**
   - Run health check: `npm run health`
   - Check pattern count: `npm run monitor`
   - Consider reducing max memory size

4. **Slow Performance**
   - Enable performance logging: `npm run debug`
   - Check system resources
   - Review learning cycle frequency

### Log Analysis

```bash
# View recent logs
tail -f logs/mcp-server.log

# Search for errors
grep "ERROR" logs/mcp-server.log

# Count log levels
grep -c "INFO\|WARN\|ERROR" logs/mcp-server.log
```

## 📈 Expected Learning Outcomes

### Immediate (0-100 interactions)
- Basic pattern recognition active
- Initial knowledge base building
- Tool usage tracking enabled

### Short-term (100-1000 interactions)
- Pattern confidence scores stabilizing
- First optimization recommendations
- Predictive accuracy ~50%

### Long-term (1000+ interactions)
- Predictive accuracy >70%
- Response time improvements ~30%
- Comprehensive knowledge graph
- Cross-server knowledge sharing
- Self-documenting insights

## 🤝 Integration with Claude

Once configured, the server provides these tools in Claude:
- Pattern analysis for learning from conversations
- Performance insights for optimization
- Predictive suggestions for improved responses
- Knowledge export for documentation
- Real-time learning from every interaction

## 📝 License

ISC License

## 🆘 Support

For issues or questions:
1. Run health check: `npm run health`
2. Check logs: `tail -f logs/mcp-server.log` 
3. Review this documentation
4. Check server status: `npm run monitor`

---

**Built with ❤️ for autonomous learning and continuous improvement**