Add local MCP tool metadata and docs

vladimir-tikhonov-nutrient · vladimir-tikhonov-nutrient · commit 0e18fd2ab478 · 2026-03-23T17:09:53.000+01:00
diff --git a/README.md b/README.md
@@ -33,10 +33,12 @@ Once configured, you (or your AI agent) can process documents through natural la
 
 ## Quick Start
 
-### 1. Get a Nutrient API Key
+### 1. Create a Nutrient Account
 
 Sign up for free at [nutrient.io/api](https://dashboard.nutrient.io/sign_up/).
 
+For local desktop use, the recommended path is to omit `NUTRIENT_DWS_API_KEY` and complete the browser sign-in flow on the first DWS-backed tool call. For CI, headless environments, or scripted setups, create an API key in the dashboard and set `NUTRIENT_DWS_API_KEY`.
+
 ### 2. Configure Your AI Client
 
 Choose your platform and add the configuration:
@@ -56,12 +58,13 @@ Open Settings → Developer → Edit Config, then add:
       "command": "npx",
       "args": ["-y", "@nutrient-sdk/dws-mcp-server"],
       "env": {
-        "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE",
         "SANDBOX_PATH": "/your/sandbox/directory",
         // "C:\\your\\sandbox\\directory" for Windows
-      },
-    },
-  },
+        // Optional for CI or headless usage:
+        // "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE"
+      }
+    }
+  }
 }
 ```
 
@@ -79,12 +82,13 @@ Create `.cursor/mcp.json` in your project root:
       "command": "npx",
       "args": ["-y", "@nutrient-sdk/dws-mcp-server"],
       "env": {
-        "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE",
         "SANDBOX_PATH": "/your/project/documents",
         // "C:\\your\\project\\documents" for Windows
-      },
-    },
-  },
+        // Optional for CI or headless usage:
+        // "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE"
+      }
+    }
+  }
 }
 ```
 
@@ -102,12 +106,13 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
       "command": "npx",
       "args": ["-y", "@nutrient-sdk/dws-mcp-server"],
       "env": {
-        "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE",
         "SANDBOX_PATH": "/your/sandbox/directory",
         // "C:\\your\\sandbox\\directory" for Windows
-      },
-    },
-  },
+        // Optional for CI or headless usage:
+        // "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE"
+      }
+    }
+  }
 }
 ```
 
@@ -118,16 +123,17 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 
 Add to `.vscode/settings.json` in your project:
 
-```json
+```jsonc
 {
   "mcp": {
     "servers": {
       "nutrient-dws": {
         "command": "npx",
         "args": ["-y", "@nutrient-sdk/dws-mcp-server"],
         "env": {
-          "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE",
-          "SANDBOX_PATH": "${workspaceFolder}"
+          "SANDBOX_PATH": "${workspaceFolder}",
+          // Optional for CI or headless usage:
+          // "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE"
         }
       }
     }
@@ -143,6 +149,9 @@ Add to `.vscode/settings.json` in your project:
 Any MCP-compatible client can connect using stdio transport:
 
 ```bash
+SANDBOX_PATH=/your/path npx @nutrient-sdk/dws-mcp-server
+
+# Optional for CI or headless usage:
 NUTRIENT_DWS_API_KEY=your_key SANDBOX_PATH=/your/path npx @nutrient-sdk/dws-mcp-server
 ```
 
@@ -154,16 +163,18 @@ Restart the application to pick up the new MCP server configuration.
 
 ### 4. Start Processing Documents
 
-Drop documents into your sandbox directory and start giving instructions!
+Place documents in your sandbox directory and use explicit file names or paths in prompts. Explicit paths are safer and more reliable than vague file-browsing requests.
 
 ## Available Tools
 
-| Tool                   | Description                                                                                                                                                           |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **document_processor** | All-in-one document processing: merge PDFs, convert formats, apply OCR, watermark, rotate, redact, flatten annotations, extract text/tables/key-value pairs, and more |
-| **document_signer**    | Digitally sign PDFs with PAdES-compliant CMS or CAdES signatures, with customizable visible/invisible signature appearances                                           |
-| **sandbox_file_tree**  | Browse files in the sandbox directory (when sandbox mode is enabled)                                                                                                  |
-| **directory_tree**     | Browse directory contents (when sandbox mode is disabled)                                                                                                             |
+| Tool | Description |
+| ---- | ----------- |
+| `document_processor` | Nutrient DWS document processing tool for conversions, OCR, extraction, watermarking, rotation, annotation flattening, and redaction workflows |
+| `document_signer` | Nutrient DWS signing tool for CMS / PKCS#7 and CAdES signatures with visible or invisible appearance options |
+| `ai_redactor` | Nutrient DWS AI redaction tool for detecting and permanently removing sensitive content such as names, addresses, SSNs, emails, and custom criteria |
+| `check_credits` | Read-only account lookup for current DWS credits and usage. No document content is uploaded |
+| `sandbox_file_tree` | Read-only view of files inside the configured sandbox directory |
+| `directory_tree` | Read-only view of local files when sandbox mode is disabled. Sandbox mode is strongly recommended |
 
 ### Document Processor Capabilities
 
@@ -179,6 +190,32 @@ Drop documents into your sandbox directory and start giving instructions!
 | Annotations       | Import XFDF annotations, flatten annotations                                                      |
 | Digital Signing   | PAdES-compliant CMS and CAdES digital signatures (via document_signer tool)                       |
 
+## Example Prompts
+
+These examples assume your files live inside the configured sandbox and that you use explicit paths.
+
+### HTML -> PDF -> signing
+
+```text
+Convert /path/to/sandbox/invoice.html to PDF and save it as /path/to/sandbox/invoice.pdf.
+```
+
+```text
+Digitally sign /path/to/sandbox/invoice.pdf with a visible signature and save it as /path/to/sandbox/invoice-signed.pdf.
+```
+
+### OCR extraction
+
+```text
+Run OCR on /path/to/sandbox/scanned-contract.pdf, return the extracted text, and save the OCR'd file as /path/to/sandbox/scanned-contract-ocr.pdf.
+```
+
+### Check credits -> process -> inspect output
+
+```text
+Check my Nutrient credits, convert /path/to/sandbox/report.docx to PDF, save it as /path/to/sandbox/report.pdf, and then tell me where the output file was written.
+```
+
 ## Use with AI Agent Frameworks
 
 This MCP server works with any platform that supports the Model Context Protocol:
@@ -215,6 +252,8 @@ export SANDBOX_PATH=/path/to/sandbox/directory
 npx @nutrient-sdk/dws-mcp-server
 ```
 
+Supported CLI flags are `--sandbox <dir>` and `-s <dir>`. Unknown CLI flags fail fast instead of silently disabling sandboxing.
+
 When sandbox mode is enabled:
 
 - Relative paths resolve relative to the sandbox directory
@@ -225,7 +264,7 @@ When sandbox mode is enabled:
 
 ### Output Location
 
-Processed files are saved to a location determined by the AI. To guide output placement, use natural language (e.g., "save the result to `output/result.pdf`") or create an `output` directory in your sandbox.
+Processed files are saved to a location determined by the AI. To guide output placement, use explicit output paths such as `save the result to /path/to/sandbox/output/result.pdf` or create an `output` directory in your sandbox.
 
 ### Authentication
 
@@ -234,27 +273,52 @@ The server authenticates to the Nutrient DWS API (`https://api.nutrient.io`) usi
 | Method | When | Config |
 |--------|------|--------|
 | **API key** | `NUTRIENT_DWS_API_KEY` is set | Static key passed as Bearer token to DWS API |
-| **OAuth browser flow** | No API key set | Opens browser for Nutrient OAuth consent, caches token locally |
+| **OAuth browser flow** | No API key set | Opens browser for Nutrient OAuth consent on the first DWS-backed tool call, caches token locally |
 
-When no API key is configured, the server opens a browser-based OAuth flow on the first tool call (similar to `gh auth login`). Tokens are cached at `$XDG_CONFIG_HOME/nutrient/credentials.json` or `~/.config/nutrient/credentials.json` and refreshed automatically.
+When no API key is configured, the server stays connected and opens a browser-based OAuth flow on the first DWS-backed tool call (similar to `gh auth login`). Tokens are cached at `$XDG_CONFIG_HOME/nutrient/credentials.json` or `~/.config/nutrient/credentials.json` and refreshed automatically.
 
 ### Environment Variables
 
 | Variable               | Required    | Description                                                                                  |
 | ---------------------- | ----------- | -------------------------------------------------------------------------------------------- |
-| `NUTRIENT_DWS_API_KEY` | No*         | Nutrient DWS API key ([get one free](https://dashboard.nutrient.io/sign_up/))                |
-| `SANDBOX_PATH`         | Recommended | Directory to restrict file operations to                                                     |
-| `CLIENT_ID`            | No          | OAuth client ID. Skips DCR and enables token refresh when set                                |
-| `DWS_API_BASE_URL`     | No          | DWS API base URL (default: `https://api.nutrient.io`)                                       |
-| `LOG_LEVEL`            | No          | Winston logger level (`info` default). Logs are written to `MCP_LOG_FILE` in stdio mode      |
-| `MCP_LOG_FILE`         | No          | Override log file path (default: system temp directory)                                      |
+| `NUTRIENT_DWS_API_KEY` | No*         | Nutrient DWS API key ([get one free](https://dashboard.nutrient.io/sign_up/))               |
+| `SANDBOX_PATH`         | Recommended | Directory to restrict file operations to                                                    |
+| `AUTH_SERVER_URL`      | No          | OAuth server base URL (default: `https://api.nutrient.io`)                                 |
+| `CLIENT_ID`            | No          | OAuth client ID. Skips DCR and enables refresh token reuse when set                         |
+| `DWS_API_BASE_URL`     | No          | DWS API base URL (default: `https://api.nutrient.io`)                                      |
+| `LOG_LEVEL`            | No          | Winston logger level (`info` default). Logs are written to `MCP_LOG_FILE` in stdio mode     |
+| `MCP_LOG_FILE`         | No          | Override log file path (default: system temp directory)                                     |
 
 \* If omitted, the server uses an OAuth browser flow to authenticate with the Nutrient API.
 
+## Data Handling
+
+### What Stays Local
+
+- The MCP server process, sandbox enforcement, and file path resolution run on the local machine.
+- `sandbox_file_tree` and `directory_tree` inspect local files only. They do not upload document contents to Nutrient.
+- API keys and OAuth credentials are stored locally on the machine running the MCP server.
+
+### What Gets Sent to Nutrient
+
+- `document_processor`, `document_signer`, and `ai_redactor` send the relevant request metadata and referenced document bytes to the Nutrient DWS API so the requested operation can run.
+- `check_credits` sends an authenticated account lookup but does not upload document files.
+- Processed results are written back to the local output path you request.
+
 ### Security Note: Token Storage
 
 When using the OAuth browser flow, access tokens and refresh tokens are cached in plaintext at `$XDG_CONFIG_HOME/nutrient/credentials.json` or `~/.config/nutrient/credentials.json` (permissions `0600`). This file contains credentials equivalent to your API key. Do not commit it to version control or include it in shared backups.
 
+## Privacy Policy
+
+Nutrient's privacy policy is available at [nutrient.io/legal/privacy](https://www.nutrient.io/legal/privacy/).
+
+## Support
+
+For product or account support, contact Nutrient at [nutrient.io/company/contact](https://www.nutrient.io/company/contact/).
+
+For bugs or feature requests specific to this MCP package, use [GitHub issues](https://github.com/PSPDFKit/nutrient-dws-mcp-server/issues).
+
 ## Troubleshooting
 
 ### Reset authentication to a clean state
@@ -303,7 +367,7 @@ The server will automatically register a new client and open the browser for con
 
 - Check that `SANDBOX_PATH` points to an existing directory
 - Ensure your documents are inside the sandbox directory
-- Use the `sandbox_file_tree` tool to verify visible files
+- Ask the assistant to inspect the configured sandbox, or inspect the sandbox directory directly
 
 ## Contributing
 
diff --git a/src/index.ts b/src/index.ts
@@ -41,7 +41,7 @@ function addToolsToServer(options: {
 
   server.tool(
     'document_processor',
-    `Processes documents using Nutrient DWS Processor API. Reads from and writes to file system or sandbox (if enabled).
+    `Nutrient document processing tool backed by the Nutrient DWS Processor API. Reads input files from the local file system or sandbox (if enabled) and writes results back locally.
 
 Features:
 • Import XFDF annotations
@@ -53,6 +53,13 @@ Features:
 
 Output formats: PDF, PDF/A, images (PNG, JPEG, WebP), JSON extraction, Office (DOCX, XLSX, PPTX)`,
     BuildAPIArgsSchema.shape,
+    {
+      title: 'Nutrient Document Processor',
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true,
+    },
     async ({ instructions, outputPath }) => {
       try {
         return await performBuildCall(instructions, outputPath, apiClient)
@@ -64,7 +71,7 @@ Output formats: PDF, PDF/A, images (PNG, JPEG, WebP), JSON extraction, Office (D
 
   server.tool(
     'document_signer',
-    `Digitally signs PDF files using Nutrient DWS Sign API. Reads from and writes to file system or sandbox (if enabled).
+    `Nutrient PDF signing tool backed by the Nutrient DWS Sign API. Reads input files from the local file system or sandbox (if enabled) and writes signed output back locally.
 
 Signature types:
 • CMS/PKCS#7 (standard digital signatures)
@@ -80,6 +87,13 @@ Positioning:
 • Place on specific page coordinates
 • Use existing signature form fields`,
     SignAPIArgsSchema.shape,
+    {
+      title: 'Nutrient Document Signer',
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true,
+    },
     async ({ filePath, signatureOptions, watermarkImagePath, graphicImagePath, outputPath }) => {
       try {
         return await performSignCall(
@@ -98,7 +112,7 @@ Positioning:
 
   server.tool(
     'ai_redactor',
-    `AI-powered document redaction using Nutrient DWS AI Redaction API. Reads from and writes to file system or sandbox (if enabled).
+    `Nutrient AI redaction tool backed by the Nutrient DWS AI Redaction API. Reads input files from the local file system or sandbox (if enabled) and writes redacted output back locally.
 
 Automatically detects and permanently removes sensitive information from documents using AI analysis.
 Detected content types include:
@@ -110,6 +124,13 @@ Detected content types include:
 
 By default (when neither stage nor apply is set), redactions are detected and immediately applied. Set stage to true to detect and stage redactions without applying them. Set apply to true to apply previously staged redactions.`,
     AiRedactArgsSchema.shape,
+    {
+      title: 'Nutrient AI Redactor',
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true,
+    },
     async ({ filePath, criteria, outputPath, stage, apply }) => {
       try {
         return await performAiRedactCall(filePath, criteria, outputPath, apiClient, stage, apply)
@@ -123,8 +144,17 @@ By default (when neither stage nor apply is set), redactions are detected and im
     'check_credits',
     `Check your Nutrient DWS API credit balance and usage for the current billing period.
 
+This is a read-only account lookup. It does not upload any document content.
+
 Returns: subscription type, total credits, used credits, and remaining credits.`,
     CheckCreditsArgsSchema.shape,
+    {
+      title: 'Nutrient Credit Balance',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
     async () => {
       try {
         return await performCheckCreditsCall(apiClient)
@@ -137,15 +167,29 @@ Returns: subscription type, total credits, used credits, and remaining credits.`
   if (sandboxEnabled) {
     server.tool(
       'sandbox_file_tree',
-      'Returns the file tree of the sandbox directory. It will recurse into subdirectories and return a list of files and directories.',
+      'Browse files already available in the configured sandbox directory. This is a read-only local filesystem operation and does not upload documents to Nutrient.',
       {},
+      {
+        title: 'Nutrient Sandbox Files',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
       async () => performDirectoryTreeCall('.'),
     )
   } else {
     server.tool(
       'directory_tree',
-      'Returns the directory tree of a given path. All paths are resolved relative to root directory.',
+      'Browse local files when sandbox mode is disabled. This is a read-only local filesystem operation, but it can inspect any path visible to the current user. Sandbox mode is strongly recommended.',
       DirectoryTreeArgsSchema.shape,
+      {
+        title: 'Nutrient Directory Tree',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
       async ({ path }) => performDirectoryTreeCall(path),
     )
   }
