Contributing Guide

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• CLAUDE.md
• RELEASE.md
• SECURITY.md
• scripts/update_readme_snippets.py
• mkdocs.yml

This guide provides instructions and best practices for contributing to the MCP Python SDK. Adhering to these guidelines ensures a smooth and effective development process for everyone involved. All contributions are expected to align with the project's standards for code quality, testing, and community interaction.

All participants in this project are required to abide by the Code of Conduct. By contributing, you agree that your contributions will be licensed under the project's MIT License.
Sources: CONTRIBUTING.md:1-3, CONTRIBUTING.md:46-51

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. All contributors and community members pledge to create a harassment-free, open, welcoming, and inclusive environment.

Our Standards

Behavior that contributes to a positive community includes:

• Demonstrating empathy and kindness.
• Being respectful of differing opinions and experiences.
• Giving and gracefully accepting constructive feedback.
• Accepting responsibility for mistakes and learning from them.

Examples of unacceptable behavior include harassment, trolling, personal attacks, and the use of sexualized language.
Sources: CODE_OF_CONDUCT.md:3-29

Enforcement

Instances of unacceptable behavior can be reported to the community leaders at <mcp-coc@anthropic.com>. All complaints will be reviewed and investigated. Community leaders have the right to remove, edit, or reject contributions that do not align with the Code of Conduct.
Sources: CODE_OF_CONDUCT.md:44-49, CODE_OF_CONDUCT.md:34-39

Development Setup

To begin contributing, you need to set up your local development environment.

1. Prerequisites: Ensure you have Python 3.10+ and uv installed.
   Sources: CONTRIBUTING.md:6-7
2. Fork & Clone: Fork the repository on GitHub and then clone your fork locally.

   git clone https://github.com/YOUR-USERNAME/python-sdk.git
   

   Sources: CONTRIBUTING.md:8-9
3. Install Dependencies: Use uv to install all required development and extra dependencies from the lock file.

   uv sync --frozen --all-extras --dev
   

   Sources: CONTRIBUTING.md:10-14
4. Set up Pre-commit Hooks: Install the pre-commit hooks to ensure code quality checks run automatically before each commit.

   uv tool install pre-commit --with pre-commit-uv --force-reinstall
   

   Sources: CONTRIBUTING.md:16-20

Development Workflow

Follow this workflow for all contributions, from bug fixes to new features.

The general development workflow is as follows:

1. Branching Strategy

• Bug Fixes: Use the latest release branch (e.g., v1.1.x).
• New Features: Use the main branch.
• If you are unsure, please ask in a GitHub issue before starting work.
  Sources: CONTRIBUTING.md:23-27

2. Code Quality and Checks

Before committing, ensure your changes meet the project's quality standards by running the following checks.

Tool	Command	Purpose
pytest	uv run pytest	Run the test suite.
pyright	uv run pyright	Perform static type checking.
ruff	uv run ruff check . --fix	Lint and automatically fix issues.
ruff	uv run ruff format .	Format the code.
pre-commit	pre-commit run --all-files	Run all configured pre-commit hooks.
Sources: CONTRIBUTING.md:30-39, CLAUDE.md:39-58

3. Updating README Snippets

If you modify any code within the examples/ directory, you must update the corresponding snippets in the README files. This is done using a dedicated script.

uv run scripts/update_readme_snippets.py

This script ensures that the documentation remains synchronized with the example code.
Sources: CONTRIBUTING.md:41-43

4. Commits and Pull Requests

• Commit Messages: For bug fixes or features from user reports, add a Reported-by:<name> trailer. For commits related to a GitHub issue, add a Github-Issue:#<number> trailer. Never include co-authored-by or mention the tool used for the commit.
  Sources: CLAUDE.md:19-25
• Pull Requests: Write a detailed PR message describing the problem and solution at a high level. Add jerome3o-anthropic and jspahrsummers as reviewers.
  Sources: CLAUDE.md:27-34

Coding Standards

General Rules

• Package Management: Only use uv for package management. uv pip install and @latest syntax are forbidden.
• Type Hints: All code must include type hints.
• Docstrings: Public APIs must have docstrings.
• Function Size: Functions should be small and focused.
• Line Length: Maximum line length is 120 characters.
  Sources: CLAUDE.md:6-14

Code Formatting

The project uses ruff for formatting and linting. Key rules include:

• Import sorting (I001).
• No unused imports.
• Strings should be wrapped using parentheses.
  Sources: CLAUDE.md:39-51

Exception Handling

• Always use logger.exception() instead of logger.error() when catching exceptions. Do not include the exception object in the log message.
• Catch specific exceptions where possible (e.g., OSError, json.JSONDecodeError).
• Only catch the base Exception in top-level handlers to prevent crashes.
  Sources: CLAUDE.md:82-91

Testing

• Framework: Tests are run using pytest with anyio for asynchronous testing.
• Execution: Run tests with uv run --frozen pytest.
• Requirements: New features must be accompanied by tests. Bug fixes require regression tests to prevent recurrence. Tests should cover edge cases and error conditions.
  Sources: CLAUDE.md:16-21, CONTRIBUTING.md:30-32

Release Process

The release process involves two main scenarios:

1. Bumping Dependencies:
   • Change the dependency version in pyproject.toml.
   • Update the lock file with uv lock --resolution lowest-direct.
2. Major or Minor Release:
   • Create a new release via the GitHub UI.
   • The tag and release title must be vX.Y.Z.
   • The package version is set automatically from the Git tag.
     Sources: RELEASE.md:3-9

Security Policy

Security is a top priority. If you discover a potential vulnerability, please report it responsibly.

• Reporting: All security issues should be reported through Anthropic's HackerOne submission form.
• Guidelines: The full vulnerability disclosure program guidelines are available on the HackerOne program page.
  Sources: SECURITY.md:5-14