Contributing to MCP-Crawl4AI

Thank you for your interest in contributing to MCP-Crawl4AI! This guide will help you get started with the development process and outline our contribution guidelines.

We welcome contributions of all sizes, from fixing typos in documentation to implementing new features.

Getting Started

Prerequisites

Python 3.13+
uv (recommended package manager)
Node.js 18+ (for documentation website)
Git

Setting Up the Development Environment

# Clone the repository
git clone https://github.com/wyattowalsh/mcp-crawl4ai.git
cd mcp-crawl4ai
 
# Install dependencies (including dev group)
uv sync --group dev
 
# Install browser dependencies for mcp-crawl4ai
mcp-crawl4ai --setup

Development Workflow

Branching Strategy

We follow a simplified GitHub flow:

Fork the repository (if you're an external contributor)
Create a feature branch from main
Make your changes
Submit a pull request to main

Branch naming convention: <type>/<short-description>

Types: feature, bugfix, docs, refactor, test, etc.

Example: feature/add-llm-extraction

Code Style

We use the following tools to maintain code quality:

Ruff: For linting and formatting (configured in pyproject.toml)
ty: For static type checking

Run the linting and formatting tools:

# Lint
uv run ruff check .
 
# Format
uv run ruff format .
 
# Type check
uv run ty check mcp_crawl4ai/

Testing

We use pytest for testing with asyncio support.

# Run all tests
uv run pytest
 
# Run with coverage
uv run pytest --cov=mcp_crawl4ai
 
# Run specific tests
uv run pytest tests/test_server.py

Pull Request Process

Ensure your code passes all tests and linting
Update documentation if necessary
Include a clear description of the changes in your PR
Link to any related issues using keywords (e.g., "Fixes #123")
Wait for review from maintainers

Please do not include multiple unrelated changes in a single PR. Create separate PRs for unrelated features or fixes.

Documentation

If you're adding a new feature, please update the relevant documentation:

Update or add appropriate MDX files in docs/content/docs/
Update API reference if necessary in docs/content/docs/api-reference.mdx
Consider adding examples if applicable

To preview documentation changes locally:

cd docs
pnpm install
pnpm dev

Then visit http://localhost:3000 to preview the changes.

Community Guidelines

Be respectful and inclusive
Focus on constructive feedback
Help others learn and grow
Give credit where it's due

Thank you for contributing to MCP-Crawl4AI! Your help makes this project better for everyone.

Contributing Guide