CONTRIBUTING.md

Contributing to Devora Prompt Assistant MCP

Thank you for your interest in contributing to the Devora Prompt Assistant MCP server! We welcome contributions from the community.

Getting Started

Prerequisites

• Node.js 20+
• pnpm (recommended) or npm
• Git

Development Setup

1. Fork the repository on GitHub

2. Clone your fork:

   git clone https://github.com/your-username/devora-prompt-assistant-mcp.git
   cd devora-prompt-assistant-mcp

3. Install dependencies:

   pnpm install

4. Copy environment template:

   cp env.example .env

5. Set up your environment:

   • Add at least one AI provider API key to .env
   • Configure other settings as needed

6. Run the development server:

   pnpm dev:stdio

Development Workflow

Code Style

We use ESLint and Prettier for code formatting:

# Check for linting issues
pnpm run lint

# Fix auto-fixable issues
pnpm run lint:fix

# Format code
pnpm run format

Testing

Run the test suite:

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test --coverage

Building

Build the project:

pnpm run build

Contributing Guidelines

Types of Contributions

We welcome several types of contributions:

• Bug fixes: Fix issues in existing functionality
• New features: Add new capabilities (please discuss first)
• Documentation: Improve README, code comments, or examples
• Tests: Add or improve test coverage
• Performance: Optimize existing code
• Security: Report or fix security issues

Before You Start

1. Check existing issues: Look for existing issues or discussions
2. Start a discussion: For significant changes, open a GitHub Discussion first
3. Create an issue: For bugs or feature requests, create an issue

Making Changes

1. Create a branch:

   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/issue-description

2. Make your changes:

   • Write clean, readable code
   • Add tests for new functionality
   • Update documentation as needed
   • Follow existing code patterns

3. Test your changes:

   pnpm test
   pnpm run lint
   pnpm run build

4. Commit your changes:

   git add .
   git commit -m "feat: add your feature description"

   Use conventional commit messages:

   • feat: for new features
   • fix: for bug fixes
   • docs: for documentation changes
   • test: for test changes
   • refactor: for code refactoring
   • perf: for performance improvements

5. Push your changes:

   git push origin feature/your-feature-name

6. Create a Pull Request:

   • Use the PR template
   • Provide a clear description
   • Link to related issues
   • Include screenshots for UI changes

Pull Request Guidelines

PR Title

Use a clear, descriptive title that explains what the PR does.

PR Description

Include:

• What: What changes were made
• Why: Why these changes were necessary
• How: How the changes work
• Testing: How the changes were tested
• Breaking Changes: Any breaking changes (if applicable)

Code Review Process

• All PRs require review from maintainers
• Address feedback promptly
• Keep PRs focused and reasonably sized
• Update documentation as needed

Code Standards

TypeScript

• Use strict TypeScript settings
• Prefer interfaces over types for object shapes
• Use proper error handling
• Add JSDoc comments for public APIs

Error Handling

• Use custom error classes from src/core/errors.ts
• Provide meaningful error messages
• Log errors appropriately
• Handle edge cases gracefully

Testing

• Write unit tests for new functionality
• Test error conditions
• Mock external dependencies
• Aim for good test coverage

Documentation

• Update README.md for user-facing changes
• Add JSDoc comments for new functions
• Update CHANGELOG.md for significant changes
• Include examples for new features

Project Structure

src/
├── auth/            # Authentication middleware
├── config/          # Environment and model configuration
├── core/            # Core utilities (logger, errors, pipeline, git, cache)
├── providers/       # AI provider adapters
├── server/          # MCP server and transports
└── index.ts         # CLI entry point

Adding New Providers

To add a new AI provider:

1. Create provider file in src/providers/
2. Implement the Provider interface from src/providers/types.ts
3. Add configuration to src/config/env.ts
4. Update model router in src/core/modelRouter.ts
5. Add tests in test/providers/
6. Update documentation in README.md

Adding New Tools

To add a new MCP tool:

1. Create tool file in src/server/tools/
2. Define input/output schemas using Zod
3. Implement tool handler function
4. Register tool in src/server/mcp.ts
5. Add tests in test/
6. Update documentation in README.md

Release Process

Versioning

We use Semantic Versioning:

• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes (backward compatible)

Release Steps

1. Update version in package.json
2. Update CHANGELOG.md
3. Create a release PR
4. Merge after review
5. Tag the release
6. GitHub Actions will publish to NPM

Community Guidelines

Code of Conduct

• Be respectful and inclusive
• Welcome newcomers
• Focus on constructive feedback
• Help others learn and grow

Getting Help

• GitHub Discussions: For questions and general discussion
• GitHub Issues: For bug reports and feature requests
• Email: For security issues (see SECURITY.md)

Recognition

Contributors will be recognized in:

• CONTRIBUTING.md acknowledgments
• GitHub contributors list
• Release notes (for significant contributions)

License

By contributing to this project, you agree that your contributions will be licensed under the same MIT License that covers the project.

Questions?

If you have questions about contributing, please:

1. Check existing GitHub Discussions
2. Open a new Discussion
3. Contact the maintainers

Thank you for contributing to Devora Prompt Assistant MCP! 🚀