Contributing Guidelines

How to contribute to guMCP development

Thank you for your interest in contributing to guMCP! This guide will help you get started with development and understand our contribution process.

Development Environment Setup

Prerequisites

• Python 3.11
• Git

Setup Steps

1. Clone the repository

   git clone https://github.com/dvlpjrs/guMCP.git
   cd guMCP
   
2. Create a virtual environment

   python -m venv venv
   
3. Activate the virtual environment

   On macOS/Linux:

   source venv/bin/activate
   

   On Windows:

   venv\Scripts\activate
   
4. Install dependencies

   # Install main dependencies
   pip install -r requirements.txt
   
   # Install development dependencies
   pip install -r requirements-dev.txt
   
5. Set up environment variables

   Copy the example .env file and update it with your configuration:

   cp .env.example .env
   

Project Structure

Understanding the project layout:

• src/ - Main source code
  • auth/ - Authentication components
  • servers/ - Server implementations
  • utils/ - Utility functions and helpers
• tests/ - Test suite
  • servers/ - Server-specific tests
  • clients/ - Test client implementations
• scripts/ - Utility scripts for development

Pull Request Process

1. Fork and create branch

   Fork the repository and create your branch from main:

   git checkout -b feature/your-feature-name
   
2. Make your changes

   • Follow the project’s code style (see Code Style)
   • Add tests for any new functionality
   • Update documentation as needed
3. Run quality checks

   Ensure all tests pass and code meets quality standards:

   # Format code
   python scripts/format.py
   
   # Run linting
   python scripts/lint.py
   
   # Run tests
   python tests/servers/test_runner.py --server=your-server
   
4. Submit pull request

   Submit a pull request with:

   • Clear description of changes
   • Why the changes are needed
   • Any related issue numbers

Requested Contributions

We’re particularly interested in contributions for:

• Add Support for New MCP Spec
  • Streamable HTTP Transport
  • Client/Server Authentication Mechanism
• Add Support for FastMCP
• New Server Implementations - See our server creation guide

Writing Tests

When adding new features:

1. Write tests for new functionality - All servers should have a corresponding tests.py file
2. Ensure all tests pass - Run the full test suite before submitting
3. Use pytest fixtures - Leverage the existing test infrastructure
4. Include integration tests - Have some tests that do NOT use mocks and require actual authentication
5. Use descriptive test names - Follow the pattern test_<functionality>_<expected_behavior>

See our Testing Guide for detailed information.

Versioning

We follow Semantic Versioning for this project:

• MAJOR: Incompatible API changes
• MINOR: Backwards-compatible functionality additions
• PATCH: Backwards-compatible bug fixes

Getting Help

If you have questions or need help:

• Open an issue in the GitHub repository
• Review existing documentation and examples
• Contact the project maintainers

License

By contributing to this project, you agree that your contributions will be licensed under the project’s license.

Thank you for contributing to guMCP!