Metadata-Version: 2.4
Name: slopspotter
Version: 0.1.1
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
License-File: LICENSE
Summary: Detects AI-hallucinated (slopsquatted) Python packages before they get installed.
Keywords: security,pypi,hallucination,slopsquatting,ai
Author-email: Conran Pearce <54678624+conranpearce@users.noreply.github.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/conranpearce/slopspotter/issues
Project-URL: Homepage, https://github.com/conranpearce/slopspotter
Project-URL: Repository, https://github.com/conranpearce/slopspotter

# slopspotter

[![PyPI](https://img.shields.io/pypi/v/slopspotter)](https://pypi.org/project/slopspotter/)
[![Python](https://img.shields.io/pypi/pyversions/slopspotter)](https://pypi.org/project/slopspotter/)
[![License](https://img.shields.io/pypi/l/slopspotter)](https://github.com/conranpearce/slopspotter/blob/main/LICENSE)

Detects AI-hallucinated Python packages before they get installed.

Checks a package against a curated hallucinated packages database and verifies its existence on PyPI in real time, returning a risk assessment with a clear install recommendation.

Installs two tools:
- `slopspotter` — CLI for manual package checks
- `slopspotter-mcp` — stdio MCP server for AI coding agents

## Installation

```bash
pip install slopspotter
```

## Usage

```bash
slopspotter requests
```

```json
{
  "package": "requests",
  "exists": true,
  "pypi_unavailable": false,
  "in_slop_db": false,
  "risk_level": "low",
  "safe_to_install": true,
  "recommendation": "PROCEED: 'requests' appears safe to install."
}
```

Example high risk output:

```json
{
  "package": "cohere-ai-sdk",
  "exists": false,
  "pypi_unavailable": false,
  "in_slop_db": true,
  "risk_level": "high",
  "safe_to_install": false,
  "recommendation": "BLOCK: 'cohere-ai-sdk' does not exist on PyPI and is flagged as a hallucinated package."
}
```

Exit codes: `0` = low risk, `1` = medium, `2` = high, `3` = critical.

## Risk Levels

| Level | Meaning |
|-------|---------|
| `low` | Exists on PyPI, not flagged |
| `medium` | Flagged with low historical risk |
| `high` | Not on PyPI (hallucinated), flagged, or PyPI unreachable |
| `critical` | Flagged and actively installable on PyPI |

## How It Works

Each package is checked against a curated database of known AI-hallucinated packages and verified against PyPI in real time. The database is maintained by the project author.

## MCP Server

`slopspotter` ships with a stdio MCP server for use with AI coding agents (Claude Code, Cursor, etc.). Once connected, the agent will automatically call `assess_package` before any install and block unsafe packages.

### Claude Code

```bash
claude mcp add slopspotter uvx --from slopspotter slopspotter-mcp
```

Or add manually to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "slopspotter": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "slopspotter", "slopspotter-mcp"]
    }
  }
}
```

If you already have `slopspotter` installed via pip:

```json
{
  "mcpServers": {
    "slopspotter": {
      "type": "stdio",
      "command": "slopspotter-mcp"
    }
  }
}
```

### Other agents (Cursor, Windsurf, etc.)

Use the same JSON config — most agents support the `mcpServers` format.

### Usage

Once connected, your agent will automatically assess packages before installing. You can also ask directly:

> "Is `requests` safe to install?"

