PaperlessMCP/CONTRIBUTING.md

Contributing to PaperlessMCP

Thank you for your interest in contributing! This document outlines our development workflow and guidelines.

Development Workflow

We use trunk-based development:

1. Create a feature branch from main
2. Make your changes with conventional commits
3. Open a pull request to main
4. CI runs build and tests
5. Merge to main triggers automatic release

main ←── feature/add-search-filters
     ←── fix/upload-timeout
     ←── feat/bulk-export

Conventional Commits

We use Conventional Commits for automatic versioning. Your commit messages determine the version bump:

Commit Format

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

[optional body]

[optional footer]

Types and Version Bumps

Type	Description	Version Bump
fix:	Bug fixes	Patch (0.0.X)
feat:	New features	Minor (0.X.0)
feat!:	Breaking changes	Major (X.0.0)
docs:	Documentation only	Patch
style:	Code style (formatting)	Patch
refactor:	Code refactoring	Patch
test:	Adding/updating tests	Patch
chore:	Maintenance tasks	Patch

Examples

# Bug fix → v1.0.1
git commit -m "fix: handle null response from API"

# New feature → v1.1.0
git commit -m "feat: add document export functionality"

# Breaking change → v2.0.0
git commit -m "feat!: change API response format"

# Or with BREAKING CHANGE footer
git commit -m "feat: redesign search API

BREAKING CHANGE: search now returns paginated results by default"

Scopes (Optional)

Use scopes to indicate the affected area:

git commit -m "fix(upload): increase timeout for large files"
git commit -m "feat(tags): add bulk delete operation"
git commit -m "docs(readme): update installation instructions"

Pull Request Process

1. Branch naming: Use descriptive names

   • feat/description for features
   • fix/description for bug fixes
   • docs/description for documentation

2. PR title: Use conventional commit format

   • The PR title becomes the merge commit message
   • Example: feat: add document preview endpoint

3. Description: Include

   • What changes were made
   • Why the changes were needed
   • How to test the changes

4. CI checks: Ensure all checks pass

   • Build succeeds
   • Tests pass
   • Docker builds

Local Development

Prerequisites

• .NET 10 SDK
• Docker (optional, for container testing)

Setup

# Clone the repo
git clone https://github.com/barryw/PaperlessMCP.git
cd PaperlessMCP

# Restore and build
dotnet restore
dotnet build

# Run tests
dotnet test

Running Locally

# Set environment variables
export PAPERLESS_BASE_URL=https://your-instance.com
export PAPERLESS_API_TOKEN=your-token

# Run in stdio mode (for testing with Claude)
dotnet run --project PaperlessMCP/PaperlessMCP -- --stdio

# Run in HTTP mode
dotnet run --project PaperlessMCP/PaperlessMCP

Running Tests

# All tests
dotnet test

# With verbose output
dotnet test --logger "console;verbosity=detailed"

# Specific test class
dotnet test --filter "FullyQualifiedName~DocumentToolsTests"

Code Style

• Follow existing code patterns
• Use meaningful variable and method names
• Add XML documentation for public APIs
• Keep methods focused and small

Questions?

Open an issue for questions or discussions about contributing.