Add OAuth browser flow with DCR for stdio transport (#22)

## Summary

- Introduces `DwsApiClient` abstraction with pluggable token provider (API key or OAuth)
- Adds OAuth browser flow module (`src/auth/nutrient-oauth.ts`) with PKCE, token caching (`~/.nutrient/credentials.json`), refresh, and Dynamic Client Registration
- When no `NUTRIENT_DWS_API_KEY` is set, the server opens a browser for Nutrient OAuth consent on first tool call (similar to `gh auth login`)
- DCR registers a client automatically at `{AUTH_SERVER_URL}/oauth/register` — no pre-registered client ID needed
- Adds Winston logger with file transport for stdio mode (avoids interfering with MCP protocol on stdout/stderr)
- Adds Github actions setup to run lint and basic tests

## Auth flow

1. If `NUTRIENT_DWS_API_KEY` is set, use the API key directly
2. Otherwise, check for a cached token at `~/.nutrient/credentials.json`
3. If the cached token is valid, return it
4. If expired but a refresh token exists, refresh it
5. If no token or refresh fails, register a client via DCR and start a browser OAuth flow, then cache the token

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `NUTRIENT_DWS_API_KEY` | — | API key (skips OAuth if set) |
| `AUTH_SERVER_URL` | `https://api.nutrient.io` | OAuth server base URL |
| `CLIENT_ID` | — | Override DCR with a specific client ID |
| `DWS_API_BASE_URL` | `https://api.nutrient.io` | DWS API base URL |

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: tomassurin

.github/workflows/tests.yml

@@ -0,0 +1,44 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - '**'
+  pull_request:
+
+concurrency:
+  group: tests-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Lint, Build, Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm exec eslint src tests
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Run tests
+        run: pnpm run test:ci

README.md

@@ -16,20 +16,20 @@ A Model Context Protocol (MCP) server that connects AI assistants to the [Nutrie
 
 Once configured, you (or your AI agent) can process documents through natural language:
 
-**You:** *"Merge report-q1.pdf and report-q2.pdf into a single document"*
-**AI:** *"Done! I've merged both reports into combined-report.pdf (24 pages total)."*
+**You:** _"Merge report-q1.pdf and report-q2.pdf into a single document"_
+**AI:** _"Done! I've merged both reports into combined-report.pdf (24 pages total)."_
 
-**You:** *"Redact all social security numbers and email addresses from application.pdf"*
-**AI:** *"I found and redacted 5 SSNs and 3 email addresses. The redacted version is saved as application-redacted.pdf."*
+**You:** _"Redact all social security numbers and email addresses from application.pdf"_
+**AI:** _"I found and redacted 5 SSNs and 3 email addresses. The redacted version is saved as application-redacted.pdf."_
 
-**You:** *"Digitally sign this contract with a visible signature on page 3"*
-**AI:** *"I've applied a PAdES-compliant digital signature to contract.pdf. The signed document is saved as contract-signed.pdf."*
+**You:** _"Digitally sign this contract with a visible signature on page 3"_
+**AI:** _"I've applied a PAdES-compliant digital signature to contract.pdf. The signed document is saved as contract-signed.pdf."_
 
-**You:** *"Convert this PDF to markdown"*
-**AI:** *"Here's the markdown content extracted from your document..."*
+**You:** _"Convert this PDF to markdown"_
+**AI:** _"Here's the markdown content extracted from your document..."_
 
-**You:** *"OCR this scanned document in German and extract the text"*
-**AI:** *"I've processed the scan with German OCR. Here's the extracted text..."*
+**You:** _"OCR this scanned document in German and extract the text"_
+**AI:** _"I've processed the scan with German OCR. Here's the extracted text..."_
 
 ## Quick Start
 
@@ -57,11 +57,11 @@ Open Settings → Developer → Edit Config, then add:
       "args": ["-y", "@nutrient-sdk/dws-mcp-server"],
       "env": {
         "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE",
-        "SANDBOX_PATH": "/your/sandbox/directory"
+        "SANDBOX_PATH": "/your/sandbox/directory",
         // "C:\\your\\sandbox\\directory" for Windows
-      }
-    }
-  }
+      },
+    },
+  },
 }
 ```
 
@@ -80,13 +80,14 @@ Create `.cursor/mcp.json` in your project root:
       "args": ["-y", "@nutrient-sdk/dws-mcp-server"],
       "env": {
         "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE",
-        "SANDBOX_PATH": "/your/project/documents"
+        "SANDBOX_PATH": "/your/project/documents",
         // "C:\\your\\project\\documents" for Windows
-      }
-    }
-  }
+      },
+    },
+  },
 }
 ```
+
 </details>
 
 <details>
@@ -102,13 +103,14 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
       "args": ["-y", "@nutrient-sdk/dws-mcp-server"],
       "env": {
         "NUTRIENT_DWS_API_KEY": "YOUR_API_KEY_HERE",
-        "SANDBOX_PATH": "/your/sandbox/directory"
+        "SANDBOX_PATH": "/your/sandbox/directory",
         // "C:\\your\\sandbox\\directory" for Windows
-      }
-    }
-  }
+      },
+    },
+  },
 }
 ```
+
 </details>
 
 <details>
@@ -132,6 +134,7 @@ Add to `.vscode/settings.json` in your project:
   }
 }
 ```
+
 </details>
 
 <details>
@@ -142,6 +145,7 @@ Any MCP-compatible client can connect using stdio transport:
 ```bash
 NUTRIENT_DWS_API_KEY=your_key SANDBOX_PATH=/your/path npx @nutrient-sdk/dws-mcp-server
 ```
+
 </details>
 
 ### 3. Restart Your AI Client
@@ -154,26 +158,26 @@ Drop documents into your sandbox directory and start giving instructions!
 
 ## Available Tools
 
-| Tool | Description |
-|------|-------------|
+| 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) |
+| **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)                                                                                                             |
 
 ### Document Processor Capabilities
 
-| Feature | Description |
-|---------|-------------|
-| Document Creation | Merge PDFs, Office docs (DOCX, XLSX, PPTX), and images into a single document |
-| Format Conversion | PDF ↔ DOCX, images (PNG, JPEG, WebP), PDF/A, PDF/UA, HTML, Markdown |
-| Editing | Watermark (text/image), rotate pages, flatten annotations |
-| Security | Redact sensitive data (SSNs, credit cards, emails, etc.), password protection, permission control |
-| Data Extraction | Extract text, tables, or key-value pairs as structured JSON |
-| OCR | Multi-language optical character recognition for scanned documents |
-| Optimization | Compress and linearize PDFs without quality loss |
-| Annotations | Import XFDF annotations, flatten annotations |
-| Digital Signing | PAdES-compliant CMS and CAdES digital signatures (via document_signer tool) |
+| Feature           | Description                                                                                       |
+| ----------------- | ------------------------------------------------------------------------------------------------- |
+| Document Creation | Merge PDFs, Office docs (DOCX, XLSX, PPTX), and images into a single document                     |
+| Format Conversion | PDF ↔ DOCX, images (PNG, JPEG, WebP), PDF/A, PDF/UA, HTML, Markdown                               |
+| Editing           | Watermark (text/image), rotate pages, flatten annotations                                         |
+| Security          | Redact sensitive data (SSNs, credit cards, emails, etc.), password protection, permission control |
+| Data Extraction   | Extract text, tables, or key-value pairs as structured JSON                                       |
+| OCR               | Multi-language optical character recognition for scanned documents                                |
+| Optimization      | Compress and linearize PDFs without quality loss                                                  |
+| Annotations       | Import XFDF annotations, flatten annotations                                                      |
+| Digital Signing   | PAdES-compliant CMS and CAdES digital signatures (via document_signer tool)                       |
 
 ## Use with AI Agent Frameworks
 
@@ -212,6 +216,7 @@ npx @nutrient-sdk/dws-mcp-server
 ```
 
 When sandbox mode is enabled:
+
 - Relative paths resolve relative to the sandbox directory
 - All input file paths are validated to ensure they reside in the sandbox
 - Processed files are saved within the sandbox
@@ -222,25 +227,80 @@ When sandbox mode is enabled:
 
 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.
 
+### Authentication
+
+The server authenticates to the Nutrient DWS API (`https://api.nutrient.io`) using one of:
+
+| 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 |
+
+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 `~/.nutrient/credentials.json` and refreshed automatically.
+
 ### Environment Variables
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `NUTRIENT_DWS_API_KEY` | Yes | Your Nutrient DWS API key ([get one free](https://dashboard.nutrient.io/sign_up/)) |
-| `SANDBOX_PATH` | Recommended | Directory to restrict file operations to |
+| 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)                                      |
+
+\* If omitted, the server uses an OAuth browser flow to authenticate with the Nutrient API.
+
+### Security Note: Token Storage
+
+When using the OAuth browser flow, access tokens and refresh tokens are cached in plaintext at `~/.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.
 
 ## Troubleshooting
 
+### Reset authentication to a clean state
+
+If OAuth authentication stops working, delete the cached token file to start fresh:
+
+```bash
+rm ~/.nutrient/credentials.json
+```
+
+The server will automatically register a new client and open the browser for consent on the next tool call.
+
+### FAQ
+
 **Server not appearing in Claude Desktop?**
+
 - Ensure Node.js 18+ is installed (`node --version`)
 - Check the config file path is correct for your OS
 - Restart Claude Desktop completely (check Task Manager/Activity Monitor)
 
+**Browser doesn't open for OAuth login?**
+
+- This happens in headless or remote environments (SSH, Docker, CI). Set `NUTRIENT_DWS_API_KEY` instead — the server skips the browser flow when an API key is configured.
+- On macOS, ensure a default browser is set in System Settings → Desktop & Dock → Default web browser.
+
+**"Token exchange failed" or "OAuth authorization failed"?**
+
+- Delete `~/.nutrient/credentials.json` and try again.
+- If using a custom `AUTH_SERVER_URL`, verify the server is reachable and its `/oauth/token` endpoint is working.
+
+**"Dynamic client registration failed"?**
+
+- If using a custom `AUTH_SERVER_URL`, verify it is reachable.
+- Ensure the custom auth server supports RFC 7591 Dynamic Client Registration at its `/oauth/register` endpoint.
+
 **"API key invalid" errors?**
+
 - Verify your API key at [dashboard.nutrient.io](https://dashboard.nutrient.io)
 - Ensure the key is set correctly in the `env` section (no extra spaces)
 
+**Token expired but refresh fails?**
+
+- The server automatically refreshes expired tokens using the cached refresh token. If refresh fails (e.g., the refresh token was revoked), delete `~/.nutrient/credentials.json` — the server will re-authenticate via the browser on the next call.
+
 **Files not found?**
+
 - 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

docs/testing.md

@@ -0,0 +1,90 @@
+# DWS MCP Server — Local Testing
+
+This guide covers local testing against both production DWS (`api.nutrient.io`) and local DWS debug builds. Docker/deployment steps are intentionally omitted.
+
+## Prerequisites
+
+- Node.js 18+
+- pnpm
+- Project dependencies installed:
+
+```bash
+pnpm install
+```
+
+## Run Commands
+
+```bash
+pnpm run build && pnpm start
+```
+
+---
+
+## stdio Transport
+
+### With API key
+
+```bash
+export NUTRIENT_DWS_API_KEY=your_dws_api_key
+pnpm run build && pnpm start
+```
+
+### With OAuth browser flow
+
+When no API key is set, the server opens a browser for Nutrient OAuth consent on the first tool call. Tokens are cached at `~/.nutrient/credentials.json`.
+
+```bash
+pnpm run build && pnpm start
+```
+
+To test against a local DWS auth server instead of production:
+
+```bash
+export AUTH_SERVER_URL=http://localhost:4000
+export DWS_API_BASE_URL=http://localhost:4000
+pnpm run build && pnpm start
+```
+
+The OAuth flow will use `{AUTH_SERVER_URL}/oauth/authorize` and `{AUTH_SERVER_URL}/oauth/token`. The `CLIENT_ID` env var can override the default client ID (`nutrient-dws-mcp-server`).
+
+---
+
+## Environment Variable Reference
+
+| Variable               | Default                    | Description                                      |
+|------------------------|----------------------------|--------------------------------------------------|
+| `DWS_API_BASE_URL`    | `https://api.nutrient.io`  | DWS API base URL                                 |
+| `NUTRIENT_DWS_API_KEY`| —                          | DWS API key (optional in OAuth mode)             |
+| `AUTH_SERVER_URL`      | `https://api.nutrient.io`  | Authorization server base URL (for OAuth)        |
+| `CLIENT_ID`           | —                          | OAuth client ID (stdio OAuth flow)               |
+| `SANDBOX_PATH`        | —                          | Filesystem sandbox root                          |
+| `LOG_LEVEL`           | `info`                     | Winston logger level                             |
+| `MCP_LOG_FILE`        | auto (tmpdir)              | Override log file path                           |
+
+---
+
+## MCP Inspector
+
+The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a browser-based tool for interactively testing and debugging MCP servers.
+
+For stdio transport, pass the server as a subprocess directly:
+
+```bash
+npx @modelcontextprotocol/inspector -- npx @nutrient-sdk/dws-mcp-server
+```
+
+Or when developing locally:
+
+```bash
+npx @modelcontextprotocol/inspector -- node dist/index.js
+```
+
+---
+
+## Common Failures
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| Browser doesn't open (stdio OAuth) | Running in headless/CI | Set `NUTRIENT_DWS_API_KEY` instead |
+| Token exchange fails | Auth server misconfigured | Check `AUTH_SERVER_URL` and OAuth endpoints |
+| `NUTRIENT_DWS_API_KEY` errors | API key invalid or expired | Verify at [dashboard.nutrient.io](https://dashboard.nutrient.io) |

package.json

@@ -38,18 +38,24 @@
     "LICENSE"
   ],
   "scripts": {
+    "start": "node dist/index.js",
     "build": "tsc && shx chmod +x dist/index.js",
     "format": "prettier --write .",
     "lint": "eslint .",
     "pretest": "tsc --project tsconfig.test.json --noEmit",
     "test": "vitest run",
+    "test:ci": "vitest run --exclude tests/build-api-examples.test.ts --exclude tests/signing-api-examples.test.ts",
+    "test:integration": "vitest run tests/build-api-examples.test.ts tests/signing-api-examples.test.ts",
     "test:watch": "vitest",
-    "clean": "shx rm -rf dist"
+    "clean": "shx rm -rf dist",
+    "prepublishOnly": "pnpm run build"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
     "axios": "^1.13.2",
     "form-data": "^4.0.5",
+    "open": "^11.0.0",
+    "winston": "^3.19.0",
     "zod": "^3.25.76"
   },
   "devDependencies": {