# pkg-booper

[![CI](https://github.com/FennecOnTheNet/pkg-booper-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/FennecOnTheNet/pkg-booper-mcp/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/pkg-booper.svg)](https://www.npmjs.com/package/pkg-booper)
[![codecov](https://codecov.io/gh/FennecOnTheNet/pkg-booper-mcp/graph/badge.svg)](https://codecov.io/gh/FennecOnTheNet/pkg-booper-mcp)

> Boop your dependencies' snoots.

An MCP server that gives AI assistants tools to check up-to-date npm package versions, as well as gleaning other security heuristics.
It's not a super comprehensive analysis, just a lil' snoot boop.

## What is this?

pkg-booper is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides npm package intelligence for AI-assisted development. It fills the gap where documentation tools exist but version/health checking doesn't.

**Key features:**
- Quick version lookups for any npm package
- Security signal analysis using transparent indicators
- Batch analysis of entire `package.json` files
- Caching for fast repeated lookups

## Installation

Run directly with npx:

```bash
npx pkg-booper
```

Or install globally:

```bash
npm install -g pkg-booper
pkg-booper
```

## MCP Client Configuration

### Claude Desktop

Add to your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "pkg-booper": {
      "command": "npx",
      "args": ["-y", "pkg-booper"]
    }
  }
}
```

### Cursor

Add to your Cursor MCP settings (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "pkg-booper": {
      "command": "npx",
      "args": ["-y", "pkg-booper"]
    }
  }
}
```

### Claude Code

Add to your Claude Code MCP settings file (`.mcp.json`):

```json
{
  "mcpServers": {
    "pkg-booper": {
      "command": "npx",
      "args": ["-y", "pkg-booper"]
    }
  }
}
```

### Cline

Add to your Cline MCP settings:

```json
{
  "mcpServers": {
    "pkg-booper": {
      "command": "npx",
      "args": ["-y", "pkg-booper"]
    }
  }
}
```

## Tools

### pkg-booper-boop

Quick version lookup for an npm package.

**Input:**
```json
{
  "package": "lodash",
  "skipCache": false
}
```

**Output:**
```json
{
  "success": true,
  "package": "lodash",
  "latest": "4.17.21",
  "tags": {
    "latest": "4.17.21"
  },
  "summary": "lodash@4.17.21"
}
```

### pkg-booper-sniff

Signal-based security analysis of an npm package. Returns information that lets the AI reason about the combination of indicators.

**Input:**
```json
{
  "package": "express",
  "version": "4.18.2",
  "compareVersions": true,
  "skipCache": false
}
```

**Output:**
```json
{
  "success": true,
  "package": "express",
  "version": "4.18.2",
  "facts": {
    "age": { "days": 4500, "created": "2010-12-29" },
    "lastPublish": { "days": 180, "version": "4.18.2" },
    "weeklyDownloads": 30000000,
    "maintainerCount": 3,
    "versionCount": 275,
    "hasTypes": true,
    "hasRepository": true
  },
  "definitiveIndicators": [],
  "behavioralSignals": [],
  "info": ["Popular package: 30M weekly downloads"],
  "summary": "express@4.18.2: No concerning signals detected"
}
```

**Signal Categories:**
- `definitiveIndicators`: Critical security issues (malware markers, deprecated status)
- `behavioralSignals`: Patterns that warrant investigation (new package, single maintainer, suspicious scripts)
- `info`: Neutral observations (popularity, age, features)

### pkg-booper-big-sniff-file

Batch analyze all dependencies from a `package.json` file.

**Input:**
```json
{
  "path": "/path/to/package.json",
  "includeDevDependencies": true,
  "skipCache": false
}
```

**Output:**
```json
{
  "success": true,
  "packageJsonPath": "/path/to/package.json",
  "results": {
    "lodash": { "success": true, "package": "lodash", "..." },
    "express": { "success": true, "package": "express", "..." }
  },
  "summary": {
    "total": 15,
    "clean": 14,
    "suspicious": 1,
    "outdated": 3,
    "definiteThreats": 0,
    "failed": 0
  },
  "humanSummary": "Analyzed 15 packages: 14 clean, 1 suspicious, 0 threats"
}
```

### pkg-booper-big-sniff-list

Batch analyze a provided list of dependencies.

**Input:**
```json
{
  "dependencies": {
    "lodash": "^4.17.21",
    "express": "^4.18.2",
    "axios": "^1.6.0"
  },
  "skipCache": false
}
```

**Output:** Same format as `pkg-booper-big-sniff-file`.

### pkg-booper-clear-cache

Clear cached npm package data.

**Input:**
```json
{
  "package": "lodash",
  "type": "all"
}
```

- `package`: Optional. Clear cache for specific package, or omit for all.
- `type`: `"all"` | `"versions"` | `"health"` | `"popular"`

**Output:**
```json
{
  "success": true,
  "cleared": ["lodash:versions", "lodash:health"],
  "summary": "Cleared 2 cache entries for lodash"
}
```

## Configuration

pkg-booper can be configured via YAML files, environment variables, or programmatic overrides.

### Configuration File Locations

Files are checked in this order (first found wins):

1. `PKG_BOOPER_CONFIG` environment variable path
2. `./pkg-booper.yaml` (project directory)
3. `~/.config/pkg-booper/config.yaml` (user config)

### Example Configuration

```yaml
# pkg-booper.yaml
cache:
  directory: ~/.cache/pkg-booper
  ttl: 86400  # 24 hours in seconds
  popularPackagesTtl: 604800  # 7 days for popular packages

thresholds:
  levenshtein: 2  # Typosquat detection sensitivity
  lowDownloads: 100  # Weekly downloads below this trigger a signal

scoring:
  weights:
    maturity: 0.15
    popularity: 0.25
    maintenance: 0.25
    trust: 0.25
    completeness: 0.10

github:
  token: ${GITHUB_TOKEN}  # Interpolates from environment

timeout: 10000  # Request timeout in ms

rateLimit:
  npm:
    requestsPerSecond: 10
  github:
    requestsPerMinute: 30

debug: false
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `GITHUB_TOKEN` | GitHub API token for enhanced rate limits | - |
| `PKG_BOOPER_CONFIG` | Path to custom config file | - |
| `PKG_BOOPER_CACHE_DIR` | Cache directory | `~/.cache/pkg-booper` |
| `PKG_BOOPER_CACHE_TTL` | Cache TTL in seconds | `86400` |
| `PKG_BOOPER_TIMEOUT` | Request timeout in ms | `10000` |
| `PKG_BOOPER_DEBUG` | Enable debug logging | `false` |

## Examples

### AI Assistant Usage

**User:** "What's the latest version of React?"

**AI uses pkg-booper-boop:**
```
React is currently at version 18.2.0.
```

**User:** "Analyze the security of this package.json"

**AI uses pkg-booper-big-sniff-file:**
```
I analyzed 23 dependencies:
- 21 packages look clean
- 2 packages have behavioral signals worth noting:
  - some-package: New package (< 30 days old), single maintainer
  - another-pkg: Significantly outdated (2 major versions behind)

No definitive threats detected, but you may want to review the flagged packages.
```

**User:** "Is 'lod-ash' a legit package?"

**AI uses pkg-booper-sniff:**
```
Warning: 'lod-ash' appears to be a typosquat of 'lodash':
- Very similar name (Levenshtein distance: 1)
- Much lower download count than lodash
- Created recently compared to lodash

I'd recommend using the official 'lodash' package instead.
```

## License

This is licensed under the AGPLv3.

Why? I feel like information deserves to be free. Code is a sort of 
information, and I know the AGPL is pretty good at encouraging sharing. 
That, and I think of the code I put together with the help of generative 
AI less like an original composition, and more like a silly mashup.

I don't feel comfortable publishing my mashups under anything less open ;)