Contributing to MCP-Use

Thank you for your interest in contributing to MCP-Use! This document provides guidelines and instructions for contributing to this project.

Getting Started

Development Environment

MCP-Use requires:

Python 3.11 or later

Installation from Source

Fork the repository on GitHub.

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/mcp-use.git
cd mcp-use

Install the package in development mode:
```
pip install -e ".[dev,search,e2b]"
```

Set up pre-commit hooks:

pip install pre-commit
pre-commit install

Development Workflow

Branching Strategy

main branch contains the latest stable code
Create feature branches from main named according to the feature you're implementing: feature/your-feature-name
For bug fixes, use: fix/bug-description

Commit Messages

For now no commit style is enforced, try to keep your commit messages informational.

Code Style

We use Ruff for code formatting and linting. The configuration is in ruff.toml.

Key style guidelines:

Line length: 100 characters
Use double quotes for strings
Follow PEP 8 naming conventions
Add type hints to function signatures

Pre-commit Hooks

We use pre-commit hooks to ensure code quality before committing. The configuration is in .pre-commit-config.yaml.

The hooks will:

Format code using Ruff
Run linting checks
Check for trailing whitespace and fix it
Ensure files end with a newline
Validate YAML files
Check for large files
Remove debug statements

Testing

Running Tests

Run the test suite with pytest:

pytest

To run specific test categories:

pytest tests/

Adding Tests

Add unit tests for new functionality in tests/unit/
For slow or network-dependent tests, mark them with @pytest.mark.slow or @pytest.mark.integration
Aim for high test coverage of new code

Pull Requests

Creating a Pull Request

Ensure your code passes all tests and pre-commit hooks
Push your changes to your fork
Submit a pull request to the main repository
Follow the pull request template

Documentation

Update docstrings for new or modified functions, classes, and methods

Use Google-style docstrings:

def function_name(param1: type, param2: type) -> return_type:
    """Short description.

    Longer description if needed.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of return value

    Raises:
        ExceptionType: When and why this exception is raised
    """

Update README.md for user-facing changes

Getting Help

If you need help with your contribution:

Open an issue for discussion
Reach out to the maintainers
Check existing code for examples

Thank you for contributing to MCP-Use!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!