Compatag

Compatag preflights Python package compatibility before deployment. It checks published PyPI package artifacts against explicit Python versions and platforms, identifying compatible wheels and cases that may require a source build.

Compatag is available through a command-line interface and a local MCP server. Its results describe published metadata and artifacts; they do not guarantee that an application will run successfully.

Contents

• Demo
• Features
• Installation
• How to Use
• Current Scope and Limitations
• To-do
• License

Demo

The video shows Compatag's MCP server in action with Codex. Playback is deliberately slowed during tool calls and while Codex presents conclusions based on the results, making these steps easier to follow.

https://github.com/user-attachments/assets/709741e3-4c93-4ec7-8706-19bcb4995c2e

Features

• Package checks: Checks a single Python requirement against an explicit CPython version and platform.
• Dependency audits: Audits direct dependencies in requirements-style files and PEP 621 pyproject.toml files, including selected optional dependency groups.
• Wheel and source-build detection: Detects compatible wheels and source-build requirements, taking Requires-Python and environment markers into account.
• Target comparisons: Compares two deployment targets, reporting compatibility, selected-version, artifact, and dependency-applicability changes.
• CLI and MCP support: Provides CLI commands with JSON output and three tools through a local MCP stdio server.
• Concurrent analysis: Analyzes PyPI packages concurrently, with configurable concurrency and resource limits.

Installation

Compatag requires Python 3.11 or newer. CI covers Python 3.11-3.14 on Windows and Ubuntu.

From PyPI

pip install compatag

From source

git clone https://github.com/SharnavM/compatag.git
cd compatag
python -m pip install .

For development, an editable installation includes the test and code-checking tools:

python -m pip install -e ".[dev]"

How to Use

CLI

Each command takes an explicit deployment target, independent of the machine running Compatag.

A single requirement check:

compatag check "numpy>=2,<3" --python 3.11 --platform manylinux_2_17_aarch64

A direct-dependency audit:

compatag audit requirements.txt --python 3.11 --platform win_amd64

For a project with a dev optional dependency group:

compatag audit pyproject.toml --extra dev --python 3.11 --platform win_amd64

A comparison between Windows x64 and ARM64 Linux:

compatag compare requirements.txt --from-python 3.11 --from-platform win_amd64 --to-python 3.11 --to-platform manylinux_2_17_aarch64

All three analysis commands support --json for structured output. The CLI guide covers complete options, exit codes, and further examples.

MCP

Compatag exposes a local MCP stdio server through compatag-mcp. The MCP client launches the server and receives these tools:

The following registration examples assume that Compatag is installed and compatag-mcp is available on the client's PATH.

Codex CLI:

codex mcp add compatag -- compatag-mcp

Claude Code:

claude mcp add --transport stdio compatag -- compatag-mcp

Other clients (Cursor, Antigravity, and similar editors):

Local stdio configuration uses compatag-mcp as the command, with no arguments. For clients that accept an mcpServers configuration, such as Cursor, a minimal entry is:

{
  "mcpServers": {
    "compatag": {
      "command": "compatag-mcp",
      "args": []
    }
  }
}

The configuration location and format depend on the client. An absolute executable path can replace compatag-mcp when the installation is outside the client's PATH.

MCP manifest tools receive manifest contents, not arbitrary filesystem paths. The client reads the file and passes its text to Compatag. The MCP guide covers tool inputs, optional groups, and result handling.

Current Scope and Limitations

• Analysis covers direct dependencies. Transitive dependencies are not resolved.
• Interpreter support is currently limited to CPython.
• Results are based on published PyPI distribution metadata and artifacts. Compatag does not execute packages or guarantee application or runtime compatibility.
• A source distribution means a source build may be required. Compatag does not build it or prove that the build will succeed.
• Markers and Python constraints that cannot be resolved from the supplied target are reported as indeterminate.
• Direct URL requirements and local package paths are outside the current analysis scope. Pip directives such as -r, -c, -e, and --index-url produce manifest issues. Dynamically supplied project dependencies cannot be fully audited from static text.

The manifest guide describes supported input syntax and limitations.

Further documentation covers compatibility results, architecture, development, and releasing.

To-do

• Transitive dependency resolution.
• Streamable HTTP MCP transport for remote deployment.

License

Compatag is released under the MIT License.