Verify dependencies before install.
Not scan after the fact.

Standard PyPI Installation

Install the standalone CLI and Python library directly via pip, uv, or poetry:

pip install isitreal

Development Setup & Testing

To clone the source repository, run tests, and develop extensions:

git clone https://github.com/example/isitreal.git
cd isitreal
pip install -e '.[dev]'
pytest

Core Verification Functions

isitreal exposes clean synchronous and batch verification methods via the verify module:

from isitreal import verify

# 1. Verify a nonexistent package
res = verify.package("fancylib")
# -> PackageResult(name='fancylib', exists=False, suggestions=['fancy-lib', ...], risk=None, ...)

# 2. Verify a well-established PyPI package
res = verify.package("requests")
# -> PackageResult(name='requests', exists=True, risk='low', age_days=5640, ...)

# 3. Verify a known hallucinated/slopsquatted package
res = verify.package("react-codeshift")
# -> PackageResult(name='react-codeshift', exists=False, risk='high', reasons=['Package name is in the known list...'])

# 4. Scan a requirements.txt or pyproject.toml file
results = verify.scan("requirements.txt")
# -> list[PackageResult] sorted worst-risk-first

PackageResult Data Model

Each verification query returns an immutable Pydantic PackageResult instance with the following fields:

1. Check a Single Package

Use isitreal check <package> to print a rich formatted diagnostic panel:

isitreal check requests
isitreal check react-codeshift

2. Scan Dependency Files

Scan requirements.txt or pyproject.toml and display a structured table sorted worst-risk-first:

isitreal scan requirements.txt

3. Automated CI/CD Gating (--fail-on)

Use the --fail-on flag to exit with nonzero code 1 whenever any dependency matches or exceeds the specified risk threshold:

isitreal scan requirements.txt --fail-on high

Example GitHub Actions CI Workflow

Add dependency reality-checking to your pull request pipeline:

name: Dependency Reality Check
on: [push, pull_request]

jobs:
  verify-deps:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Install isitreal
        run: pip install isitreal
      - name: Scan requirements for slopsquatting / hallucinations
        run: isitreal scan requirements.txt --fail-on high

Native FastMCP Implementation

isitreal bundles an official Python Model Context Protocol (MCP) server built on FastMCP. When connected, AI agents automatically query two tools:

• verify_package(name: str, ecosystem: str = "pypi") -> PackageResult — Checks a single package for existence, release age, download signals, and slopsquatting lists.
• verify_dependencies(file_contents: str) -> list[PackageResult] — Parses requirements text or pyproject.toml content and returns an ordered risk assessment.

Configuration in Claude Desktop

Add the server to your Claude Desktop configuration file (~/.config/Claude/claude_desktop_config.json on macOS/Linux or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "isitreal": {
      "command": "isitreal-mcp"
    }
  }
}

Configuration in Claude Code / CLI (`.claude.json`)

Configure project-wide verification for Claude Code by editing your repository's .claude.json:

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