CONTRIBUTING.md•15.7 kB
# Contributing to MCP Self-Learning Server
## 🤝 Welcome Contributors!
Thank you for your interest in contributing to the MCP Self-Learning Server! This guide will help you get started with contributing to this autonomous learning system.
## 📋 Table of Contents
- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Environment](#development-environment)
- [Project Structure](#project-structure)
- [Coding Standards](#coding-standards)
- [Testing Guidelines](#testing-guidelines)
- [Submission Process](#submission-process)
- [Issue Guidelines](#issue-guidelines)
- [Security Policy](#security-policy)
## 🤝 Code of Conduct
This project adheres to a code of conduct. By participating, you are expected to uphold this code:
- **Be Respectful**: Treat all contributors with respect and professionalism
- **Be Inclusive**: Welcome contributors from all backgrounds and skill levels
- **Be Constructive**: Provide helpful feedback and suggestions
- **Be Patient**: Remember that everyone is learning and improving
## 🚀 Getting Started
### Prerequisites
- **Node.js**: Version 18.0.0 or higher
- **NPM**: Version 8.0.0 or higher
- **Git**: Latest stable version
- **Python**: Version 3.8+ (for Python client development)
### Fork & Clone
```bash
# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/mcp-self-learning-server.git
cd mcp-self-learning-server
# Add upstream remote
git remote add upstream https://github.com/saralegui-solutions/mcp-self-learning-server.git
```
### Initial Setup
```bash
# Install dependencies
npm install
# Install globally for CLI testing
npm link
# Verify installation
mcp-learn --version
mcp-learn health
```
## 🔧 Development Environment
### Environment Configuration
Create a development configuration file:
```bash
# Copy example config
cp config/example.json ~/.mcp-learning/dev-config.json
# Set development environment
export NODE_ENV=development
export MCP_LEARN_CONFIG_PATH=~/.mcp-learning/dev-config.json
```
### Development Server
```bash
# Start development server
npm run dev
# Or start with debugging
npm run debug
# Start API server only
npm run api
# Run health check
npm run health
```
### Development Tools
#### Recommended VS Code Extensions
- **ESLint**: Code linting
- **Prettier**: Code formatting
- **Node.js Extension Pack**: Node.js development tools
- **GitLens**: Git integration
- **Thunder Client**: API testing
#### Useful Commands
```bash
# Run linting
npm run lint
# Run type checking (if TypeScript)
npm run typecheck
# Format code
npm run format
# Run all checks
npm run precommit
```
## 📁 Project Structure
```
mcp-self-learning-server/
├── bin/ # CLI executables
│ └── mcp-learn.js # Main CLI tool
├── lib/ # Client libraries
│ ├── self-learning-client.js # Node.js client
│ └── self_learning_client.py # Python client
├── api/ # REST API server
│ └── rest-server.js # Express server
├── integrations/ # External integrations
│ ├── claudio-integration.js # Claudio agent
│ ├── claudio-mcp-tools.js # Claudio MCP tools
│ └── claudia_learning_plugin.py # Claudia plugin
├── tools/ # Utility tools
│ ├── health-check.js # Health monitoring
│ └── monitor.js # Performance monitoring
├── test/ # Test suites
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
├── scripts/ # Build/deployment scripts
│ └── postinstall.js # Post-installation setup
├── data/ # Learning data (gitignored)
├── logs/ # Log files (gitignored)
├── docs/ # Additional documentation
└── config/ # Configuration files
```
## 📝 Coding Standards
### JavaScript/Node.js Standards
#### Code Style
- Use **ES6+ syntax** (import/export, async/await, arrow functions)
- **2 spaces** for indentation
- **Semicolons** required
- **Single quotes** for strings
- **Camelcase** for variables and functions
- **PascalCase** for classes and constructors
#### Example:
```javascript
import { EventEmitter } from 'events';
class LearningEngine extends EventEmitter {
constructor(options = {}) {
super();
this.maxMemorySize = options.maxMemorySize || 1000;
this.patterns = new Map();
}
async analyzePattern(interaction) {
const features = this.extractFeatures(interaction);
const patternId = this.generatePatternId(features);
if (this.patterns.has(patternId)) {
return this.updateExistingPattern(patternId, interaction);
}
return this.createNewPattern(patternId, features, interaction);
}
}
```
### Python Standards
Follow **PEP 8** guidelines:
- **4 spaces** for indentation
- **snake_case** for variables and functions
- **PascalCase** for classes
- **UPPER_CASE** for constants
- **Type hints** for function parameters and returns
#### Example:
```python
from typing import Dict, List, Optional, Any
import asyncio
import aiohttp
class SelfLearningClient:
"""Python client for MCP Self-Learning Server"""
def __init__(self, base_url: str = "http://localhost:8765",
timeout: int = 30) -> None:
self.base_url = base_url.rstrip('/')
self.timeout = timeout
self.session: Optional[aiohttp.ClientSession] = None
async def analyze_pattern(self, interaction: Dict[str, Any]) -> Dict[str, Any]:
"""Analyze an interaction pattern for learning"""
if not self.session:
raise RuntimeError("Client not connected")
async with self.session.post(
f"{self.base_url}/analyze",
json={"interaction": interaction}
) as response:
return await response.json()
```
### Documentation Standards
#### Code Comments
```javascript
/**
* Analyzes interaction patterns and extracts learning features
*
* @param {Object} interaction - The interaction to analyze
* @param {string} interaction.type - Type of interaction (e.g., 'tool_usage')
* @param {string} interaction.input - Input to the interaction
* @param {string} interaction.output - Output from the interaction
* @param {boolean} interaction.success - Whether the interaction succeeded
* @returns {Promise<Object>} Analysis results with pattern ID and features
* @throws {Error} If interaction is invalid or analysis fails
*/
async analyzePattern(interaction) {
// Implementation...
}
```
#### README Updates
- Update README.md for new features
- Include code examples for new APIs
- Update installation instructions if needed
- Add new integration examples
## 🧪 Testing Guidelines
### Test Structure
#### Unit Tests (`test/unit/`)
```javascript
// test/unit/learning-engine.test.js
import { LearningEngine } from '../../mcp-self-learning-server.js';
describe('LearningEngine', () => {
let engine;
beforeEach(() => {
engine = new LearningEngine({ maxMemorySize: 100 });
});
describe('analyzePattern', () => {
it('should analyze valid interaction pattern', async () => {
const interaction = {
type: 'test_interaction',
input: 'test input',
output: 'test output',
success: true
};
const result = await engine.analyzePattern(interaction);
expect(result.success).toBe(true);
expect(result.patternId).toBeDefined();
expect(result.features).toHaveProperty('toolSequence');
});
it('should handle invalid interaction gracefully', async () => {
const invalidInteraction = { type: 'test' }; // Missing required fields
await expect(engine.analyzePattern(invalidInteraction))
.rejects.toThrow('Invalid interaction');
});
});
});
```
#### Integration Tests (`test/integration/`)
```javascript
// test/integration/api-server.test.js
import axios from 'axios';
import { SelfLearningMCPServer } from '../../mcp-self-learning-server.js';
describe('API Integration', () => {
let server;
const baseURL = 'http://localhost:8766'; // Test port
beforeAll(async () => {
server = new SelfLearningMCPServer();
await server.startAPIServer(8766);
});
afterAll(async () => {
await server.stop();
});
it('should return healthy status', async () => {
const response = await axios.get(`${baseURL}/health`);
expect(response.status).toBe(200);
expect(response.data.status).toBe('healthy');
});
});
```
### Running Tests
```bash
# Run all tests
npm test
# Run unit tests only
npm run test:unit
# Run integration tests only
npm run test:integration
# Run with coverage
npm run test:coverage
# Run specific test file
npm test -- test/unit/learning-engine.test.js
# Run tests in watch mode
npm run test:watch
```
### Test Requirements
#### For New Features
- **Unit tests** for all new functions/methods
- **Integration tests** for new API endpoints
- **Client library tests** for new client methods
- **End-to-end tests** for complete workflows
#### Test Coverage
- Maintain **>85%** code coverage
- Test both **success and failure cases**
- Include **edge cases** and **boundary conditions**
- Mock external dependencies appropriately
## 🔄 Submission Process
### Branch Naming
Use descriptive branch names:
```bash
# Feature branches
git checkout -b feature/add-learning-analytics
git checkout -b feature/improve-pattern-matching
# Bug fixes
git checkout -b fix/memory-leak-in-learning-cycle
git checkout -b fix/api-error-handling
# Documentation
git checkout -b docs/update-api-documentation
git checkout -b docs/add-deployment-guide
```
### Commit Messages
Follow conventional commit format:
```bash
# Feature commits
git commit -m "feat: add real-time learning analytics dashboard"
git commit -m "feat(api): add batch pattern analysis endpoint"
# Bug fixes
git commit -m "fix: resolve memory leak in learning cycle"
git commit -m "fix(client): handle connection timeouts gracefully"
# Documentation
git commit -m "docs: add comprehensive API documentation"
git commit -m "docs(readme): update installation instructions"
# Performance improvements
git commit -m "perf: optimize pattern matching algorithm"
git commit -m "perf(db): add indexing for faster queries"
# Refactoring
git commit -m "refactor: extract learning algorithm to separate module"
git commit -m "refactor(tests): improve test organization"
```
### Pull Request Process
#### Before Submitting
```bash
# Update your branch
git fetch upstream
git rebase upstream/main
# Run all checks
npm run lint
npm test
npm run typecheck
# Build and test globally
npm run build
npm link
mcp-learn health
```
#### PR Template
Use this template for pull requests:
```markdown
## 🚀 Changes
Brief description of what this PR does.
## 📋 Type of Change
- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
- [ ] ✨ New feature (non-breaking change which adds functionality)
- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] 📚 Documentation update
- [ ] 🔧 Configuration change
- [ ] ♻️ Refactoring (no functional changes)
## 🧪 Testing
- [ ] Unit tests pass (`npm run test:unit`)
- [ ] Integration tests pass (`npm run test:integration`)
- [ ] Manual testing completed
- [ ] CLI tools tested (`mcp-learn` commands)
- [ ] API endpoints tested
- [ ] Client libraries tested
## 📝 Checklist
- [ ] My code follows the project's coding standards
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
## 📊 Performance Impact
- [ ] No performance impact
- [ ] Minimal performance impact (<5% change)
- [ ] Significant performance improvement
- [ ] Performance impact requires discussion
## 🔗 Related Issues
Closes #[issue number]
Related to #[issue number]
## 📸 Screenshots/Examples
Include screenshots, code examples, or API responses if applicable.
```
#### Review Process
1. **Automated Checks**: CI/CD runs tests and linting
2. **Code Review**: Maintainers review code quality and design
3. **Testing**: Reviewers test functionality manually
4. **Discussion**: Address feedback and suggestions
5. **Approval**: PR approved by at least one maintainer
6. **Merge**: Squash and merge to main branch
## 🐛 Issue Guidelines
### Bug Reports
Use the bug report template:
```markdown
## 🐛 Bug Description
Clear and concise description of the bug.
## 🔄 Steps to Reproduce
1. Start the server with `mcp-learn start`
2. Send API request to `/analyze`
3. Observe error in logs
## 📋 Expected Behavior
What should happen instead.
## 🖥️ Environment
- OS: Ubuntu 22.04
- Node.js: v18.17.0
- NPM: v9.6.7
- Package Version: v1.0.0
## 📸 Screenshots/Logs
Include relevant logs or screenshots.
## 🔍 Additional Context
Any other relevant information.
```
### Feature Requests
```markdown
## ✨ Feature Request
**Is your feature request related to a problem?**
Clear description of the problem this feature would solve.
**Describe the solution you'd like**
Clear description of what you want to happen.
**Describe alternatives you've considered**
Other approaches you've thought about.
**Additional context**
Screenshots, mockups, or examples.
**Implementation suggestions**
Any ideas about how this could be implemented.
```
## 🔒 Security Policy
### Reporting Security Issues
**DO NOT** create public issues for security vulnerabilities. Instead:
1. Email: security@saralegui-solutions.com
2. Include: Detailed description and reproduction steps
3. Response: We'll respond within 48 hours
### Security Guidelines
- Never commit secrets, tokens, or credentials
- Use environment variables for sensitive configuration
- Validate all input data
- Implement proper error handling
- Follow security best practices for APIs
## 🎯 Areas for Contribution
### High Priority
- **Performance Optimization**: Improve learning algorithm efficiency
- **Memory Management**: Better memory usage patterns
- **Error Handling**: More robust error recovery
- **Documentation**: API examples and tutorials
### Medium Priority
- **New Integrations**: Support for additional AI frameworks
- **Monitoring**: Enhanced metrics and dashboards
- **Testing**: Increase test coverage
- **CLI Improvements**: New commands and features
### Good First Issues
- **Documentation fixes**: Typos, unclear instructions
- **Code cleanup**: Remove unused imports, format code
- **Simple bug fixes**: Edge cases, validation improvements
- **Test additions**: Cover untested code paths
## 🏆 Recognition
Contributors will be recognized in:
- **README.md Contributors section**
- **Release notes** for significant contributions
- **GitHub Discussions** for helpful community support
## 📞 Getting Help
- **GitHub Discussions**: For questions and community support
- **Issues**: For bug reports and feature requests
- **Email**: dev@saralegui-solutions.com for direct communication
- **Discord**: [Community Server Link] for real-time chat
Thank you for contributing to the MCP Self-Learning Server! Your contributions help improve autonomous learning for AI agent systems worldwide. 🚀