mcp-sanity-check

A dependency-light CLI that scans a repository's tracked files for owner identifiers and secrets, then exits non-zero if it finds any. Drop it into CI or a pre-push hook and private data cannot ship into a public repo.

What problem it solves

When you maintain a fleet of MCP servers (or any set of personal automation repos) that you plan to publish publicly, a single slip can embed your home IP, email, device hostname, or an API key in the Git history forever. mcp-sanity-check is the last gate before a push or a CI merge — it scans every tracked file and blocks the operation if anything personal is found.

The tool ships with no owner identifiers baked in, so the scanner itself can live in a public repo without leaking anyone's data. Your specific strings (emails, account IDs, home-LAN IPs, device names) stay in ~/.config/mcp-sanity/identifiers.json on your machine and are never committed anywhere.

Related MCP server: credential-free

Install

One-liner via npx (no install needed):

npx -y github:nidamen/mcp-sanity-check-mcp --path /path/to/repo

Or install globally:

npm install -g mcp-sanity-check
mcp-sanity-check --path /path/to/repo

Or run from a local checkout:

node bin/mcp-sanity-check.mjs --path /path/to/repo

Requires Node >= 18. Zero runtime dependencies.

MCP client configuration

This tool runs as a stdio MCP server. Add it to your MCP client config:

{
  "mcpServers": {
    "mcp-sanity-check": {
      "command": "npx",
      "args": ["-y", "github:nidamen/mcp-sanity-check-mcp"],
      "env": {}
    }
  }
}

To use your private identifier list, set the MCP_SANITY_IDENTIFIERS environment variable to the path of your identifiers.json:

{
  "mcpServers": {
    "mcp-sanity-check": {
      "command": "npx",
      "args": ["-y", "github:nidamen/mcp-sanity-check-mcp"],
      "env": {
        "MCP_SANITY_IDENTIFIERS": "/Users/you/.config/mcp-sanity/identifiers.json"
      }
    }
  }
}

CLI usage

mcp-sanity-check [--path <dir>] [--staged] [--range <a..b>] [--json] [--quiet] [--no-color]

Exit codes: 0 = clean, 1 = one or more hits found, 2 = usage error (bad path, etc.).

Complete tool reference

This is a CLI tool, not an MCP tool-calling server. The scanner exposes one capability: scan a directory and report leaks.

mcp-sanity-check (CLI / binary)

Purpose: Scan a repository for owner identifiers and secrets and exit non-zero if any are found.

Modes:

Input parameters:

Returns (human mode):

✓ mcp-sanity-check: clean (42 files scanned)

or on a hit:

✗ mcp-sanity-check: 2 potential leak(s) found
  SECRET    config.env:3  github-personal-access-token (ghp_)  -> ghp_****...ab
  IDENTIFIER src/client.js:7  owner-identifier:you@example.com  -> you@****
BLOCKED: 2 hit(s) across 42 files. Remove the values above, ...

Returns (JSON mode, --json):

{
  "ok": false,
  "filesScanned": 42,
  "hitCount": 2,
  "mode": "full",
  "hits": [
    {
      "file": "config.env",
      "line": 3,
      "class": "secret",
      "pattern": "github-personal-access-token (ghp_)",
      "masked": "ghp_****...ab"
    }
  ]
}

Fields in each hit object:

What gets flagged

Owner identifiers

Loaded at runtime from (in priority order):

1. Path in $MCP_SANITY_IDENTIFIERS environment variable (points to a JSON file).

2. ~/.config/mcp-sanity/identifiers.json (default private config location).

3. identifiers array in the scanned repo's .sanity-patterns.json.

The JSON file must be an object with an identifiers array of strings:

{ "identifiers": ["your@email.com", "192.168.1.50", "myhostname", "acct-id-xyz"] }

This file is never committed anywhere. It lives only on your machine.

Generic PII (public CI backstop)

Even without a private identifier list, the scanner catches:

Obvious documentation placeholders (you@example.com, 192.168.1.1, /home/user, aa:bb:cc:dd:ee:ff, etc.) are excluded so docs and examples do not trip the backstop.

Secret patterns

The high-entropy rule fires only when the assigned value is 40+ characters, base64-ish, and clears a Shannon-entropy threshold (H >= 3.5 bits/char, 12+ distinct characters). This keeps false positives low on long-but-repetitive strings.

All matched values are masked in output: the first 4 and last 2 characters are shown; everything in between is replaced with *.

Private config: ~/.config/mcp-sanity/

The directory ~/.config/mcp-sanity/ is the one place the owner's specific identifiers live. It is:

• Never committed (it sits outside any repo).

• Never referenced by path in any tracked file.

• Loaded at runtime by the scanner binary on the machine where the private list is needed.

Structure:

~/.config/mcp-sanity/
  identifiers.json      <- {"identifiers": ["your@email.com", "192.168.1.50", ...]}

How a repo opts in

Option 1: CI workflow

Copy .github/workflows/sanity-check.yml from this repo into the target repo. It runs on every push and PR using ubuntu-latest + Node 20, fetches the full history, and fails the build on any hit.

It can also be called as a reusable workflow:

jobs:
  sanity:
    uses: nidamen/mcp-sanity-check/.github/workflows/sanity-check.yml@main

Option 2: Pre-push git hook

Install hooks/pre-push so leaks are blocked before they ever reach the remote. The hook scans only the outgoing commit range, so it is fast.

# Per-repo:
cp /path/to/mcp-sanity-check/hooks/pre-push /path/to/your-repo/.git/hooks/pre-push
chmod +x /path/to/your-repo/.git/hooks/pre-push

# Shared across all repos (global hooks dir):
mkdir -p ~/.git-hooks
cp /path/to/mcp-sanity-check/hooks/pre-push ~/.git-hooks/pre-push
chmod +x ~/.git-hooks/pre-push
git config --global core.hooksPath ~/.git-hooks

The hook resolves the scanner via (in order): $MCP_SANITY_CHECK env var (full path to the .mjs), mcp-sanity-check on PATH, or npx mcp-sanity-check.

To bypass intentionally (not recommended): git push --no-verify.

Per-repo tuning: .sanity-patterns.json

Place a .sanity-patterns.json file at the scanned repo's root to extend or relax the defaults:

{
  "identifiers": ["ACME_INTERNAL_CODENAME", "another-owner-string"],
  "allow":       ["EXAMPLE_PLACEHOLDER"],
  "allowFiles":  ["docs/sample-output.txt", "test/fixtures/"]
}

Quick usage examples

Check a repo before publishing:

mcp-sanity-check --path ~/code/my-mcp-server

Run in CI (no color, machine output):

mcp-sanity-check --path . --no-color --json | tee scan-report.json

Check only what you are about to commit:

mcp-sanity-check --staged

Tests

npm test
# or
node test/run.mjs

The suite creates dirty fixtures in a temp directory (planted identifiers and secrets never live in tracked source), confirms the scanner catches them, confirms the values are masked in output, confirms the allow-list suppresses false positives, and confirms a clean directory exits zero.

Limitations

• Scans text files only. Files larger than 5 MB and files with a NUL byte in the first 4 KB are skipped.

• Binary file types (images, archives, compiled objects, fonts, audio, video, SQLite, lock files) are skipped by extension.

• The high-entropy rule can still produce false positives on long deterministic strings (base64-encoded config blobs, encoded protobuf payloads). Use allow in .sanity-patterns.json to suppress these.

• Generic PII patterns (email, RFC1918 IP, home path, MAC) are designed to catch leaks in public CI where the private identifier list is unavailable; they may fire on legitimate example values that are not in the placeholder list. Add them to allow as needed.

• --staged and --range modes scan only added lines in the diff, not the full file state. A pre-existing leak in unchanged lines is not caught until a full --path scan is run.

• Entropy check thresholds (H >= 3.5, distinct >= 12) were tuned empirically; an unusually low-entropy real secret may not be caught by the high-entropy rule (but would still be caught if it matches a named pattern).

License

MIT