Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
376 lines (281 loc) · 9.87 KB

CONTRIBUTING.md

File metadata and controls

376 lines (281 loc) · 9.87 KB

Contributing to MarkItDown MCP Server

Thank you for your interest in contributing to the MarkItDown MCP Server! 🎉

📋 Table of Contents

📜 Code of Conduct

This project adheres to a code of conduct that we expect all contributors to follow. Please be respectful and constructive in all interactions.

🚀 Getting Started

Prerequisites

  • Python 3.10 or higher
  • Git
  • Basic understanding of the Model Context Protocol (MCP)

Fork the Repository

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/markitdown-mcp.git
cd markitdown-mcp

💻 Development Setup

  1. Create a virtual environment:

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  2. Install in development mode:

    pip install -e .

  3. Install development dependencies:

    pip install -e ".[dev]"

  4. Verify installation:

    markitdown-mcp --help

🔧 Making Changes

Branch Naming Convention

  • feat/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation updates
  • test/ - Test improvements
  • refactor/ - Code refactoring

Example: feat/add-new-file-format or fix/mcp-protocol-error

Development Workflow

  1. Create a feature branch:

    git checkout -b feat/your-feature-name

  2. Make your changes:

    • Follow existing code style
    • Add tests for new functionality
    • Update documentation as needed

  3. Test your changes:

    # Test MCP server functionality
python -c "
import json
import subprocess
test_request = {'jsonrpc': '2.0', 'id': 1, 'method': 'tools/list', 'params': {}}
proc = subprocess.run(['markitdown-mcp'], input=json.dumps(test_request), 
                     capture_output=True, text=True)
print('✅ Server working' if proc.stdout else '❌ Server error')
"

  4. Format code (if you have dev dependencies):

    black markitdown_mcp/
isort markitdown_mcp/

Code Style Guidelines

  • Follow PEP 8 Python style guide
  • Use meaningful variable and function names
  • Add docstrings to all functions and classes
  • Keep functions focused and small
  • Use type hints where appropriate

Adding New File Format Support

If you want to add support for a new file format:

  1. Check if MarkItDown library already supports it
  2. Update the supported_extensions set in markitdown_mcp/server.py
  3. Add the format to the README documentation
  4. Test with sample files
  5. Update the format count in documentation if needed

📤 Submitting Pull Requests

Before Submitting

  • Code follows the project's style guidelines
  • Self-review of code completed
  • Tests pass locally
  • Documentation updated if needed
  • No merge conflicts with main branch

PR Template

When creating a PR, please include:

  1. Description: Clear description of what the PR does
  2. Type: Feature, bug fix, documentation, etc.
  3. Testing: How you tested the changes
  4. Screenshots: If applicable (especially for documentation changes)
  5. Breaking Changes: Any breaking changes and migration steps

PR Review Process

  1. Automated checks will run
  2. Maintainer will review the code
  3. Address any feedback
  4. Once approved, PR will be merged

🚀 Release Process

Conventional Commits

All commits MUST follow conventional commit format for automated version management:

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

[optional body]

[optional footer]

Commit Types

Type Description Version Impact
feat New feature Minor (0.1.0)
fix Bug fix Patch (0.0.1)
docs Documentation only None
style Code formatting None
refactor Code restructuring None
perf Performance improvement Patch (0.0.1)
test Testing changes None
chore Build/dependencies None
ci CI/CD changes None
BREAKING CHANGE Breaking API change Major (1.0.0)

Examples

# New feature (minor version bump)
feat(mcp): add support for PowerBI files

# Bug fix (patch version bump)
fix(security): resolve path traversal vulnerability

# Breaking change (major version bump)
feat(api): redesign tool interface

BREAKING CHANGE: tool parameters now require explicit types

Automated Releases

Releases are fully automated based on conventional commits:

  1. Version Detection: Commits since last release determine version bump
  2. Quality Gates: All CI checks must pass before release
  3. Changelog: Automatically generated from commit messages
  4. Publishing: Package published to PyPI automatically
  5. GitHub Release: Created with auto-generated release notes

Contributing to Releases

For Feature Development

# 1. Create feature branch
git checkout -b feat/new-file-format

# 2. Make changes with proper commits
git commit -m "feat(converter): add support for Pages files"
git commit -m "test(converter): add Pages file test cases"
git commit -m "docs(readme): update supported formats list"

# 3. Create PR with conventional title
# PR Title: "feat(converter): add support for Pages files"

For Bug Fixes

# 1. Create fix branch
git checkout -b fix/memory-leak

# 2. Make fix with proper commit
git commit -m "fix(memory): resolve memory leak in large file processing"

# 3. Create PR
# PR Title: "fix(memory): resolve memory leak in large file processing"

For Breaking Changes

Breaking changes require special attention:

# Commit message must include BREAKING CHANGE footer
git commit -m "feat(api): redesign tool response format

BREAKING CHANGE: tool responses now return structured data with metadata instead of plain text"

Release Timeline

  • Patch Releases: Automated when bug fixes are merged
  • Minor Releases: Automated when new features are merged
  • Major Releases: Automated when breaking changes are merged
  • Security Releases: Emergency releases within 24 hours

Release Quality Requirements

Before any release, automated systems verify:

  • All tests pass on supported Python versions (3.10, 3.11, 3.12)
  • Code formatting and linting pass (ruff)
  • Type checking passes (mypy)
  • Test coverage maintains minimum threshold (80%)
  • Security scans pass (no high/critical vulnerabilities)
  • MCP protocol compliance verified
  • Documentation builds successfully

Manual Release Override

For emergency situations, maintainers can create manual releases:

# 1. Ensure quality gates pass
ruff format --check && ruff check && mypy markitdown_mcp/

# 2. Update version in pyproject.toml
# 3. Update CHANGELOG.md
# 4. Create and push tag
git tag v1.2.3
git push origin v1.2.3

Release Communication

Contributors will be notified of releases through:

  • GitHub Releases: Automated release notes
  • PyPI: Package updates
  • Changelog: Updated CHANGELOG.md file
  • Issues: Automatic closure of fixed issues

For detailed release procedures, see the RELEASE.md file in the repository root.

🐛 Reporting Issues

Bug Reports

When reporting bugs, please include:

  • Environment: OS, Python version, package version
  • Steps to reproduce: Detailed steps
  • Expected behavior: What should happen
  • Actual behavior: What actually happens
  • Error messages: Full error output
  • Sample files: If related to specific file types (redact sensitive data)

Use this template:

**Environment:**
- OS: [e.g., macOS 13.0, Windows 11, Ubuntu 20.04]
- Python version: [e.g., 3.9.7]
- Package version: [e.g., 1.0.0]
- MCP Client: [e.g., Claude Desktop 0.4.1]

**Bug Description:**
A clear description of the bug.

**Steps to Reproduce:**
1. Install package...
2. Run command...
3. Error occurs...

**Expected Behavior:**
What you expected to happen.

**Actual Behavior:**
What actually happened.

**Error Output:**

Paste error messages here


**Sample Files:**
If applicable, attach sample files that cause the issue.

💡 Feature Requests

We welcome feature requests! Please:

  1. Check existing issues to avoid duplicates
  2. Clearly describe the use case
  3. Explain why this feature would benefit MCP users
  4. Consider implementation complexity

Feature Request Template:

**Is your feature request related to a problem?**
A clear description of the problem.

**Describe the solution you'd like**
A clear description of what you want to happen.

**Describe alternatives you've considered**
Other solutions you've thought about.

**Use Case**
How would this feature benefit MCP users?

**Additional context**
Any other context about the feature request.

🏷️ Labels

We use these labels to organize issues and PRs:

  • bug - Something isn't working
  • enhancement - New feature or request
  • documentation - Documentation improvements
  • good first issue - Good for newcomers
  • help wanted - Extra attention needed
  • mcp-protocol - Related to MCP protocol
  • file-format - New file format support
  • performance - Performance improvements

🎖️ Recognition

Contributors will be recognized in:

  • GitHub contributors list
  • Release notes for significant contributions
  • Special thanks in documentation

📞 Getting Help

  • GitHub Issues: For bugs and feature requests
  • GitHub Discussions: For questions and general discussion
  • Code Review: We're happy to help review code before you submit

📄 License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to MarkItDown MCP Server! 🚀