Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
170 lines (119 loc) · 4.84 KB

CONTRIBUTING.md

File metadata and controls

170 lines (119 loc) · 4.84 KB

Contributing to MCPcat 🎉

Thank you for your interest in contributing to MCPcat! We're excited to have you join our community of developers building analytics tools for MCP servers.

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR-USERNAME/mcpcat-python-sdk.git
cd mcpcat-python-sdk
  3. Install dependencies using uv: 
    uv sync
  4. Create a branch for your feature or fix: 
    git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

Development Process

Making Changes

  1. Write your code following our Python standards
  2. Add tests for new features (required for feature additions)
  3. Run the test suite to ensure everything passes: 
    uv run pytest
  4. Check your code meets our standards: 
    uv run ruff check .    # Run linting checks
uv run ruff format .   # Format code

Commit Conventions

We follow Conventional Commits. Your commit messages should be structured as:

<type>: <description>

[optional body]

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • test: Adding or updating tests
  • refactor: Code change that neither fixes a bug nor adds a feature
  • chore: Changes to build process or auxiliary tools

Examples:

git commit -m "feat: add telemetry exporters for observability"
git commit -m "fix: handle edge case in session tracking"
git commit -m "docs: update API documentation"

Pull Request Process

  1. Push your changes to your fork:

    git push origin feature/your-feature-name

  2. Create a Pull Request from your fork to our main branch

  3. Fill out the PR description with:

    • What changes you've made
    • Why these changes are needed
    • Any relevant context or screenshots

  4. Wait for review - The MCPcat team will review your PR within 2 business days

  5. Address feedback if any changes are requested

  6. Celebrate 🎉 once your PR is merged!

No Issue Required

You don't need to open an issue before submitting a PR. Feel free to submit pull requests directly with your improvements!

Good First Issues

Looking for a place to start? Check out issues labeled good first issue - these are great for newcomers to the codebase.

Testing

  • New features should include tests to ensure reliability
  • Run tests locally with uv run pytest
  • We use pytest for our test suite
  • Test files should be placed in the tests/ directory with test_*.py naming convention

Code Quality

Before submitting your PR, ensure your code passes all checks:

# Run tests
uv run pytest

# Check code style and linting
uv run ruff check .

# Format code
uv run ruff format .

# Type checking (if applicable)
uv run mypy src/mcpcat --ignore-missing-imports

Our CI will run these same checks on your PR.

Dependencies

While we don't restrict adding new dependencies, they are generally discouraged unless absolutely necessary. If you need to add a dependency:

  1. Consider if the functionality can be achieved with existing dependencies
  2. Check if the dependency is well-maintained and lightweight
  3. Ensure it's compatible with our MIT license
  4. Add it using uv: uv add <package-name>

Project Structure

mcpcat-python-sdk/
├── src/           # Source code
│   └── mcpcat/    # Main package
│       ├── modules/      # Core modules
│       ├── thirdparty/   # Vendored dependencies
│       ├── types.py      # Type definitions
│       └── utils.py      # Utility functions
├── tests/         # Test files
├── examples/      # Example usage
├── docs/          # Documentation
└── dist/          # Built distributions (generated)

Community

Versioning

The MCPcat team handles versioning and releases. Your contributions will be included in the next appropriate release based on semantic versioning principles.

Recognition

All contributors are recognized in our repository. Your contributions help make MCPcat better for everyone building MCP servers!

Questions?

If you have questions about contributing, feel free to:

Thank you for contributing to MCPcat! 🐱