mcp-context-engineering/CONTRIBUTING.md

The intelligent context optimization system for AI coding assistants. Built with Cole's PRP methodology, Context Portal knowledge graphs, and production-ready MongoDB architecture.

# Contributing to Universal Context Engineering MCP Server

Thank you for your interest in contributing! This project aims to be the definitive context engineering solution for AI coding assistants.

## 🚀 **Quick Start for Contributors**

### Prerequisites
- Node.js 18.12+
- MongoDB (local or Atlas)
- TypeScript knowledge
- Understanding of MCP (Model Context Protocol)

### Setup Development Environment
```bash
git clone https://github.com/romiluz13/mcp-context-engineering.git
cd mcp-context-engineering
npm install
cp .env.example .env
# Edit .env with your MongoDB and API keys
npm run build
npm run dev
```

## 📋 **How to Contribute**

### 1. **Types of Contributions Welcome**
- 🐛 **Bug fixes** - Help us squash bugs
- ✨ **New features** - Enhance the context engineering capabilities  
- 📚 **Documentation** - Improve guides and examples
- 🧪 **Tests** - Expand test coverage
- 🔧 **Performance** - Optimize performance and scalability
- 🎯 **Agent Support** - Add support for new AI coding agents

### 2. **Development Workflow**

#### Step 1: Fork & Branch
```bash
# Fork the repo on GitHub, then:
git clone https://github.com/YOUR_USERNAME/mcp-context-engineering.git
cd mcp-context-engineering
git checkout -b feature/amazing-new-feature
```

#### Step 2: Make Changes
- Follow the existing code style and patterns
- Add tests for new functionality
- Update documentation as needed
- Ensure TypeScript types are properly defined

#### Step 3: Test Your Changes
```bash
npm run build        # Ensure it builds
npm run test         # Run tests (when available)
npm run lint         # Check code style
npm run dev          # Test with actual MCP agent
```

#### Step 4: Commit & Push
```bash
git add .
git commit -m "feat: add amazing new feature"
git push origin feature/amazing-new-feature
```

#### Step 5: Create Pull Request
- Open PR on GitHub
- Describe what your changes do
- Link any related issues
- Wait for review

## 🏗️ **Architecture Guidelines**

### Code Organization
```
src/
├── config/          # Environment & configuration
├── context/         # Context engineering logic
│   └── methodology/ # PRP generation & research
├── mcp/            # MCP server & tools
├── mongodb/        # Database layer
│   ├── models/     # Zod schemas & types
│   └── operations/ # Database operations
└── index.ts        # Entry point
```

### Key Principles
1. **Type Safety**: Use TypeScript strictly with Zod validation
2. **Error Handling**: Comprehensive error handling at all levels
3. **Modularity**: Clean separation of concerns
4. **Testing**: Test critical functionality (when tests are added)
5. **Documentation**: Code should be self-documenting with good naming

## 🎯 **MCP Tool Development**

### Adding New MCP Tools
1. **Define the tool** in `src/mcp/server.ts` `ListToolsRequestSchema` handler
2. **Implement handler** method (e.g., `handleYourNewTool`)
3. **Add to switch statement** in `CallToolRequestSchema` handler
4. **Add proper validation** using Zod schemas
5. **Include error handling** and user-friendly responses
6. **Update documentation** and examples

### MCP Tool Standards
- **Input validation** with Zod schemas
- **Comprehensive error handling** with user-friendly messages
- **Agent optimization** - consider different AI agent needs
- **MongoDB integration** where relevant
- **Learning integration** - track effectiveness when possible

## 🧪 **Testing Guidelines**

### Manual Testing Checklist
- [ ] Server starts without errors
- [ ] MongoDB connection established
- [ ] All MCP tools respond correctly
- [ ] Error handling works properly
- [ ] Agent-specific formatting works
- [ ] Environment validation functions

### Test Data
Use realistic but anonymized test data:
- Project contexts with common tech stacks
- Feature descriptions that represent real use cases
- Varied complexity levels and agent types

## 📝 **Code Style**

### TypeScript Guidelines
- Use strict TypeScript configuration
- Define proper interfaces and types
- Use Zod for runtime validation
- Prefer `const` over `let` when possible
- Use descriptive variable and function names

### Formatting
```bash
npm run format      # Prettier formatting
npm run lint        # ESLint validation
npm run lint:fix    # Auto-fix linting issues
```

### Commit Messages
Follow conventional commits:
- `feat:` - New features
- `fix:` - Bug fixes  
- `docs:` - Documentation changes
- `style:` - Code style changes
- `refactor:` - Code refactoring
- `test:` - Test additions/changes
- `chore:` - Maintenance tasks

## 🐛 **Bug Reports**

### Before Reporting
1. Check existing issues for duplicates
2. Test with latest version
3. Verify it's not a configuration issue

### Bug Report Template
```markdown
**Bug Description**
Clear description of the bug

**Steps to Reproduce**
1. Step one
2. Step two
3. Step three

**Expected Behavior**
What should happen

**Actual Behavior**  
What actually happens

**Environment**
- Node.js version:
- MongoDB version:
- Operating System:
- AI Agent:

**Additional Context**
Any other relevant information
```

## ✨ **Feature Requests**

### Feature Request Template
```markdown
**Feature Description**
Clear description of the proposed feature

**Use Case**
Why is this feature needed?

**Proposed Implementation**
How might this be implemented?

**Alternatives Considered**
Any alternative approaches?

**Additional Context**
Screenshots, mockups, etc.
```

## 📚 **Documentation**

### Documentation Standards
- Clear, concise explanations
- Include code examples
- Cover common use cases
- Update when making changes
- Use proper markdown formatting

### Areas Needing Documentation
- MCP tool usage examples
- Configuration options
- Architecture decisions
- Performance optimization tips
- Troubleshooting guides

## 🚀 **Release Process**

### Version Management
- Follow semantic versioning (SemVer)
- Update `package.json` version
- Create git tags for releases
- Update CHANGELOG.md

### Release Checklist
- [ ] All tests pass
- [ ] Documentation updated
- [ ] Version bumped appropriately
- [ ] CHANGELOG.md updated
- [ ] Git tag created
- [ ] NPM package published (when ready)

## ❓ **Questions?**

- **GitHub Discussions**: For general questions and ideas
- **GitHub Issues**: For specific bugs or feature requests
- **Code Reviews**: For implementation discussions

## 🙏 **Recognition**

Contributors will be recognized in:
- README.md contributors section
- Release notes for significant contributions
- Special mentions for major features

---

**Thank you for helping make Universal Context Engineering better!** 🎉

Every contribution, no matter how small, helps advance the state of AI coding assistance.