Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pymupdf/pymupdf4llm-mcp/llms.txt

Use this file to discover all available pages before exploring further.

Contributions to pymupdf4llm-mcp are welcome and greatly appreciated. This page walks through setting up a local development environment, making changes, and submitting a pull request so your work can be included in the project.

​
Prerequisites

Before you begin, make sure you have the following installed:
  • Python 3.10 or later — the project targets Python 3.10–3.13
  • uv — fast Python package and project manager (installation guide)
  • Git

​
Setup

1

Fork and clone the repository

Fork the repository on GitHub, then clone your fork locally:
git clone git@github.com:YOUR_NAME/pymupdf4llm-mcp.git
cd pymupdf4llm-mcp
2

Install the virtual environment and pre-commit hooks

Run the install target to create the virtual environment with uv and register the pre-commit hooks:
make install
# equivalent to: uv sync && uv run pre-commit install
The pre-commit hooks run ruff and other formatters automatically on every git commit.
3

Create a feature branch

Always work on a dedicated branch rather than directly on main:
git checkout -b my-feature-or-fix
4

Make your changes

Edit the source code and add corresponding tests in the tests/ directory. Every new behaviour or bug fix should be covered by at least one test case.
5

Run the quality check suite

Before committing, verify that linting, formatting, and dependency checks all pass:
make check
This runs the following in order:
  1. Lock file consistency — uv lock --locked confirms uv.lock matches pyproject.toml
  2. Pre-commit linters — runs ruff (lint + format) and other hooks across all files
  3. Dependency audit — deptry . checks for obsolete or missing dependencies
6

Run the test suite

Confirm all tests pass and coverage is collected:
make test
7

Commit, push, and open a pull request

When everything is green, push your branch to GitHub and open a pull request:
git add .
git commit -m "Your detailed description of your changes."
git push origin my-feature-or-fix
Then open a pull request from your fork on the GitHub website.

​
Available Make Targets

The Makefile provides the following targets:
TargetDescription
make installCreate the virtual environment and install pre-commit hooks
make checkRun linters, format checks, and dependency audit
make testRun tests with pytest and generate a coverage report
make snapshotUpdate inline snapshots after intentional output changes
make buildBuild the wheel distribution
make publishPublish the built distribution to PyPI
make build-and-publishBuild the wheel and publish it to PyPI in one step
The project uses inline-snapshot for snapshot testing. If you make an intentional change to the Markdown output produced by the server, run make snapshot to update the stored snapshots before committing. See Testing for more details.

​
Code Quality

The project enforces consistent style through ruff:
  • Linter: ruff with a broad rule set (pyflakes, pyupgrade, bugbear, bandit, isort, and more)
  • Formatter: ruff format with preview mode enabled
  • Line length: 120 characters
  • Target version: Python 3.9+
Pre-commit hooks run ruff lint and ruff format automatically on every git commit, so most style issues are caught before they reach CI.

​
Pull Request Guidelines

Please check the following before opening a pull request:
  • Include tests for any new functionality or bug fix
  • Update documentation if the change affects behaviour visible to users
  • Pass make check — all linters and the dependency audit must succeed
  • Pass make test — all tests must pass with no unexpected snapshot differences

Build docs developers (and LLMs) love

Get started for freeTalk to us