Metadata-Version: 2.4
Name: watermarkbuster-local
Version: 0.1.0
Summary: Local Watermark Buster CLI and MCP server.
Author: Watermark Buster
License-Expression: MIT
Project-URL: Homepage, https://watermarkbuster.com
Project-URL: Documentation, https://watermarkbuster.com/mcp
Keywords: mcp,watermark,metadata,unicode,privacy
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp==2.0.0
Dynamic: license-file

# Watermark Buster Local

Run Watermark Buster on your computer. The package includes a command line tool and a local stdio MCP server for Codex, Claude Code, Gemini CLI, Cursor, Antigravity, and other MCP clients.

Normal text and file cleaning uses the CPU and Python standard library. It does not send content to `watermarkbuster.com`.

## Install

Python 3.10 or newer is required. `pipx` keeps the command in its own Python environment:

```bash
pipx install watermarkbuster-local
watermarkbuster-local doctor
```

To install this source checkout before the public package is released:

```bash
cd /path/to/watermarkbuster.com
pipx install .
watermarkbuster-local doctor
```

Upgrade a released install with:

```bash
pipx upgrade watermarkbuster-local
```

## Use the CLI

Inspect or clean one file:

```bash
watermarkbuster-local inspect draft.md
watermarkbuster-local clean draft.md -o draft.cleaned.md
```

Audit a folder:

```bash
watermarkbuster-local audit-directory ./content --json > audit.json
```

Audit same-site URLs from a sitemap:

```bash
watermarkbuster-local audit-website \
  --sitemap https://example.com/sitemap.xml \
  --max-pages 100 \
  --json > website-audit.json
```

The audit follows only URLs with the same scheme, host, and port as the sitemap. It reads at most 4 MB from each URL by default.

## Connect an AI agent

The safest setup gives the agent access to one folder:

```bash
watermarkbuster-local mcp --root /ABSOLUTE/PATH/TO/YOUR/FILES
```

The command waits for MCP messages on standard input. An MCP client starts it for you.

### Codex

```bash
codex mcp add watermark-buster-local -- \
  watermarkbuster-local mcp --root /ABSOLUTE/PATH/TO/YOUR/FILES
```

Then run `codex mcp list`.

### Gemini CLI

```bash
gemini mcp add --scope user watermark-buster-local \
  watermarkbuster-local mcp -- --root /ABSOLUTE/PATH/TO/YOUR/FILES
```

Then run `gemini mcp list`.

### Claude Code

```bash
claude mcp add --scope user watermark-buster-local -- \
  watermarkbuster-local mcp --root /ABSOLUTE/PATH/TO/YOUR/FILES
```

Then run `claude mcp list` or use `/mcp` inside Claude Code.

### Cursor, Antigravity, and JSON clients

Use this stdio MCP server object in the client's MCP settings:

```json
{
  "mcpServers": {
    "watermark-buster-local": {
      "command": "watermarkbuster-local",
      "args": [
        "mcp",
        "--root",
        "/ABSOLUTE/PATH/TO/YOUR/FILES"
      ]
    }
  }
}
```

Use a real absolute path. Restart the client after you save its settings.

## Use npx or npm

The npm command can start the local Python package after `pipx install watermarkbuster-local`:

```bash
npx -y watermarkbuster-mcp --local --root "$PWD"
```

Or install both commands once:

```bash
pipx install watermarkbuster-local
npm install --global watermarkbuster-mcp
watermarkbuster-mcp --local --root "$PWD"
```

`npx` installs the small MCP launcher. `pipx` installs the local cleaning engine.

## Local MCP tools

- `inspect_text` finds hidden Unicode without changing text.
- `clean_text` returns clean text and removal counts.
- `inspect_file` checks one file inside the allowed folder.
- `clean_file` writes a clean copy inside the allowed folder.
- `audit_directory` checks a folder tree.
- `audit_website` checks same-site sitemap URLs when network access is enabled.
- `rewrite_text_local` uses an Ollama server on this computer.
- `remove_pixel_watermark` uses the optional `noai-watermark` command.
- `get_local_capabilities` shows the folder boundary and optional tool status.

## Optional local model rewriting

Install and start Ollama separately. Pull a model that is suitable for your computer, then run:

```bash
watermarkbuster-local rewrite draft.txt \
  --model YOUR_LOCAL_MODEL \
  -o draft.rewritten.txt
```

Only loopback Ollama URLs such as `http://127.0.0.1:11434` are accepted. This prevents an agent from sending the text to a remote rewrite server.

## Optional pixel cleaning

Pixel cleaning uses the separate `noai-watermark` project. It can run on a CPU, but the first use can download about 4 GB for the default model or about 10 GB for CtrlRegen.

That project does not currently publish a license file. Watermark Buster does not include its code or model files. Confirm that you have permission to install and use it before you continue.

```bash
pipx install noai-watermark
watermarkbuster-local remove-pixel source.png \
  -o source.pixel-cleaned.png
```

Use `--model-profile ctrlregen` for the larger CtrlRegen pipeline. Watermark Buster does not bundle its code or model files.

## Website access for agents

Website audit is off in MCP mode by default. Turn it on only when the agent must audit a site:

```bash
watermarkbuster-local mcp \
  --root /ABSOLUTE/PATH/TO/YOUR/FILES \
  --allow-network
```

The direct CLI website command does not need this flag because you start that command yourself.

## File safety

- The MCP server can access only `--root`. Its default is the folder where it starts.
- Paths that leave the allowed folder are rejected.
- Cleaning writes a new file unless you give the same output path yourself through the direct CLI.
- Normal cleaning needs no account, token, model, GPU, or internet connection.
- `rewrite_text_local` needs a local Ollama model.
- `remove_pixel_watermark` needs the separate pixel tool and its model files.

Use these tools only on content that you own or have permission to change.

## License

MIT. See the repository `LICENSE` file.
