watermarkbuster-mcp 1.0.1 → 1.2.0

package/README.md

@@ -1,20 +1,21 @@
 # Watermark Buster MCP
 
-Connect an MCP client to the hosted Watermark Buster tools. This package is a local stdio 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`
+- An operator-issued Watermark Buster bearer token in `WATERMARKS_API_TOKEN`
 
-No account, API token, GPU, Python, or local model is required.
+No GPU, Python, or local model is required for the default hosted mode.
 
 ## Run without installing
 
 Use `npx` to download and start the current package:
 
 ```bash
-npx -y watermarkbuster-mcp
+WATERMARKS_API_TOKEN=YOUR_CLIENT_BEARER_TOKEN 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.
@@ -27,10 +28,10 @@ Install the command on your computer:
 npm install --global watermarkbuster-mcp
 ```
 
-Your MCP client can then start:
+Your MCP client can then start it with `WATERMARKS_API_TOKEN` in its environment:
 
 ```text
-watermarkbuster-mcp
+WATERMARKS_API_TOKEN=YOUR_CLIENT_BEARER_TOKEN watermarkbuster-mcp
 ```
 
 To add the package to one Node.js project instead, run:
@@ -39,6 +40,28 @@ To add the package to one Node.js project instead, run:
 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:
@@ -55,7 +78,8 @@ Clients that use an `mcpServers` JSON object commonly use this form:
   "mcpServers": {
     "watermark-buster": {
       "command": "npx",
-      "args": ["-y", "watermarkbuster-mcp"]
+      "args": ["-y", "watermarkbuster-mcp"],
+      "env": {"WATERMARKS_API_TOKEN": "YOUR_CLIENT_BEARER_TOKEN"}
     }
   }
 }
@@ -63,7 +87,7 @@ Clients that use an `mcpServers` JSON object commonly use this form:
 
 ## Connect directly to the remote server
 
-Clients that support remote Streamable HTTP MCP do not need this npm bridge. Connect them directly to:
+Clients that support remote Streamable HTTP MCP do not need this npm bridge. Connect them directly to the URL below and send `Authorization: Bearer YOUR_CLIENT_BEARER_TOKEN` on every protocol request:
 
 ```text
 https://watermarkbuster.com/mcp
@@ -71,30 +95,22 @@ https://watermarkbuster.com/mcp
 
 ### Codex
 
-Add this to `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.watermark_buster]
-url = "https://watermarkbuster.com/mcp"
+```bash
+export WATERMARKS_API_TOKEN='YOUR_CLIENT_BEARER_TOKEN'
+codex mcp add watermark-buster \
+  --url https://watermarkbuster.com/mcp \
+  --bearer-token-env-var WATERMARKS_API_TOKEN
 ```
 
 Restart Codex, then run `codex mcp list` or use `/mcp` inside Codex.
 
 ### Claude Code
 
-```bash
-claude mcp add --transport http watermark-buster https://watermarkbuster.com/mcp
-```
-
-Run `claude mcp list` or use `/mcp` inside Claude Code.
+Use the authenticated npm bridge configuration above, then run `claude mcp list` or use `/mcp` inside Claude Code.
 
 ### Gemini CLI
 
-```bash
-gemini mcp add --transport http watermark-buster https://watermarkbuster.com/mcp
-```
-
-Run `gemini mcp list` to confirm the connection.
+Use the authenticated npm bridge configuration above, then run `gemini mcp list` to confirm the connection.
 
 ### Cursor
 
@@ -104,7 +120,9 @@ Add this to `.cursor/mcp.json` for one project or `~/.cursor/mcp.json` for all p
 {
   "mcpServers": {
     "watermark-buster": {
-      "url": "https://watermarkbuster.com/mcp"
+      "command": "npx",
+      "args": ["-y", "watermarkbuster-mcp"],
+      "env": {"WATERMARKS_API_TOKEN": "YOUR_CLIENT_BEARER_TOKEN"}
     }
   }
 }
@@ -120,7 +138,9 @@ Add this to `~/.gemini/config/mcp_config.json` for all workspaces or `.agents/mc
 {
   "mcpServers": {
     "watermark-buster": {
-      "serverUrl": "https://watermarkbuster.com/mcp"
+      "command": "npx",
+      "args": ["-y", "watermarkbuster-mcp"],
+      "env": {"WATERMARKS_API_TOKEN": "YOUR_CLIENT_BEARER_TOKEN"}
     }
   }
 }
@@ -134,22 +154,30 @@ The bridge reads the current tool list from the hosted MCP server when it starts
 
 - `inspect_text` — report supported hidden Unicode without changing the text
 - `clean_text` — remove supported hidden Unicode and exotic spaces
+- `scan_and_rewrite_text` — run the model-free English light rewrite and return estimate-only scores, quality metrics, highlights, and a diff; input is limited to 128 KB
 - `clean_file` — clean a supported file and return the cleaned copy
+- `clean_synthid_image` — run the supported best-effort CPU SynthID scan on one PNG or JPEG and return the PNG plus residual report
 - `get_capabilities` — read the current formats, limits, and behavior
 
 Example agent requests:
 
 - “Inspect this text for hidden Unicode.”
+- “Scan and lightly rewrite this English text, then show the diff and limits.”
 - “Clean this file and return the cleaned copy.”
+- “Run the SynthID image scan and tell me if a residual remains.”
 - “Show the current Watermark Buster capabilities.”
 
+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
 
-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.
+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 the token is missing or the hosted service cannot be reached, the command writes `Watermark Buster MCP: <reason>` to standard error and exits with a failure status. Check `WATERMARKS_API_TOKEN` and connectivity, 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).
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "watermarkbuster-mcp",
-  "version": "1.0.1",
-  "description": "Connect local MCP clients to the hosted Watermark Buster tools.",
+  "version": "1.2.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": [
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/client": "2.0.0",
-    "@modelcontextprotocol/server": "2.0.0"
+    "@modelcontextprotocol/client": "2.4.0",
+    "@modelcontextprotocol/server": "2.4.0"
   }
 }

package/src/cli.js

@@ -9,8 +9,39 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import {
   PACKAGE_VERSION,
   REMOTE_MCP_ENDPOINT,
+  authenticatedRequestInit,
   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);
@@ -50,6 +81,7 @@ async function startBridge() {
   });
   const remoteTransport = new StreamableHTTPClientTransport(
     new URL(REMOTE_MCP_ENDPOINT),
+    { requestInit: authenticatedRequestInit() },
   );
   await remoteClient.connect(remoteTransport);
   const { tools } = await remoteClient.listTools();
@@ -60,7 +92,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;
+  });
+}

package/src/server.js

@@ -14,6 +14,14 @@ const SERVER_INSTRUCTIONS = [
   "The hosted service does not archive submitted content.",
 ].join(" ");
 
+export function authenticatedRequestInit(environment = process.env) {
+  const apiToken = environment.WATERMARKS_API_TOKEN?.trim();
+  if (!apiToken) {
+    throw new Error("WATERMARKS_API_TOKEN is required for the hosted MCP server");
+  }
+  return { headers: { Authorization: `Bearer ${apiToken}` } };
+}
+
 function remoteToolConfiguration(remoteTool) {
   const configuration = {
     title: remoteTool.title,