mcp-codex-keeper
by aindreyway
# Contributing to MCP Codex Keeper
👍 Thank you for considering contributing to MCP Codex Keeper! This document explains how to contribute effectively.
## Project Documentation Structure
We maintain three main documentation files:
1. **README.md** - User-focused documentation
- Installation and setup
- Basic usage examples
- Available tools and features
- Configuration options
2. **CONTRIBUTING.md** (this file) - Developer guide
- How to contribute
- Development setup
- Coding standards
- Pull request process
3. **PROJECT_SUMMARY.md** - Technical documentation
- Detailed architecture
- Implementation details
- Design decisions
- Internal workflows
## Development Setup
1. Clone and prepare:
```bash
git clone https://github.com/aindreyway/mcp-codex-keeper.git
cd mcp-codex-keeper
npm install
```
2. Set up environment:
```bash
cp .env.example .env
```
Configure:
- `MCP_ENV=local` for local development
- `STORAGE_PATH=data` for local storage
3. Development Scripts:
```bash
# Run in local mode
npm run local
# Watch mode for development
npm run dev
```
## Development Guidelines
### Code Style
1. TypeScript:
- Use strict mode
- Properly type everything
- Use interfaces for complex types
- Document public APIs with JSDoc
2. File Organization:
- Keep files focused and small
- Group related functionality
- Use clear, descriptive names
- Follow existing patterns
3. Error Handling:
- Use custom error classes
- Provide meaningful messages
- Log appropriately
- Handle edge cases
### Testing
1. Local Testing:
```bash
# Run in local mode
npm run local
# Test your changes
```
2. Production Testing:
```bash
# Install globally
npm i -g @aindreyway/mcp-codex-keeper
# Test as end user
```
## Making Changes
1. Create a feature branch:
```bash
git checkout -b feature/your-feature-name
```
2. Make your changes:
- Follow code style guidelines
- Add/update tests if needed
- Update documentation
3. Commit your changes:
```bash
git add .
git commit -m "type: description of changes"
```
Use conventional commit messages:
- feat: New feature
- fix: Bug fix
- docs: Documentation
- style: Formatting
- refactor: Code restructuring
- test: Tests
- chore: Maintenance
4. Push your branch:
```bash
git push origin feature/your-feature-name
```
## Pull Request Process
1. Update Documentation:
- Update README.md if adding features
- Update PROJECT_SUMMARY.md for technical changes
- Add comments for complex code
2. Submit PR:
- Clear title and description
- Reference any related issues
- Explain your changes
- List any breaking changes
3. Review Process:
- Address review comments
- Keep discussions focused
- Be patient and respectful
4. After Merge:
- Delete your branch
- Verify changes in production
- Update related issues
## Version Management
We use semantic versioning:
1. Version Numbers:
- MAJOR (x.0.0): Breaking changes
- MINOR (0.x.0): New features
- PATCH (0.0.x): Bug fixes
2. Version Update:
```bash
npm run deploy
```
This handles:
- Version bumping
- Building
- Publishing
- Git tags
## Best Practices
1. Documentation:
- Keep it current
- Be clear and concise
- Include examples
- Explain why, not just what
2. Code:
- Write self-documenting code
- Keep functions small
- Use meaningful names
- Follow SOLID principles
3. Git:
- Small, focused commits
- Clear commit messages
- Keep main branch stable
- Rebase before merging
## Getting Help
- Check existing issues
- Ask in discussions
- Read PROJECT_SUMMARY.md
- Contact maintainers
Remember: Quality over speed. Take time to do things right!