watermarkbuster-mcp 1.0.0 → 1.1.0

package/README.md

@@ -1,15 +1,67 @@
 # Watermark Buster MCP
 
-Connect a local MCP client to the hosted Watermark Buster tools. The package is a bridge. It does not run the cleaning engine on your computer.
+Connect an MCP client to hosted or local Watermark Buster tools. The default mode is a stdio bridge to the hosted service. `--local` starts the separately installed local cleaning package.
 
 ## Requirements
 
 - Node.js 20 or newer
 - An internet connection to `https://watermarkbuster.com/mcp`
 
-No account, API token, GPU, Python, or local model is required.
+No account, API token, GPU, Python, or local model is required for the default hosted mode.
 
-## Use with `npx`
+## Run without installing
+
+Use `npx` to download and start the current package:
+
+```bash
+npx -y watermarkbuster-mcp
+```
+
+The command waits for MCP messages on standard input. It does not open a user interface or show a prompt. Normally, your MCP client starts this command for you.
+
+## Install the command
+
+Install the command on your computer:
+
+```bash
+npm install --global watermarkbuster-mcp
+```
+
+Your MCP client can then start:
+
+```text
+watermarkbuster-mcp
+```
+
+To add the package to one Node.js project instead, run:
+
+```bash
+npm install watermarkbuster-mcp
+```
+
+## Run all cleaning locally
+
+Install the local Python package once:
+
+```bash
+pipx install watermarkbuster-local
+```
+
+Then use the npm launcher in local mode:
+
+```bash
+npx -y watermarkbuster-mcp --local --root "$PWD"
+```
+
+Or, after the global npm install:
+
+```bash
+watermarkbuster-mcp --local --root "$PWD"
+```
+
+`--root` limits agent file access to one folder. Add `--allow-network` only when the local agent must run the website sitemap audit.
+
+## Add the npx bridge to an MCP client
 
 Set these values in your MCP client:
 
@@ -18,7 +70,7 @@ Command: npx
 Arguments: -y watermarkbuster-mcp
 ```
 
-For clients that use an `mcpServers` JSON object, the matching form is:
+Clients that use an `mcpServers` JSON object commonly use this form:
 
 ```json
 {
@@ -31,39 +83,102 @@ For clients that use an `mcpServers` JSON object, the matching form is:
 }
 ```
 
-The MCP client starts the command. Running it in a normal terminal shows no user interface because it waits for MCP messages on standard input.
+## Connect directly to the remote server
+
+Clients that support remote Streamable HTTP MCP do not need this npm bridge. Connect them directly to:
+
+```text
+https://watermarkbuster.com/mcp
+```
+
+### Codex
 
-## Install first
+Add this to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.watermark_buster]
+url = "https://watermarkbuster.com/mcp"
+```
+
+Restart Codex, then run `codex mcp list` or use `/mcp` inside Codex.
+
+### Claude Code
 
 ```bash
-npm install --global watermarkbuster-mcp
+claude mcp add --transport http watermark-buster https://watermarkbuster.com/mcp
 ```
 
-Then set the MCP command to:
+Run `claude mcp list` or use `/mcp` inside Claude Code.
 
-```text
-watermarkbuster-mcp
+### Gemini CLI
+
+```bash
+gemini mcp add --transport http watermark-buster https://watermarkbuster.com/mcp
+```
+
+Run `gemini mcp list` to confirm the connection.
+
+### Cursor
+
+Add this to `.cursor/mcp.json` for one project or `~/.cursor/mcp.json` for all projects:
+
+```json
+{
+  "mcpServers": {
+    "watermark-buster": {
+      "url": "https://watermarkbuster.com/mcp"
+    }
+  }
+}
+```
+
+Open Cursor's Customize sidebar, select MCP, and confirm that the server is enabled.
+
+### Google Antigravity
+
+Add this to `~/.gemini/config/mcp_config.json` for all workspaces or `.agents/mcp_config.json` for one workspace:
+
+```json
+{
+  "mcpServers": {
+    "watermark-buster": {
+      "serverUrl": "https://watermarkbuster.com/mcp"
+    }
+  }
+}
 ```
 
+Save the file, then refresh Installed MCP Servers.
+
 ## Tools
 
 The bridge reads the current tool list from the hosted MCP server when it starts. The current tools are:
 
-- `inspect_text`
-- `clean_text`
-- `clean_file`
-- `get_capabilities`
+- `inspect_text` — report supported hidden Unicode without changing the text
+- `clean_text` — remove supported hidden Unicode and exotic spaces
+- `clean_file` — clean a supported file and return the cleaned copy
+- `get_capabilities` — read the current formats, limits, and behavior
 
-## Data flow
+Example agent requests:
 
-Tool input is sent to `https://watermarkbuster.com` for processing. The hosted service processes content for the call and does not archive it. Do not use this npm bridge if content must stay on your computer.
+- “Inspect this text for hidden Unicode.”
+- “Clean this file and return the cleaned copy.”
+- “Show the current Watermark Buster capabilities.”
 
-For clients that support remote Streamable HTTP MCP, connect directly to `https://watermarkbuster.com/mcp` instead.
+Local mode exposes the larger local tool set: direct file paths, folder audit, opt-in website audit, local Ollama rewriting, and an adapter for the optional `noai-watermark` pixel tool. See the [local package guide](https://pypi.org/project/watermarkbuster-local/).
+
+## Data flow
+
+In the default mode, tool input is sent to `https://watermarkbuster.com` for processing. In `--local` mode, normal cleaning stays on the computer. Optional website audit uses the network, and optional pixel cleaning can download model files.
 
 ## Connection errors
 
 If the hosted service cannot be reached, the command writes `Watermark Buster MCP: <reason>` to standard error and exits with a failure status. Check that `https://watermarkbuster.com/mcp` is reachable, then let the MCP client start the command again.
 
+If local mode says that the local package is missing, run `pipx install watermarkbuster-local`, then start the command again.
+
+For more setup help, see [the full MCP guide](https://watermarkbuster.com/mcp).
+
 ## License
 
 MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "watermarkbuster-mcp",
-  "version": "1.0.0",
-  "description": "Connect local MCP clients to the hosted Watermark Buster tools.",
+  "version": "1.1.0",
+  "description": "Connect MCP clients to hosted or local Watermark Buster tools.",
   "type": "module",
   "bin": {
     "watermarkbuster-mcp": "src/cli.js"
@@ -15,7 +15,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "check": "node --check src/cli.js && node --check src/server.js",
+    "check": "node --check src/cli.js && node --check src/local.js && node --check src/server.js",
     "test": "node --test"
   },
   "keywords": [

package/src/cli.js

@@ -11,6 +11,36 @@ import {
   REMOTE_MCP_ENDPOINT,
   createBridgeServer,
 } from "./server.js";
+import { startLocalServer } from "./local.js";
+
+const HELP = `Watermark Buster MCP
+
+Usage:
+  watermarkbuster-mcp                 Connect to the hosted MCP server
+  watermarkbuster-mcp --local         Start the installed local MCP server
+
+Local options:
+  --root <folder>      Limit agent file access to this folder
+  --allow-network      Let the local website audit access the network
+  -h, --help           Show this help
+`;
+
+function parseArguments(argumentsList) {
+  const options = { local: false, root: null, allowNetwork: false, help: false };
+  for (let index = 0; index < argumentsList.length; index += 1) {
+    const argument = argumentsList[index];
+    if (argument === "--local") options.local = true;
+    else if (argument === "--allow-network") options.allowNetwork = true;
+    else if (argument === "--root") options.root = argumentsList[++index];
+    else if (argument === "--help" || argument === "-h") options.help = true;
+    else throw new Error(`unknown option: ${argument}`);
+  }
+  if (options.root === undefined) throw new Error("--root needs a folder");
+  if (!options.local && (options.root || options.allowNetwork)) {
+    throw new Error("--root and --allow-network need --local");
+  }
+  return options;
+}
 
 function reportFailure(error) {
   const message = error instanceof Error ? error.message : String(error);
@@ -60,7 +90,27 @@ async function startBridge() {
   registerShutdown(stdioHandle, remoteClient);
 }
 
-startBridge().catch((error) => {
-  reportFailure(error);
-  process.exitCode = 1;
-});
+function main() {
+  let options;
+  try {
+    options = parseArguments(process.argv.slice(2));
+  } catch (error) {
+    reportFailure(error);
+    process.exitCode = 2;
+    return;
+  }
+  if (options.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (options.local) {
+    startLocalServer(options);
+    return;
+  }
+  startBridge().catch((error) => {
+    reportFailure(error);
+    process.exitCode = 1;
+  });
+}
+
+main();

package/src/local.js

@@ -0,0 +1,30 @@
+import { spawn } from "node:child_process";
+
+export const LOCAL_EXECUTABLE = "watermarkbuster-local";
+
+export function localArguments(options) {
+  const argumentsList = ["mcp"];
+  if (options.root) argumentsList.push("--root", options.root);
+  if (options.allowNetwork) argumentsList.push("--allow-network");
+  return argumentsList;
+}
+
+export function startLocalServer(options) {
+  const child = spawn(LOCAL_EXECUTABLE, localArguments(options), {
+    stdio: "inherit",
+  });
+  child.once("error", (error) => {
+    if (error.code === "ENOENT") {
+      console.error(
+        "Watermark Buster MCP: local package not found. Run: pipx install watermarkbuster-local",
+      );
+    } else {
+      console.error(`Watermark Buster MCP: ${error.message}`);
+    }
+    process.exitCode = 1;
+  });
+  child.once("exit", (code, signal) => {
+    if (signal) process.kill(process.pid, signal);
+    else process.exitCode = code ?? 1;
+  });
+}