@redactic/mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Redactic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,227 @@
-# Temporary Holding Version
+# Redactic MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Mask, restore and black out personal data in text and files from Claude Desktop, Claude Code,
+Gemini CLI, Cursor and any other MCP client.
+
+The server is a thin client of the API of [Redactic](https://redactic.eu/ai-assistants/) (redactic.eu). Your text and
+files are sent to Redactic servers in the European Union, where the personal data is detected.
+The AI model receives labels such as `⟦PERSON_1⟧`. The map that turns the labels back into the
+original values stays in the memory of this server, on your computer.
+
+## What you need
+
+- A Redactic workspace and an API key. Create the key in Redactic under Admin, API. It starts
+  with `rk_live_` and is shown once. Every snippet below has `rk_live_...` where your key goes.
+- For every client except the Claude Desktop extension: Node.js 18 or later.
+- The folders in which the file tools may read and write, as full paths. Separate several
+  folders with `:` on macOS and Linux and with `;` on Windows. Inside a JSON file, write each
+  Windows backslash twice.
+
+| System | Folder example | Inside a JSON file |
+|---|---|---|
+| macOS | `/Users/you/Documents/redactic` | `"/Users/you/Documents/redactic"` |
+| Windows | `C:\Users\you\Documents\redactic` | `"C:\\Users\\you\\Documents\\redactic"` |
+| Linux | `/home/you/Documents/redactic` | `"/home/you/Documents/redactic"` |
+
+## Install
+
+The same instructions are on [redactic.eu/developers](https://redactic.eu/developers/#mcp-install).
+
+### Claude Desktop
+
+With the extension: download `redactic-<version>.mcpb` from
+[redactic.eu/developers](https://redactic.eu/developers/#mcp-desktop) and compare its SHA-256
+with the one printed on that page. Open the file, or drag it into Claude Desktop, or choose
+Settings, Extensions, Advanced settings, Install Extension. Claude Desktop asks for the API key,
+which it keeps in the keychain of your system, and for the folders the file tools may use. Claude
+Desktop brings its own Node.js, so nothing else needs to be installed.
+
+With the configuration file, which needs Node.js: in Claude Desktop choose Settings, Developer,
+Edit Config. The file it opens is:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+Add the server, save the file, then quit Claude Desktop completely and open it again.
+
+```json
+{
+  "mcpServers": {
+    "redactic": {
+      "command": "npx",
+      "args": ["-y", "@redactic/mcp"],
+      "env": {
+        "REDACTIC_API_KEY": "rk_live_...",
+        "REDACTIC_ALLOWED_DIRS": "/Users/you/Documents/redactic"
+      }
+    }
+  }
+}
+```
+
+On Windows, the folder line reads:
+
+```json
+"REDACTIC_ALLOWED_DIRS": "C:\\Users\\you\\Documents\\redactic"
+```
+
+### Claude Code
+
+Run this command in a terminal. Keep the options before the name `redactic`: a name that comes
+right after `--env` is read as one more variable and the command fails. Everything after `--` is
+the command that starts the server. With `--scope user` the server is available in all your
+projects.
+
+```bash
+claude mcp add --env REDACTIC_API_KEY=rk_live_... --env REDACTIC_ALLOWED_DIRS="$HOME/Documents/redactic" --transport stdio --scope user redactic -- npx -y @redactic/mcp
+```
+
+On Windows, write the folder as a Windows path:
+
+```bash
+claude mcp add --env REDACTIC_API_KEY=rk_live_... --env REDACTIC_ALLOWED_DIRS="C:\Users\you\Documents\redactic" --transport stdio --scope user redactic -- npx -y @redactic/mcp
+```
+
+A team can share the server in the `.mcp.json` file of a project and keep the key out of it.
+Each person sets `REDACTIC_API_KEY` in their own environment, and Claude Code reads it:
+
+```json
+{
+  "mcpServers": {
+    "redactic": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@redactic/mcp"],
+      "env": {
+        "REDACTIC_API_KEY": "${REDACTIC_API_KEY}",
+        "REDACTIC_ALLOWED_DIRS": "${REDACTIC_ALLOWED_DIRS}"
+      }
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add the server to `~/.gemini/settings.json` for all projects, or to `.gemini/settings.json` in
+one project.
+
+Write the key in the `env` block. Gemini CLI removes from the environment it passes to a server
+every variable whose name contains KEY, TOKEN or SECRET, so a key set only in your shell does not
+reach the server.
+
+```json
+{
+  "mcpServers": {
+    "redactic": {
+      "command": "npx",
+      "args": ["-y", "@redactic/mcp"],
+      "env": {
+        "REDACTIC_API_KEY": "rk_live_...",
+        "REDACTIC_ALLOWED_DIRS": "/home/you/Documents/redactic"
+      }
+    }
+  }
+}
+```
+
+On Windows, the folder line reads:
+
+```json
+"REDACTIC_ALLOWED_DIRS": "C:\\Users\\you\\Documents\\redactic"
+```
+
+### Cursor
+
+Add the server to `~/.cursor/mcp.json` for all projects, or to `.cursor/mcp.json` in one
+project. Cursor can read the key from your environment with `${env:REDACTIC_API_KEY}`.
+
+```json
+{
+  "mcpServers": {
+    "redactic": {
+      "command": "npx",
+      "args": ["-y", "@redactic/mcp"],
+      "env": {
+        "REDACTIC_API_KEY": "${env:REDACTIC_API_KEY}",
+        "REDACTIC_ALLOWED_DIRS": "/Users/you/Documents/redactic"
+      }
+    }
+  }
+}
+```
+
+The [developers page](https://redactic.eu/developers/#mcp-cursor) also has an "Add to Cursor"
+link. It fills in the server with placeholder values: replace the key and the folder before you
+save.
+
+### ChatGPT, Microsoft 365 Copilot and claude.ai
+
+This server runs on your computer, so an assistant in the browser cannot use it. ChatGPT and
+Microsoft 365 Copilot connect to remote MCP servers. A remote Redactic server is in preparation.
+
+A file that you upload into a web chat reaches the model as it is. Mask it in Redactic first,
+then upload the masked copy.
+
+## Settings
+
+| Variable | Meaning |
+|---|---|
+| `REDACTIC_API_KEY` | Your API key. Required. |
+| `REDACTIC_ALLOWED_DIRS` | The folders in which the file tools may read and write. Separate several folders with `:` on macOS and Linux and with `;` on Windows. Folders can also be given as command line arguments after the name of the server, one argument each; the Claude Desktop extension passes them this way. Without any folder the file tools answer with the instruction to set one. |
+| `REDACTIC_REGIONS` | Default countries of your documents, for example `IT,DE` (at most four). Without it Redactic detects the country. |
+| `REDACTIC_LANGUAGE` | Default language hint, for example `it`. |
+| `REDACTIC_DETECTION_MODE` | Default detection mode: `accurate` or `fast`. |
+| `REDACTIC_RESTORE_INLINE` | Set to `1` to receive restored text in the conversation. The model then reads the original values. |
+| `REDACTIC_API_URL` | Address of the API, for test environments. |
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `mask_text` | Masks a text and returns the masked text with a `session_id`. Pass the same `session_id` again and each person keeps the same label for the whole conversation. |
+| `restore_text` | Puts the values back into a text with labels and writes the result to a new file. It returns the path of the file. |
+| `mask_file` | Masks a file and saves `<name> (masked)` next to the original. It returns a `session_id` for `restore_file`. |
+| `restore_file` | Puts the values back into a masked text, Word or Excel file and saves `<name> (restored)`. It works on your computer and does not call the API. |
+| `redact_file` | Blacks out a PDF or an image for good and saves `<name> (redacted)` with its certificate. |
+| `check_file` | Checks a PDF or Word file for hidden data: text under shapes, metadata, older revisions, comments, attachments. |
+| `get_usage` | Returns the usage of the month and the limits of the workspace. |
+
+Every masking tool accepts `detection_mode`: `accurate` (the default) takes a second look at
+places, addresses and organisations, and `fast` skips it and answers sooner.
+
+## How your data is handled
+
+- A text is processed in memory on Redactic servers in the EU and is gone when the answer is sent.
+- A file is deleted from the Redactic servers as soon as the server has saved the result on your
+  computer.
+- The restore map is kept in the memory of this server for eight hours after its last use. It is
+  never written to disk, never logged and never part of a tool result. When the server stops, the
+  map is gone, so restore what you need before you close your MCP client.
+- `restore_text` writes to a file and returns its path, so the original values stay out of the
+  conversation.
+- No tool overwrites a file. A new file gets a new name, with a number when the name is taken.
+- A masked PDF cannot be restored. Keep the original PDF when you may need its values again.
+
+## Limits
+
+One document is processed at a time for each API key. When Redactic is busy the server waits and
+tries again for up to a minute, then tells you when to retry. The monthly allowance is the one of
+your Redactic plan; `get_usage` shows where you stand.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run build:mcpb
+```
+
+The tests run against a fake API on localhost and need no key. `npm run build:mcpb` builds
+`dist/redactic-<version>.mcpb` and prints its SHA-256. [RELEASE.md](RELEASE.md) lists the steps of
+a release.
+
+## Licence
+
+MIT, see [LICENSE](LICENSE).

package/manifest.json

@@ -0,0 +1,107 @@
+{
+  "manifest_version": "0.3",
+  "name": "redactic",
+  "display_name": "Redactic",
+  "version": "0.1.0",
+  "description": "Mask, restore and black out personal data in text and files.",
+  "long_description": "Redactic finds names, addresses, account numbers and national identifiers in text and documents and replaces them with labels, so an AI model can work on the content. The map that restores the values stays in this extension, on your computer. Detection runs on Redactic servers in the European Union.",
+  "author": {
+    "name": "Redactic",
+    "url": "https://redactic.eu"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/redactic/redactic-mcp"
+  },
+  "homepage": "https://redactic.eu/ai-assistants/",
+  "documentation": "https://redactic.eu/developers/#mcp",
+  "support": "https://github.com/redactic/redactic-mcp/issues",
+  "icon": "icon.png",
+  "server": {
+    "type": "node",
+    "entry_point": "src/index.js",
+    "mcp_config": {
+      "command": "node",
+      "args": [
+        "${__dirname}/src/index.js",
+        "${user_config.allowed_dirs}"
+      ],
+      "env": {
+        "REDACTIC_API_KEY": "${user_config.api_key}",
+        "REDACTIC_REGIONS": "${user_config.regions}"
+      }
+    }
+  },
+  "user_config": {
+    "api_key": {
+      "type": "string",
+      "title": "Redactic API key",
+      "description": "Create a key in Redactic under Admin, API. It starts with rk_live_.",
+      "sensitive": true,
+      "required": true
+    },
+    "allowed_dirs": {
+      "type": "directory",
+      "title": "Folders for files",
+      "description": "The folders in which Redactic may read your files and save the results.",
+      "multiple": true,
+      "required": false
+    },
+    "regions": {
+      "type": "string",
+      "title": "Countries of your documents",
+      "description": "Up to four country codes separated by commas, for example IT,DE. Leave empty to let Redactic detect the country.",
+      "required": false,
+      "default": ""
+    }
+  },
+  "tools": [
+    {
+      "name": "mask_text",
+      "description": "Mask the personal data of a text."
+    },
+    {
+      "name": "restore_text",
+      "description": "Put the original values back into a text, into a new file."
+    },
+    {
+      "name": "mask_file",
+      "description": "Mask the personal data of a file."
+    },
+    {
+      "name": "restore_file",
+      "description": "Put the original values back into a masked text, Word or Excel file."
+    },
+    {
+      "name": "redact_file",
+      "description": "Black out a PDF or an image for good."
+    },
+    {
+      "name": "check_file",
+      "description": "Check a PDF or Word file for hidden data."
+    },
+    {
+      "name": "get_usage",
+      "description": "Usage of the month and limits."
+    }
+  ],
+  "compatibility": {
+    "platforms": [
+      "darwin",
+      "win32"
+    ],
+    "runtimes": {
+      "node": ">=18.0.0"
+    }
+  },
+  "keywords": [
+    "redaction",
+    "pii",
+    "privacy",
+    "gdpr"
+  ],
+  "license": "MIT",
+  "privacy_policies": [
+    "https://redactic.eu/privacy-policy/"
+  ]
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@redactic/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "mcpName": "eu.redactic/mcp",
+  "description": "MCP server for Redactic (redactic.eu): mask, restore and black out personal data in text and files from Claude and other MCP clients.",
+  "type": "module",
+  "bin": {
+    "redactic-mcp": "src/index.js"
+  },
+  "main": "src/server.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "manifest.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "build:mcpb": "node scripts/build-mcpb.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "redaction",
+    "pii",
+    "anonymization",
+    "gdpr",
+    "redactic"
+  ],
+  "homepage": "https://redactic.eu/ai-assistants/",
+  "bugs": {
+    "url": "https://github.com/redactic/redactic-mcp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/redactic/redactic-mcp.git"
+  },
+  "author": "Redactic (https://redactic.eu)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.0",
+    "fflate": "^0.8.2",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@anthropic-ai/mcpb": "2.1.2"
+  }
+}

package/src/api.js

@@ -0,0 +1,118 @@
+// Thin HTTP client of the Redactic API. No detection logic lives here.
+//
+// A 429 (rate_limited, busy, job_in_progress) is retried after the seconds of Retry-After, for
+// at most RETRY_BUDGET_MS in total; then the error goes back to the tool. Nothing a request or
+// an answer carries is ever logged.
+import { RETRY_BUDGET_MS, VERSION } from './config.js';
+
+export class ApiError extends Error {
+  constructor(status, code, message, extra = {}) {
+    super(message || code);
+    this.status = status;
+    this.code = code;
+    this.retryAfter = extra.retryAfter;
+    this.details = extra.details || {};
+  }
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export class RedacticApi {
+  constructor({ apiKey, apiUrl, fetchImpl = fetch, sleepImpl = sleep, retryBudgetMs = RETRY_BUDGET_MS }) {
+    this.apiKey = apiKey;
+    this.apiUrl = apiUrl;
+    this.fetch = fetchImpl;
+    this.sleep = sleepImpl;
+    this.retryBudgetMs = retryBudgetMs;
+  }
+
+  async request(method, route, { json, form, accept, raw = false, retry = true } = {}) {
+    if (!this.apiKey) {
+      throw new ApiError(0, 'missing_key', 'REDACTIC_API_KEY is not set. Create a key in Redactic under Admin, API, '
+        + 'and add it to the configuration of this MCP server.');
+    }
+    let waited = 0;
+    for (;;) {
+      const headers = { Authorization: `Bearer ${this.apiKey}`, 'User-Agent': `redactic-mcp/${VERSION}` };
+      let body;
+      if (json !== undefined) { headers['Content-Type'] = 'application/json'; body = JSON.stringify(json); }
+      if (form !== undefined) body = form();          // a fresh FormData for each attempt
+      if (accept) headers.Accept = accept;
+      let response;
+      try {
+        response = await this.fetch(this.apiUrl + route, { method, headers, body });
+      } catch {
+        throw new ApiError(0, 'network_error', 'The Redactic API could not be reached. Check the network connection.');
+      }
+      if (response.ok) return raw ? response : response.json();
+      const error = await toError(response);
+      if (response.status === 429 && retry) {
+        const pause = Math.max(1, error.retryAfter || 2) * 1000;
+        if (waited + pause <= this.retryBudgetMs) {
+          waited += pause;
+          await this.sleep(pause);
+          continue;
+        }
+      }
+      throw error;
+    }
+  }
+
+  maskText(payload) { return this.request('POST', '/text/mask', { json: payload }); }
+
+  submitDocument({ bytes, name, options }) {
+    return this.request('POST', '/documents', {
+      form: () => {
+        const form = new FormData();
+        form.append('file', new Blob([bytes]), name);
+        form.append('options', new Blob([JSON.stringify(options)], { type: 'application/json' }));
+        return form;
+      },
+    });
+  }
+
+  document(id) { return this.request('GET', `/documents/${id}`); }
+
+  async download(id, kind) {
+    const response = await this.request('GET', `/documents/${id}/${kind}`, { raw: true });
+    return {
+      bytes: new Uint8Array(await response.arrayBuffer()),
+      name: fileNameOf(response.headers.get('content-disposition')),
+      contentType: response.headers.get('content-type') || '',
+    };
+  }
+
+  documentMap(id) { return this.request('GET', `/documents/${id}/map`); }
+
+  deleteDocument(id) { return this.request('DELETE', `/documents/${id}`, { retry: false }); }
+
+  check({ bytes, name }) {
+    return this.request('POST', '/check', {
+      form: () => { const form = new FormData(); form.append('file', new Blob([bytes]), name); return form; },
+    });
+  }
+
+  usage() { return this.request('GET', '/usage'); }
+}
+
+async function toError(response) {
+  let code = 'http_' + response.status;
+  let message = `The Redactic API answered ${response.status}.`;
+  let details = {};
+  try {
+    const body = await response.json();
+    if (body && body.error && typeof body.error.code === 'string') {
+      ({ code, message, ...details } = body.error);
+    }
+  } catch { /* not JSON: keep the generic message */ }
+  const retryAfter = Number.parseInt(response.headers.get('retry-after') || '', 10);
+  return new ApiError(response.status, code, message, { retryAfter: Number.isFinite(retryAfter) ? retryAfter : undefined, details });
+}
+
+export function fileNameOf(disposition) {
+  if (!disposition) return undefined;
+  const star = /filename\*=(?:UTF-8'')?([^;]+)/i.exec(disposition);
+  if (star) { try { return decodeURIComponent(star[1].trim().replace(/^"|"$/g, '')); } catch { /* fall through */ } }
+  const plain = /filename="?([^";]+)"?/i.exec(disposition);
+  return plain ? plain[1].trim() : undefined;
+}

package/src/config.js

@@ -0,0 +1,47 @@
+// Configuration of the server, read once from the environment and the command line.
+import path from 'node:path';
+
+export const VERSION = '0.1.0';
+export const DEFAULT_API_URL = 'https://redactic.eu/api/v1';
+export const SESSION_TTL_MS = 8 * 60 * 60 * 1000;   // a restore map lives 8 hours after its last use
+export const RETRY_BUDGET_MS = 60 * 1000;           // how long a 429 is retried before the tool answers
+export const POLL_BUDGET_MS = 90 * 60 * 1000;       // how long a document is waited for
+
+// Claude Desktop leaves `${user_config.x}` as it is when the user left that setting empty.
+const PLACEHOLDER = /^\$\{[^}]+\}$/;
+
+function clean(value) {
+  const text = (value || '').trim();
+  return PLACEHOLDER.test(text) ? '' : text;
+}
+
+/**
+ * The allowed folders, absolute and without duplicates. `fromEnv` is REDACTIC_ALLOWED_DIRS
+ * (several folders separated by the path delimiter of the system: ":" or ";" on Windows), `fromArgs`
+ * the command line arguments, one folder each: the Claude Desktop extension passes the folders
+ * chosen in its settings this way. `p` is `path` or, in tests, `path.win32` / `path.posix`.
+ */
+export function allowedDirsFrom(fromEnv, fromArgs = [], p = path) {
+  const candidates = [...clean(fromEnv).split(p.delimiter), ...fromArgs];
+  const dirs = [];
+  for (const candidate of candidates) {
+    const dir = clean(candidate);
+    if (!dir) continue;
+    const resolved = p.resolve(dir);
+    if (!dirs.includes(resolved)) dirs.push(resolved);
+  }
+  return dirs;
+}
+
+export function readConfig(env = process.env, argv = []) {
+  const mode = clean(env.REDACTIC_DETECTION_MODE);
+  return {
+    apiKey: clean(env.REDACTIC_API_KEY),
+    apiUrl: (clean(env.REDACTIC_API_URL) || DEFAULT_API_URL).replace(/\/+$/, ''),
+    allowedDirs: allowedDirsFrom(env.REDACTIC_ALLOWED_DIRS, argv),
+    regions: clean(env.REDACTIC_REGIONS).split(/[\s,;]+/).map((r) => r.trim().toUpperCase()).filter(Boolean),
+    language: clean(env.REDACTIC_LANGUAGE) || undefined,
+    detectionMode: mode === 'fast' || mode === 'accurate' ? mode : undefined,
+    restoreInline: clean(env.REDACTIC_RESTORE_INLINE) === '1',
+  };
+}

package/src/index.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// Entry point: the server on stdio. stdout belongs to the protocol; nothing else is written to it.
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readConfig } from './config.js';
+import { createServer } from './server.js';
+
+// Every command line argument is an allowed folder (the Claude Desktop extension passes them so).
+const server = createServer(readConfig(process.env, process.argv.slice(2)));
+await server.connect(new StdioServerTransport());

package/src/paths.js

@@ -0,0 +1,72 @@
+// Which files the tools may touch, and how a new file is named.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const HOW_TO = 'In the Redactic extension of Claude Desktop, choose the folders under Folders for files in its settings. '
+  + 'In other clients, set REDACTIC_ALLOWED_DIRS in the configuration of this MCP server to the folders the file tools may use '
+  + `(several folders are separated by "${path.delimiter}"), then restart the client.`;
+
+export function requireDirs(allowedDirs) {
+  if (!allowedDirs.length) throw new Error('The file tools are not set up yet. ' + HOW_TO);
+}
+
+async function real(target) {
+  try { return await fs.realpath(target); } catch { return null; }
+}
+
+/**
+ * Whether `target` is `dir` or below it. Both are absolute real paths. `p` is `path` or, in tests,
+ * `path.win32`: there the comparison ignores case, a path on another drive or share is outside, and
+ * `C:\data-old` is outside `C:\data`.
+ */
+export function inside(dir, target, p = path) {
+  const relative = p.relative(dir, target);
+  if (relative === '') return true;
+  const first = relative.split(p.sep)[0];
+  return first !== '..' && !p.isAbsolute(relative);
+}
+
+/** The real path of an existing file inside an allowed folder. Symbolic links are followed first. */
+export async function allowedFile(file, allowedDirs) {
+  requireDirs(allowedDirs);
+  if (typeof file !== 'string' || !path.isAbsolute(file)) throw new Error('Give the full path of the file.');
+  const target = await real(file);
+  if (!target) throw new Error('This file does not exist.');
+  for (const dir of allowedDirs) {
+    const root = await real(dir);
+    if (root && inside(root, target)) {
+      const stat = await fs.stat(target);
+      if (!stat.isFile()) throw new Error('This path is not a file.');
+      return target;
+    }
+  }
+  throw new Error('This file is outside the folders this MCP server may use. ' + HOW_TO);
+}
+
+/** `<name> (<tag>)<ext>` in `dir`, with a number when that name is taken: nothing is overwritten. */
+export async function writeNew(dir, baseName, tag, extension, bytes) {
+  for (let index = 1; index < 1000; index += 1) {
+    const suffix = index === 1 ? '' : ` ${index}`;
+    const target = path.join(dir, `${baseName} (${tag}${suffix})${extension}`);
+    try {
+      await fs.writeFile(target, bytes, { flag: 'wx' });
+      return target;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+    }
+  }
+  throw new Error('Could not find a free file name.');
+}
+
+/** An output path the caller chose: inside an allowed folder and not existing yet. */
+export async function allowedNewPath(file, allowedDirs) {
+  requireDirs(allowedDirs);
+  if (typeof file !== 'string' || !path.isAbsolute(file)) throw new Error('Give the full path of the output file.');
+  const parent = await real(path.dirname(file));
+  if (!parent) throw new Error('The folder of the output file does not exist.');
+  for (const dir of allowedDirs) {
+    const root = await real(dir);
+    if (root && inside(root, parent)) return path.join(parent, path.basename(file));
+  }
+  throw new Error('The output file is outside the folders this MCP server may use. ' + HOW_TO);
+}

package/src/restore.js

@@ -0,0 +1,59 @@
+// Putting the values back, on this computer. Nothing here calls the API.
+import path from 'node:path';
+import { strFromU8, strToU8, unzipSync, zipSync } from 'fflate';
+import { LABEL } from './sessions.js';
+
+export const TEXT_EXTENSIONS = new Set(['.txt', '.md', '.markdown', '.rst', '.csv', '.json', '.xml', '.html', '.htm']);
+export const PACKAGE_EXTENSIONS = new Set(['.docx', '.xlsx']);
+
+/** Replaces every label of `text` that the map knows. Returns the text and what was (not) found. */
+export function restoreText(text, map, encode = (value) => value) {
+  let replaced = 0;
+  const unknown = new Set();
+  const out = text.replace(LABEL, (label) => {
+    if (map.has(label)) { replaced += 1; return encode(map.get(label)); }
+    unknown.add(label);
+    return label;
+  });
+  return { text: out, replaced, unknown: unknown.size };
+}
+
+const xmlEscape = (value) => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+/** A masked .docx or .xlsx with its values back: the labels are replaced inside the XML parts. */
+export function restorePackage(bytes, map) {
+  const files = unzipSync(bytes);
+  let replaced = 0;
+  let unknown = 0;
+  for (const name of Object.keys(files)) {
+    if (!/\.(xml|rels)$/i.test(name)) continue;
+    const xml = strFromU8(files[name]);
+    if (!xml.includes('⟦')) continue;
+    const result = restoreText(xml, map, xmlEscape);
+    replaced += result.replaced;
+    unknown += result.unknown;
+    files[name] = strToU8(result.text);
+  }
+  // [Content_Types].xml first and stored, as Office writes it.
+  const ordered = {};
+  for (const name of Object.keys(files).sort((a, b) => (a === '[Content_Types].xml' ? -1 : b === '[Content_Types].xml' ? 1 : 0))) {
+    ordered[name] = files[name];
+  }
+  return { bytes: zipSync(ordered, { level: 6 }), replaced, unknown };
+}
+
+export function restoreFile(bytes, extension, map) {
+  const ext = extension.toLowerCase();
+  if (TEXT_EXTENSIONS.has(ext)) {
+    const result = restoreText(new TextDecoder('utf-8').decode(bytes), map);
+    return { bytes: new TextEncoder().encode(result.text), replaced: result.replaced, unknown: result.unknown };
+  }
+  if (PACKAGE_EXTENSIONS.has(ext)) return restorePackage(bytes, map);
+  if (ext === '.pdf') {
+    throw new Error('A masked PDF cannot be restored. Keep the original PDF when you may need its values again. '
+      + 'Text, Word and Excel files can be restored.');
+  }
+  throw new Error(`Files of type ${ext || '(none)'} cannot be restored. Text, Word and Excel files can.`);
+}
+
+export const extensionOf = (file) => path.extname(file).toLowerCase();

package/src/server.js

@@ -0,0 +1,251 @@
+// The MCP server: seven tools over the Redactic API.
+//
+// What reaches the model: masked text, counts, file paths, a session id. What never does: a
+// restore map, and (unless REDACTIC_RESTORE_INLINE=1) restored text.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { ApiError, RedacticApi } from './api.js';
+import { POLL_BUDGET_MS, VERSION } from './config.js';
+import { allowedFile, allowedNewPath, requireDirs, writeNew } from './paths.js';
+import { extensionOf, restoreFile, restoreText } from './restore.js';
+import { SessionStore } from './sessions.js';
+
+const JOB_MESSAGES = {
+  monthly_cap: 'The monthly document limit of the plan has been reached.',
+  doc_too_large: 'The document has more pages than the plan allows for one document.',
+  input_expired: 'The document waited too long for a free slot. Try again.',
+  encrypted_pdf: 'The PDF is protected by a password. Remove the password and try again.',
+  redaction_incomplete: 'The produced file still held a detected value, so it was not delivered.',
+  redaction_unverifiable: 'The produced file could not be checked, so it was not delivered.',
+  ocr_failed: 'A page could not be read.',
+  timeout: 'The document took too long to process.',
+};
+
+const detectionMode = z.enum(['accurate', 'fast']).optional().describe(
+  'How thoroughly the text is read. "accurate" (default) takes a second look at places, addresses and organisations. '
+  + '"fast" skips it and answers sooner.');
+const maskingOptions = {
+  detection_mode: detectionMode,
+  regions: z.array(z.string()).max(4).optional().describe('Countries of the document as ISO codes, for example ["IT","DE"]. Leave out to detect the country.'),
+  language: z.string().optional().describe('Language of the text as a two-letter code, as a hint.'),
+  types: z.array(z.string()).optional().describe('Entity types to mask, for example ["PERSON","IBAN"]. Leave out for all types.'),
+  names: z.array(z.string()).optional().describe('Names that are always masked.'),
+  keep: z.array(z.string()).optional().describe('Values that stay in clear.'),
+};
+
+const text = (value) => ({ content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] });
+const failure = (message) => ({ isError: true, content: [{ type: 'text', text: message }] });
+
+function describe(error) {
+  if (error instanceof ApiError) {
+    if (error.status === 429) {
+      const wait = error.retryAfter ? ` Try again in ${error.retryAfter} seconds.` : ' Try again in a minute.';
+      return `Redactic is busy (${error.code}).${wait}`;
+    }
+    return `${error.message} (${error.code})`;
+  }
+  return error && error.message ? error.message : 'The operation failed.';
+}
+
+export function createServer(config, deps = {}) {
+  const api = deps.api || new RedacticApi(config);
+  const sessions = deps.sessions || new SessionStore();
+  const sleep = deps.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const server = new McpServer({ name: 'redactic', version: VERSION });
+
+  const options = (args) => {
+    const out = {};
+    const mode = args.detection_mode || config.detectionMode;
+    if (mode) out.detection_mode = mode;
+    const regions = args.regions && args.regions.length ? args.regions : config.regions;
+    if (regions && regions.length) out.regions = regions;
+    const language = args.language || config.language;
+    if (language) out.language = language;
+    for (const name of ['types', 'names', 'keep']) if (args[name] && args[name].length) out[name] = args[name];
+    return out;
+  };
+
+  const tool = (name, definition, handler) => server.registerTool(name, definition, async (args) => {
+    try {
+      return await handler(args || {});
+    } catch (error) {
+      return failure(describe(error));
+    }
+  });
+
+  /** Runs one document through the API and always deletes it on the server afterwards. */
+  async function runDocument(file, documentOptions, collect) {
+    const bytes = await fs.readFile(file);
+    const submitted = await api.submitDocument({ bytes, name: path.basename(file), options: documentOptions });
+    try {
+      const started = Date.now();
+      let state = await api.document(submitted.id);
+      while (state.status === 'queued' || state.status === 'processing') {
+        if (Date.now() - started > POLL_BUDGET_MS) throw new Error('The document is still being processed. Try again later.');
+        await sleep(2000);
+        state = await api.document(submitted.id);
+      }
+      if (state.status === 'error') {
+        const code = state.error && state.error.code;
+        throw new Error(`${JOB_MESSAGES[code] || 'The document could not be processed.'} (${code || 'error'})`);
+      }
+      if (!state.file_available) {
+        const code = state.file_error && state.file_error.code;
+        throw new Error(`${JOB_MESSAGES[code] || 'The produced file failed its final check and was not delivered.'} (${code || 'no_file'})`);
+      }
+      return await collect(submitted.id, state);
+    } finally {
+      try { await api.deleteDocument(submitted.id); } catch { /* it expires on its own */ }
+    }
+  }
+
+  tool('mask_text', {
+    title: 'Mask text',
+    description: 'Replaces personal data in a text with labels such as ⟦PERSON_1⟧ and returns the masked text. '
+      + 'The text is sent to Redactic in the EU for detection. The map that restores the values stays in this MCP server '
+      + 'and is never returned. Pass the returned session_id to later calls of the same conversation so that the same '
+      + 'person keeps the same label, and to restore_text. Keep the labels unchanged when you rewrite the text.',
+    inputSchema: {
+      text: z.string().min(1).describe('The text to mask.'),
+      session_id: z.string().optional().describe('The session of an earlier mask_text call, to keep labels consistent.'),
+      ...maskingOptions,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, async (args) => {
+    const session = sessions.open(args.session_id);
+    const answer = await api.maskText({ text: args.text, mode: 'reversible', ...options(args) });
+    const masked = sessions.merge(session, answer.masked_text, answer.map);
+    return text({ masked_text: masked, entities: answer.entities, detection_mode: answer.detection_mode, session_id: session.id });
+  });
+
+  tool('restore_text', {
+    title: 'Restore text',
+    description: 'Puts the original values back into a text that contains labels of a session, and writes the result to a '
+      + 'file. Returns the path of the file, so the original values do not enter the conversation. The work is done on '
+      + 'this computer; nothing is sent to Redactic.',
+    inputSchema: {
+      text: z.string().min(1).describe('The text with labels.'),
+      session_id: z.string().describe('The session_id returned by mask_text.'),
+      output_path: z.string().optional().describe('Full path of the file to write. It must not exist yet. Default: a new file in the first allowed folder.'),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+  }, async (args) => {
+    const session = sessions.open(args.session_id);
+    const result = restoreText(args.text, session.map);
+    if (config.restoreInline) {
+      return text({ restored_text: result.text, replaced: result.replaced, labels_not_found: result.unknown });
+    }
+    const bytes = new TextEncoder().encode(result.text);
+    let written;
+    if (args.output_path) {
+      const target = await allowedNewPath(args.output_path, config.allowedDirs);
+      try {
+        await fs.writeFile(target, bytes, { flag: 'wx' });
+      } catch (error) {
+        if (error.code === 'EEXIST') throw new Error('The output file already exists. Choose another name.');
+        throw error;
+      }
+      written = target;
+    } else {
+      requireDirs(config.allowedDirs);
+      written = await writeNew(config.allowedDirs[0], 'text', 'restored', '.txt', bytes);
+    }
+    return text({ path: written, replaced: result.replaced, labels_not_found: result.unknown });
+  });
+
+  tool('mask_file', {
+    title: 'Mask a file',
+    description: 'Masks the personal data of a file (PDF, Word, Excel, CSV, text, image) and saves the masked copy next to '
+      + 'the original as "<name> (masked)". The file is sent to Redactic in the EU for detection and deleted there once '
+      + 'the copy is saved. Returns the path of the masked copy and a session_id for restore_file. The original file is '
+      + 'not changed.',
+    inputSchema: { path: z.string().describe('Full path of the file.'), ...maskingOptions },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, async (args) => {
+    const file = await allowedFile(args.path, config.allowedDirs);
+    return runDocument(file, { mode: 'mask', reversible: true, ...options(args) }, async (id, state) => {
+      const produced = await api.download(id, 'file');
+      const session = sessions.open();
+      if (state.map_available) sessions.put(session, (await api.documentMap(id)).map);
+      const extension = extensionOf(produced.name || '') || extensionOf(file);
+      const written = await writeNew(path.dirname(file), path.basename(file, path.extname(file)), 'masked', extension, produced.bytes);
+      return text({ path: written, pages: state.pages, entities: state.entities, detection_mode: state.detection_mode, session_id: session.id });
+    });
+  });
+
+  tool('restore_file', {
+    title: 'Restore a file',
+    description: 'Puts the original values back into a masked text, Word (.docx) or Excel (.xlsx) file and saves the result '
+      + 'as "<name> (restored)". The work is done on this computer; nothing is sent to Redactic. A masked PDF cannot be restored.',
+    inputSchema: {
+      path: z.string().describe('Full path of the file that contains labels.'),
+      session_id: z.string().describe('The session_id returned by mask_file or mask_text.'),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+  }, async (args) => {
+    const file = await allowedFile(args.path, config.allowedDirs);
+    const session = sessions.open(args.session_id);
+    const result = restoreFile(await fs.readFile(file), extensionOf(file), session.map);
+    const base = path.basename(file, path.extname(file)).replace(/ \(masked(?: \d+)?\)$/, '');
+    const written = await writeNew(path.dirname(file), base, 'restored', path.extname(file), result.bytes);
+    return text({ path: written, replaced: result.replaced, labels_not_found: result.unknown });
+  });
+
+  tool('redact_file', {
+    title: 'Black out a file',
+    description: 'Removes the personal data of a PDF or an image for good and draws black boxes in its place, then saves '
+      + 'the result as "<name> (redacted)" with its certificate. This cannot be restored. The file is sent to Redactic in '
+      + 'the EU and deleted there once the result is saved. The original file is not changed.',
+    inputSchema: {
+      path: z.string().describe('Full path of the PDF or image.'),
+      blackout_images: z.boolean().optional().describe('Also black out every embedded picture, such as photos, signatures and logos.'),
+      ...maskingOptions,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, async (args) => {
+    const file = await allowedFile(args.path, config.allowedDirs);
+    const documentOptions = { mode: 'blackout', ...options(args) };
+    if (args.blackout_images) documentOptions.blackout_images = true;
+    return runDocument(file, documentOptions, async (id, state) => {
+      const produced = await api.download(id, 'file');
+      const base = path.basename(file, path.extname(file));
+      const dir = path.dirname(file);
+      const result = { path: await writeNew(dir, base, 'redacted', extensionOf(produced.name || '') || extensionOf(file), produced.bytes) };
+      if (state.certificate_available) {
+        const certificate = await api.download(id, 'certificate');
+        result.certificate_path = await writeNew(dir, base, 'certificate', extensionOf(certificate.name || '') || '.pdf', certificate.bytes);
+      }
+      return text({ ...result, pages: state.pages, entities: state.entities, detection_mode: state.detection_mode });
+    });
+  });
+
+  tool('check_file', {
+    title: 'Check a file for hidden data',
+    description: 'Looks inside a PDF or Word file for data that a reader does not see and a recipient can still extract: '
+      + 'text under a covering shape, unapplied redactions, invisible text, document properties, older revisions, '
+      + 'attachments, comments and tracked changes. Excerpts come back masked. The file is sent to Redactic in the EU and '
+      + 'is not stored.',
+    inputSchema: { path: z.string().describe('Full path of the PDF or .docx file.') },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, async (args) => {
+    const file = await allowedFile(args.path, config.allowedDirs);
+    const report = await api.check({ bytes: await fs.readFile(file), name: path.basename(file) });
+    delete report.request_id;
+    return text(report);
+  });
+
+  tool('get_usage', {
+    title: 'Usage of the month',
+    description: 'Returns the plan of the Redactic workspace, the documents and text used this month, and the limits.',
+    inputSchema: {},
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, async () => {
+    const usage = await api.usage();
+    delete usage.request_id;
+    return text(usage);
+  });
+
+  return server;
+}

package/src/sessions.js

@@ -0,0 +1,115 @@
+// Restore maps, in the memory of this process only.
+//
+// A session holds one map {label: value}. It is never written to disk, never logged and never
+// part of a tool result. It expires SESSION_TTL_MS after its last use and with the process.
+//
+// The API numbers the labels of each call from 1, so two calls of one conversation can both
+// use ⟦PERSON_1⟧ for different people. `merge` renumbers the labels of a new call against the
+// session: a value the session already knows keeps its label, a new value gets a free one.
+import { randomUUID } from 'node:crypto';
+import { SESSION_TTL_MS } from './config.js';
+
+export const LABEL = /⟦([A-Z_]+)_(\d+)(?:\.(\d+))?⟧/g;
+
+function parse(label) {
+  const match = /^⟦([A-Z_]+)_(\d+)(?:\.(\d+))?⟧$/.exec(label);
+  return match ? { code: match[1], number: Number(match[2]), variant: match[3] ? Number(match[3]) : 1 } : null;
+}
+
+const format = (code, number, variant) => (variant > 1 ? `⟦${code}_${number}.${variant}⟧` : `⟦${code}_${number}⟧`);
+
+export class SessionStore {
+  constructor({ ttlMs = SESSION_TTL_MS, now = () => Date.now() } = {}) {
+    this.ttlMs = ttlMs;
+    this.now = now;
+    this.sessions = new Map();
+  }
+
+  sweep() {
+    const limit = this.now() - this.ttlMs;
+    for (const [id, session] of this.sessions) if (session.usedAt < limit) this.sessions.delete(id);
+  }
+
+  /** The session of `id`, or a new one when `id` is empty. Throws for an id that is unknown or expired. */
+  open(id) {
+    this.sweep();
+    if (!id) {
+      const session = { id: randomUUID(), map: new Map(), usedAt: this.now() };
+      this.sessions.set(session.id, session);
+      return session;
+    }
+    const session = this.sessions.get(id);
+    if (!session) {
+      throw new Error('This session_id is unknown or has expired. The restore map of a session is kept in memory '
+        + 'for eight hours after its last use and is gone when the MCP server restarts.');
+    }
+    session.usedAt = this.now();
+    return session;
+  }
+
+  /** Adds the map of one API answer to the session and returns the masked text with the session's labels. */
+  merge(session, maskedText, apiMap) {
+    const byValue = new Map();                       // value -> label, of the session
+    const used = new Map();                          // code -> Set of numbers in use
+    const variants = new Map();                      // "CODE_N" -> Set of variants in use
+    const note = (label) => {
+      const p = parse(label);
+      if (!p) return;
+      if (!used.has(p.code)) used.set(p.code, new Set());
+      used.get(p.code).add(p.number);
+      const base = `${p.code}_${p.number}`;
+      if (!variants.has(base)) variants.set(base, new Set());
+      variants.get(base).add(p.variant);
+    };
+    for (const [label, value] of session.map) { byValue.set(value, label); note(label); }
+
+    const groups = new Map();                        // base of the API answer -> [[label, value]]
+    for (const [label, value] of Object.entries(apiMap || {})) {
+      const p = parse(label);
+      if (!p || typeof value !== 'string') continue;
+      const base = `${p.code}_${p.number}`;
+      if (!groups.has(base)) groups.set(base, { code: p.code, entries: [] });
+      groups.get(base).entries.push({ label, value, variant: p.variant });
+    }
+
+    const rename = new Map();                        // label of the API answer -> label of the session
+    for (const group of groups.values()) {
+      group.entries.sort((a, b) => a.variant - b.variant);
+      // The identity is known when the session already holds one of its written forms.
+      const known = group.entries.map((e) => parse(byValue.get(e.value) || '')).find((p) => p && p.code === group.code);
+      let number;
+      if (known) {
+        number = known.number;
+      } else {
+        const taken = used.get(group.code) || new Set();
+        number = 1;
+        while (taken.has(number)) number += 1;
+      }
+      for (const entry of group.entries) {
+        let label = byValue.get(entry.value);
+        const current = label ? parse(label) : null;
+        if (!current || current.code !== group.code || current.number !== number) {
+          const base = `${group.code}_${number}`;
+          const takenVariants = variants.get(base) || new Set();
+          let variant = 1;
+          while (takenVariants.has(variant)) variant += 1;
+          label = format(group.code, number, variant);
+          note(label);
+          session.map.set(label, entry.value);
+          byValue.set(entry.value, label);
+        }
+        rename.set(entry.label, label);
+      }
+    }
+    session.usedAt = this.now();
+    return maskedText.replace(LABEL, (label) => rename.get(label) || label);
+  }
+
+  /** Stores a map as it is (a file has its own session). */
+  put(session, apiMap) {
+    for (const [label, value] of Object.entries(apiMap || {})) {
+      if (parse(label) && typeof value === 'string') session.map.set(label, value);
+    }
+    session.usedAt = this.now();
+  }
+}