Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
253 lines (185 loc) · 6.89 KB

CONTRIBUTING.md

File metadata and controls

253 lines (185 loc) · 6.89 KB

Contributing to Template MCP Server

Thank you for your interest in contributing! This guide explains the process for contributing to this project.

Table of Contents

Getting Started

  1. Fork the repository on GitHub.

  2. Clone your fork:

    git clone https://github.com/<your-username>/template-mcp-server.git
cd template-mcp-server

  3. Set up the development environment:

    make install

    This creates a virtual environment, installs all dependencies (including dev), and sets up pre-commit hooks.

  4. Verify everything works:

    make test
make pre-commit

Development Workflow

  1. Create a feature branch from main:

    git checkout -b feat/your-feature-name

  2. Make your changes following the Coding Standards.

  3. Run quality checks locally:

    make lint        # Check linting issues
make format      # Auto-format code
make test        # Run test suite
make coverage    # Run tests with coverage report
make pre-commit  # Run all pre-commit hooks

  4. Commit your changes using Conventional Commits.

  5. Push and open a Pull Request against main.

Commit Conventions

This project uses Conventional Commits for clear history and automated release notes.

Format

<type>(<optional scope>): <description>

[optional body]

[optional footer(s)]

Types

Type Description
feat New feature or capability
fix Bug fix
docs Documentation only changes
style Code style (formatting, semicolons, etc.)
refactor Code change that neither fixes a bug nor adds a feature
perf Performance improvement
test Adding or correcting tests
build Changes to build system or dependencies
ci Changes to CI configuration
chore Other changes that don't modify src or test files

Examples

feat(tools): add weather forecast tool
fix(oauth): handle expired token refresh correctly
docs: update deployment instructions for OpenShift
test(tools): add edge case tests for multiply tool
ci: add dependabot configuration

Pull Request Process

  1. Fill out the PR template completely. The template includes a checklist; all items must be addressed.

  2. Ensure all CI checks pass:

    • Pre-commit hooks (linting, formatting, type checking)
    • Test suite with coverage >= 80%
    • Security scanning (Bandit)

  3. Link related issues using keywords: Closes #123, Fixes #456.

  4. Keep PRs focused. One logical change per PR. If you find unrelated issues, open separate PRs.

  5. Respond to review feedback promptly. Push fixes as new commits (don't force-push during review).

  6. Squash and merge is the default merge strategy. Your PR title becomes the changelog entry, so make it clear and descriptive.

Issue Guidelines

Before Opening an Issue

  • Search existing issues to avoid duplicates.
  • Check the README and documentation for answers.

Bug Reports

Use the Bug Report template. Include:

  • Steps to reproduce
  • Expected vs. actual behavior
  • Environment details (OS, Python version, etc.)
  • Logs or error messages

Feature Requests

Use the Feature Request template. Include:

  • Problem statement (what you're trying to solve)
  • Proposed solution
  • Alternatives considered

Labels

Issues are automatically labeled by type. You can also add:

  • good first issue - suitable for newcomers
  • help wanted - looking for contributors
  • priority/high - needs attention soon

Coding Standards

Python Style

  • PEP 8 compliance (enforced by Ruff)
  • Line length: 88 characters (Ruff default)
  • Imports: sorted by isort (via Ruff)
  • Quotes: double quotes

Type Annotations

Required for all public functions and methods:

async def my_tool(param: str, count: int = 1) -> Dict[str, Any]:
    ...

Documentation

Google-style docstrings for all public APIs:

async def my_tool(param: str) -> Dict[str, Any]:
    """Short description of the tool.

    Args:
        param: Description of the parameter.

    Returns:
        Dict[str, Any]: Description of the return value.

    Raises:
        ValueError: When param is invalid.
    """

Error Handling

  • Use structured logging (structlog) for all log messages.
  • Return error dictionaries with status, error, and message keys.
  • Never expose internal errors to clients.

Adding New MCP Tools

  1. Create the tool module in template_mcp_server/src/tools/:

    # template_mcp_server/src/tools/your_tool.py
from typing import Any, Dict
from template_mcp_server.utils.pylogger import get_python_logger

logger = get_python_logger()

async def your_tool_function(param: str) -> Dict[str, Any]:
    """Your tool description."""
    try:
        # Implementation
        return {"status": "success", "result": "value"}
    except Exception as e:
        logger.error(f"Error in your tool: {e}")
        return {"status": "error", "error": str(e)}

  2. Register in MCP server (template_mcp_server/src/mcp.py):

    from template_mcp_server.src.tools.your_tool import your_tool_function

def _register_mcp_tools(self) -> None:
    # ... existing registrations ...
    self.mcp.tool()(your_tool_function)

  3. Add tests in tests/:

    # tests/test_your_tool.py
import pytest
from template_mcp_server.src.tools.your_tool import your_tool_function

@pytest.mark.asyncio
async def test_your_tool_success():
    result = await your_tool_function("test")
    assert result["status"] == "success"

  4. Update documentation in README.md and template_mcp_server/src/tools/README.md.

Testing Requirements

  • All new code must have corresponding tests.
  • Minimum 80% code coverage is required.
  • Tests must pass on Python 3.12 and 3.13.
  • Use pytest with pytest-asyncio for async tests.
  • Mock external dependencies; do not make real network calls in tests.

Running Tests

make test              # Run all tests
make coverage          # Run with coverage report
pytest tests/ -v       # Verbose output
pytest tests/ -k name  # Run specific test by name

Getting Help

  • Issues: Open an issue for bugs or feature requests.
  • Discussions: Use GitHub Discussions for questions and ideas.
  • Documentation: Check the README and in-code documentation.

Thank you for contributing!