Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
192 lines (136 loc) · 3.82 KB

CONTRIBUTING.md

File metadata and controls

192 lines (136 loc) · 3.82 KB

Contributing to mcpstat

Thank you for your interest in contributing to mcpstat! This document provides guidelines and instructions for contributing.

Table of Contents

Code of Conduct

Please read and follow our Code of Conduct.

Getting Started

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/mcpstat.git
cd mcpstat
  3. Create a virtual environment and install dependencies: 
    python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows
pip install -e ".[dev]"

Development Setup

Running the Tests

# Run all tests with coverage (configured in pyproject.toml)
pytest

# Run specific test file
pytest tests/test_mcpstat.py

# Run without coverage
pytest tests/ --no-cov

Type Checking

mypy mcpstat/

Linting

# Ruff (primary linter)
ruff check .

# Ruff with auto-fix
ruff check . --fix

Coding Standards

Style Guide

  • Follow PEP 8 for Python code
  • Use snake_case for functions and variables
  • Use CamelCase for class names
  • Maximum line length: 127 characters

Code Quality Tools

Pre-commit Hooks (Recommended)

Install pre-commit hooks to automatically check code quality before commits:

# Install pre-commit
pip install pre-commit

# Install the git hooks
pre-commit install

# Run all hooks manually (optional)
pre-commit run --all-files

The pre-commit configuration includes:

  • Ruff: Fast Python linting and formatting
  • Mypy: Static type checking
  • Bandit: Security vulnerability scanning
  • Standard hooks: Trailing whitespace, YAML/TOML/JSON validation

Manual Quality Checks

# Full check suite (before PR)
ruff check .
mypy mcpstat/
pytest tests/ -v

# Format code
ruff format .

Documentation

  • Add docstrings to all public methods and classes
  • Follow Google-style docstrings
  • Update README.md if adding user-facing features

Type Hints

  • Use type hints for function parameters and return values
  • Use TYPE_CHECKING for import-only type hints
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from mcp.types import Tool

Submitting Changes

Commit Messages

Follow conventional commit format:

type(scope): short description

Longer description if needed.

Fixes #123

Types: feat, fix, docs, style, refactor, test, chore

Pull Request Process

  1. Create a feature branch: 
    git checkout -b feature/your-feature-name
  2. Make your changes with clear, descriptive commits
  3. Ensure all checks pass: 
    pytest tests/
mypy mcpstat/
ruff check .
  4. Push to your fork and create a pull request

Pull Request Checklist

  • Tests pass locally
  • Code follows style guidelines (ruff, mypy clean)
  • Documentation updated (if applicable)
  • CHANGELOG.md updated under [Unreleased]
  • Commits are clean and well-described

Reporting Issues

Bug Reports

Include:

  • mcpstat version (pip show mcpstat)
  • Python version (python --version)
  • Operating system
  • Minimal reproducible example
  • Expected vs actual behavior
  • Error messages or logs

Feature Requests

Include:

  • Clear description of the feature
  • Use case / motivation
  • Possible implementation approach (optional)

Questions?

Thank you for contributing to mcpstat! 🎉