@orellbuehler/paperless-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orell Bühler
+
+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

@@ -0,0 +1,194 @@
+# paperless-mcp
+
+MCP server for [Paperless-ngx](https://docs.paperless-ngx.com/) that exposes the REST API as tools for AI agents. Includes optional semantic search via local vector embeddings.
+
+## Install
+
+The package is published as [`@orellbuehler/paperless-mcp`](https://www.npmjs.com/package/@orellbuehler/paperless-mcp) and runs directly with `npx` — no clone or build needed:
+
+```bash
+claude mcp add paperless \
+  --env PAPERLESS_URL=https://your-paperless-instance.example.com \
+  --env PAPERLESS_TOKEN=your-api-token \
+  -- npx -y @orellbuehler/paperless-mcp
+```
+
+See [Usage with Claude Code](#usage-with-claude-code) for the equivalent JSON config.
+
+Semantic search is off by default. To enable it, set `EMBEDDINGS_ENABLED=true`; the `better-sqlite3` and `sqlite-vec` native modules are installed automatically as optional dependencies (this requires a build toolchain on your platform). The core document tools work without them.
+
+## Setup (from source)
+
+For local development, clone the repo and build the `dist/` output:
+
+```bash
+npm install
+npm run build
+```
+
+## Usage with Claude Code
+
+1. Get your API token from Paperless-ngx (Settings > Administration, or `POST /api/token/`)
+
+2. Set the environment variables by editing `~/.claude/settings.json`. Using the published package:
+
+```json
+{
+  "mcpServers": {
+    "paperless": {
+      "command": "npx",
+      "args": ["-y", "@orellbuehler/paperless-mcp"],
+      "env": {
+        "PAPERLESS_URL": "https://your-paperless-instance.example.com",
+        "PAPERLESS_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+If you built from source instead, use `"command": "node"` with `"args": ["/path/to/paperless-mcp/dist/index.js"]`. To enable semantic search, add `"EMBEDDINGS_ENABLED": "true"` (and `"OPENAI_API_KEY"` if using the OpenAI embedding provider).
+
+3. Restart Claude Code. The tools will be available immediately.
+
+4. If you enabled semantic search, run `sync_embeddings` to index your documents.
+
+## Updating
+
+The server runs from the compiled `dist/` output, so updating is just rebuild + restart — there's no need to re-run `claude mcp add` (the launch command and path don't change):
+
+```bash
+git pull          # if you track a remote
+npm install       # only if dependencies changed
+npm run build     # recompile src/ -> dist/
+```
+
+Then restart Claude Code (or your MCP client) so it re-spawns the server with the new build. Verify with `claude mcp list` (should show `paperless ✓ connected`) or run `/mcp` inside a session.
+
+To change connection settings (URL, token, embedding provider), edit the `env` block in your config, or re-register the server:
+
+```bash
+claude mcp remove paperless
+claude mcp add paperless --scope user \
+  --env PAPERLESS_URL=http://localhost:8000 \
+  --env PAPERLESS_TOKEN=your-api-token \
+  -- node /path/to/paperless-mcp/dist/index.js
+```
+
+## Available Tools
+
+### Core API Tools
+
+| Category            | Tools                                                                                                                           |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Search              | `search_documents`, `search_autocomplete`                                                                                       |
+| Documents           | `list_documents`, `get_document`, `get_documents`, `download_document`, `update_document`, `delete_document`, `upload_document` |
+| Document details    | `get_document_metadata`, `get_document_suggestions`, `get_document_notes`, `add_document_note`, `delete_document_note`          |
+| Bulk operations     | `bulk_edit_documents`, `get_next_asn`                                                                                           |
+| Correspondents      | `list_correspondents`, `get_correspondent`, `create_correspondent`, `update_correspondent`, `delete_correspondent`              |
+| Document types      | `list_document_types`, `get_document_type`, `create_document_type`, `update_document_type`, `delete_document_type`              |
+| Tags                | `list_tags`, `get_tag`, `create_tag`, `update_tag`, `delete_tag`                                                                |
+| Saved views         | `list_saved_views`, `get_saved_view`, `create_saved_view`, `update_saved_view`                                                  |
+| Storage paths       | `list_storage_paths`, `get_storage_path`, `create_storage_path`, `update_storage_path`                                          |
+| Custom fields       | `list_custom_fields`, `get_custom_field`, `create_custom_field`, `update_custom_field`                                          |
+| Users               | `list_users`, `get_user`, `create_user`, `update_user`                                                                          |
+| Groups              | `list_groups`, `get_group`, `create_group`, `update_group`                                                                      |
+| Paperless workflows | `list_workflows`, `get_workflow`, `create_workflow`, `update_workflow`                                                          |
+| System              | `get_status`, `get_statistics`, `list_tasks`                                                                                    |
+
+> **Note:** `list_documents` and `search_documents` return document metadata only (no OCR text) to keep responses small. Use `get_document` (single) or `get_documents` (batch) to retrieve full content.
+>
+> Saved views, users/groups, and workflows support read + create + update only — no delete tools (use the Paperless web UI to delete). User management covers accounts and group membership; it does not set per-document permissions. Notes support add and delete only (no edit), so there is no note-editing tool.
+
+### Extended Tools
+
+| Category        | Tools                                                                  | Description                                              |
+| --------------- | ---------------------------------------------------------------------- | -------------------------------------------------------- |
+| Semantic search | `semantic_search`, `sync_embeddings`, `embedding_status`               | Vector similarity search using local sqlite-vec database |
+| Content         | `get_document_content`                                                 | Extract OCR'd text content from documents                |
+| Workflows       | `auto_classify_document`, `process_inbox`, `bulk_tag_by_content`       | AI-assisted classification and bulk operations           |
+| Helpers         | `get_documents_by_correspondent`, `monthly_summary`, `upload_from_url` | Convenience tools for common workflows                   |
+
+## Environment Variables
+
+| Variable               | Required        | Description                                                                                                                                                       |
+| ---------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PAPERLESS_URL`        | Yes             | Base URL of your Paperless-ngx instance                                                                                                                           |
+| `PAPERLESS_TOKEN`      | Yes             | API token. In `stdio` mode this is the user's token; in `http` mode it is the admin/indexer token (builds the shared embedding index and gates `sync_embeddings`) |
+| `MCP_TRANSPORT`        | No              | `stdio` (default) or `http`                                                                                                                                       |
+| `PORT`                 | No              | Port for the HTTP server (default: `3001`, http mode only)                                                                                                        |
+| `EMBEDDINGS_ENABLED`   | No              | Set to `true` to enable semantic search tools (default: off)                                                                                                      |
+| `MCP_ALLOWED_ORIGINS`  | No              | Comma-separated `Origin` allowlist for browser clients (http mode). Empty (default) blocks all cross-origin browser requests; use `*` to allow any                |
+| `MCP_ALLOWED_HOSTS`    | No              | Comma-separated `Host` allowlist for DNS-rebinding protection (http mode). Empty (default) disables host validation                                               |
+| `EMBEDDING_PROVIDER`   | No              | `openai` or `ollama` (default: `openai`)                                                                                                                          |
+| `OPENAI_API_KEY`       | If using OpenAI | Required for OpenAI embeddings                                                                                                                                    |
+| `OLLAMA_URL`           | If using Ollama | Ollama server URL (default: `http://localhost:11434`)                                                                                                             |
+| `EMBEDDING_MODEL`      | No              | Model name (defaults per provider)                                                                                                                                |
+| `EMBEDDING_DIMENSIONS` | No              | Vector dimensions (defaults per provider)                                                                                                                         |
+| `PAPERLESS_MCP_DATA`   | No              | Directory for the vector DB (default: `~/.paperless-mcp`)                                                                                                         |
+
+## Transports
+
+The server supports two transports, selected by `MCP_TRANSPORT`.
+
+### stdio (default)
+
+Single-user. The MCP client launches the server as a subprocess and it uses
+`PAPERLESS_TOKEN` for all requests. This is the configuration shown above.
+
+### HTTP (multi-user)
+
+Run the server as a shared HTTP service (e.g. a sidecar next to your Paperless-ngx
+deployment) so other users on your network can connect:
+
+```bash
+MCP_TRANSPORT=http PORT=3001 \
+  PAPERLESS_URL=https://paperless.example.com \
+  PAPERLESS_TOKEN=<admin-token> \
+  node dist/index.js
+```
+
+Clients connect to `http://<host>:3001/mcp` and authenticate with **their own**
+Paperless API token via an `Authorization: Bearer <token>` header (or
+`X-Paperless-Token`). Every Paperless call is made with that token, so each user
+only sees the documents their account permits.
+
+`PAPERLESS_TOKEN` is the admin/indexer token: it builds the shared semantic-search
+index, and the `sync_embeddings` tool is only available to a session using the
+admin token. `semantic_search` results are filtered through the requesting user's
+token, so users never see documents they cannot access.
+
+Non-browser MCP clients (which don't send an `Origin` header) work out of the box.
+Browser-based clients are blocked unless you list their origin in
+`MCP_ALLOWED_ORIGINS`. If the server is reachable on a public hostname, set
+`MCP_ALLOWED_HOSTS` to the expected host(s) for DNS-rebinding protection.
+
+## Run as an HTTP sidecar (Docker Compose)
+
+A `Dockerfile` is included. Add the server as a service next to your existing
+Paperless-ngx compose stack:
+
+```yaml
+paperless-mcp:
+  build: https://github.com/<you>/paperless-mcp.git
+  restart: unless-stopped
+  depends_on:
+    - webserver
+  ports:
+    - 3001:3001
+  volumes:
+    - /mnt/ssd/paperless_ngx/mcp:/data
+  environment:
+    MCP_TRANSPORT: http
+    PORT: 3001
+    PAPERLESS_URL: http://webserver:8000
+    PAPERLESS_TOKEN: <admin-token>
+    PAPERLESS_MCP_DATA: /data
+    EMBEDDINGS_ENABLED: "true"
+    EMBEDDING_PROVIDER: openai
+    OPENAI_API_KEY: <key>
+```
+
+LAN clients connect to `http://<host>:3001/mcp` with their own Paperless API
+token. Run `sync_embeddings` once with the admin token to build the shared
+semantic index.

package/dist/config.js

@@ -0,0 +1,43 @@
+import { PaperlessClient } from "./paperless/client.js";
+const baseUrl = (process.env.PAPERLESS_URL || "").replace(/\/+$/, "");
+const adminToken = process.env.PAPERLESS_TOKEN || "";
+if (!baseUrl || !adminToken) {
+    console.error("PAPERLESS_URL and PAPERLESS_TOKEN environment variables are required");
+    process.exit(1);
+}
+function csv(value) {
+    return (value || "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+export const config = {
+    baseUrl,
+    adminToken,
+    transport: (process.env.MCP_TRANSPORT === "http" ? "http" : "stdio"),
+    port: parseInt(process.env.PORT || "3001", 10),
+    embeddingsEnabled: /^(1|true|yes)$/i.test(process.env.EMBEDDINGS_ENABLED || ""),
+    allowedOrigins: csv(process.env.MCP_ALLOWED_ORIGINS),
+    allowedHosts: csv(process.env.MCP_ALLOWED_HOSTS),
+};
+export const adminClient = new PaperlessClient(baseUrl, adminToken);
+const clientCache = new Map();
+const MAX_CACHE = 100;
+export function clientFor(token) {
+    if (token === adminToken)
+        return adminClient;
+    const existing = clientCache.get(token);
+    if (existing) {
+        clientCache.delete(token);
+        clientCache.set(token, existing);
+        return existing;
+    }
+    const client = new PaperlessClient(baseUrl, token);
+    if (clientCache.size >= MAX_CACHE) {
+        const oldest = clientCache.keys().next().value;
+        if (oldest !== undefined)
+            clientCache.delete(oldest);
+    }
+    clientCache.set(token, client);
+    return client;
+}

package/dist/embeddings.js

@@ -0,0 +1,62 @@
+const EMBEDDING_PROVIDER = (process.env.EMBEDDING_PROVIDER || "openai");
+const EMBEDDING_MODEL = process.env.EMBEDDING_MODEL ||
+    (EMBEDDING_PROVIDER === "openai" ? "text-embedding-3-small" : "nomic-embed-text");
+const EMBEDDING_DIMENSIONS = parseInt(process.env.EMBEDDING_DIMENSIONS || (EMBEDDING_PROVIDER === "openai" ? "1536" : "768"), 10);
+if (isNaN(EMBEDDING_DIMENSIONS) || EMBEDDING_DIMENSIONS <= 0) {
+    console.error("EMBEDDING_DIMENSIONS must be a positive integer");
+    process.exit(1);
+}
+const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
+const OLLAMA_URL = (process.env.OLLAMA_URL || "http://localhost:11434").replace(/\/+$/, "");
+export function getEmbeddingDimensions() {
+    return EMBEDDING_DIMENSIONS;
+}
+export function getProviderInfo() {
+    return { provider: EMBEDDING_PROVIDER, model: EMBEDDING_MODEL, dimensions: EMBEDDING_DIMENSIONS };
+}
+async function embedOpenAI(texts) {
+    if (!OPENAI_API_KEY)
+        throw new Error("OPENAI_API_KEY is required when using OpenAI embeddings");
+    const res = await fetch("https://api.openai.com/v1/embeddings", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${OPENAI_API_KEY}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            model: EMBEDDING_MODEL,
+            input: texts,
+            dimensions: EMBEDDING_DIMENSIONS,
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`OpenAI embedding error: ${res.status} ${body}`);
+    }
+    const data = (await res.json());
+    return data.data.sort((a, b) => a.index - b.index).map((d) => d.embedding);
+}
+async function embedOllama(texts) {
+    const res = await fetch(`${OLLAMA_URL}/api/embed`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ model: EMBEDDING_MODEL, input: texts }),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Ollama embedding error: ${res.status} ${body}`);
+    }
+    const data = (await res.json());
+    return data.embeddings;
+}
+export async function embed(texts) {
+    if (texts.length === 0)
+        return [];
+    if (EMBEDDING_PROVIDER === "ollama")
+        return embedOllama(texts);
+    return embedOpenAI(texts);
+}
+export async function embedSingle(text) {
+    const [result] = await embed([text]);
+    return result;
+}

package/dist/http.js

@@ -0,0 +1,124 @@
+import { createServer as createHttpServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { config, clientFor } from "./config.js";
+import { createServer } from "./server.js";
+export function extractToken(headers) {
+    const auth = headers["authorization"];
+    if (typeof auth === "string" && auth.startsWith("Bearer ")) {
+        const t = auth.slice("Bearer ".length).trim();
+        if (t)
+            return t;
+    }
+    const x = headers["x-paperless-token"];
+    if (typeof x === "string" && x.trim())
+        return x.trim();
+    return null;
+}
+export function originAllowed(origin) {
+    if (!origin)
+        return true; // non-browser clients don't send Origin
+    return config.allowedOrigins.includes("*") || config.allowedOrigins.includes(origin);
+}
+export function hostAllowed(host) {
+    if (config.allowedHosts.length === 0)
+        return true; // host validation disabled
+    if (!host)
+        return false;
+    return config.allowedHosts.includes(host) || config.allowedHosts.includes(host.split(":")[0]);
+}
+function setCors(res, origin) {
+    if (config.allowedOrigins.includes("*")) {
+        res.setHeader("Access-Control-Allow-Origin", "*");
+    }
+    else if (origin && config.allowedOrigins.includes(origin)) {
+        res.setHeader("Access-Control-Allow-Origin", origin);
+        res.setHeader("Vary", "Origin");
+    }
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Paperless-Token, mcp-session-id");
+    res.setHeader("Access-Control-Expose-Headers", "mcp-session-id");
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const c of req)
+        chunks.push(c);
+    if (chunks.length === 0)
+        return undefined;
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+export function startHttpServer() {
+    const transports = new Map();
+    const httpServer = createHttpServer(async (req, res) => {
+        const origin = req.headers.origin;
+        setCors(res, origin);
+        if (req.method === "OPTIONS") {
+            res.writeHead(204).end();
+            return;
+        }
+        if (!hostAllowed(req.headers.host)) {
+            res.writeHead(403, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Host not allowed" }));
+            return;
+        }
+        if (!originAllowed(origin)) {
+            res.writeHead(403, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Origin not allowed" }));
+            return;
+        }
+        const url = new URL(req.url || "/", `http://localhost:${config.port}`);
+        if (url.pathname !== "/mcp") {
+            res.writeHead(404).end();
+            return;
+        }
+        const rawSessionId = req.headers["mcp-session-id"];
+        const sessionId = Array.isArray(rawSessionId) ? rawSessionId[0] : rawSessionId;
+        try {
+            if (sessionId) {
+                const existing = transports.get(sessionId);
+                if (!existing) {
+                    // Unknown/expired session — let the client re-initialize.
+                    res.writeHead(404, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Unknown or expired session" }));
+                    return;
+                }
+                const body = await readBody(req);
+                await existing.handleRequest(req, res, body);
+                return;
+            }
+            // No session id => initialize request: require a token.
+            const token = extractToken(req.headers);
+            if (!token) {
+                res.writeHead(401, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Missing Paperless token (Authorization: Bearer <token>)" }));
+                return;
+            }
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (sid) => {
+                    transports.set(sid, transport);
+                },
+                onsessionclosed: (sid) => {
+                    transports.delete(sid);
+                },
+            });
+            transport.onclose = () => {
+                if (transport.sessionId)
+                    transports.delete(transport.sessionId);
+            };
+            const server = await createServer(clientFor(token));
+            await server.connect(transport);
+            const body = await readBody(req);
+            await transport.handleRequest(req, res, body);
+        }
+        catch (e) {
+            if (!res.headersSent) {
+                res.writeHead(500, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: String(e) }));
+            }
+        }
+    });
+    httpServer.listen(config.port, () => {
+        console.error(`paperless-mcp HTTP server listening on :${config.port}/mcp`);
+    });
+}

package/dist/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { config, adminClient } from "./config.js";
+import { createServer } from "./server.js";
+import { startHttpServer } from "./http.js";
+if (config.transport === "http") {
+    startHttpServer();
+}
+else {
+    const server = await createServer(adminClient);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/paperless/client.js

@@ -0,0 +1,54 @@
+export class PaperlessClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this.token = token;
+    }
+    async fetch(path, options = {}) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            ...options,
+            headers: {
+                Authorization: `Token ${this.token}`,
+                ...(options.body && typeof options.body === "string"
+                    ? { "Content-Type": "application/json" }
+                    : {}),
+                ...options.headers,
+            },
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`${res.status} ${res.statusText}: ${body}`);
+        }
+        if (res.status === 204)
+            return { success: true };
+        return res.json();
+    }
+    async fetchAllPages(path) {
+        const all = [];
+        let page = 1;
+        while (true) {
+            const sep = path.includes("?") ? "&" : "?";
+            const data = (await this.fetch(`${path}${sep}page=${page}&page_size=100`));
+            all.push(...data.results);
+            if (!data.next)
+                break;
+            page++;
+        }
+        return all;
+    }
+    async getDocumentContent(id) {
+        const doc = (await this.fetch(`/api/documents/${id}/`));
+        return doc.content || "";
+    }
+    download(path) {
+        return fetch(`${this.baseUrl}${path}`, { headers: { Authorization: `Token ${this.token}` } });
+    }
+    upload(path, form) {
+        return fetch(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: { Authorization: `Token ${this.token}` },
+            body: form,
+        });
+    }
+}

package/dist/paperless/format.js

@@ -0,0 +1,44 @@
+export function buildQS(params) {
+    const sp = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === null)
+            continue;
+        if (Array.isArray(v)) {
+            if (v.length === 0)
+                continue;
+            if (k === "id__in")
+                sp.set(k, v.join(","));
+            else
+                v.forEach((item) => sp.append(k, String(item)));
+        }
+        else {
+            sp.set(k, String(v));
+        }
+    }
+    const s = sp.toString();
+    return s ? `?${s}` : "";
+}
+export function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+export function err(e) {
+    return { content: [{ type: "text", text: String(e) }], isError: true };
+}
+function omitContent(doc) {
+    if (doc && typeof doc === "object" && "content" in doc) {
+        const { content, ...rest } = doc;
+        return rest;
+    }
+    return doc;
+}
+export function summarizeDocs(data) {
+    if (Array.isArray(data))
+        return data.map(omitContent);
+    if (data && typeof data === "object") {
+        const obj = data;
+        if (Array.isArray(obj.results))
+            return { ...obj, results: obj.results.map(omitContent) };
+        return omitContent(obj);
+    }
+    return data;
+}

package/dist/server.js

@@ -0,0 +1,20 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { config } from "./config.js";
+import { registerCoreTools } from "./tools/core.js";
+import { registerWorkflowTools } from "./tools/workflow.js";
+import { registerHelperTools } from "./tools/helpers.js";
+import { registerUserTools } from "./tools/users.js";
+import { registerAutomationTools } from "./tools/automation.js";
+export async function createServer(client) {
+    const server = new McpServer({ name: "paperless-mcp", version: "1.0.0" });
+    registerCoreTools(server, client);
+    registerWorkflowTools(server, client);
+    registerHelperTools(server, client);
+    registerUserTools(server, client);
+    registerAutomationTools(server, client);
+    if (config.embeddingsEnabled) {
+        const { registerSearchTools } = await import("./tools/search.js");
+        registerSearchTools(server, client);
+    }
+    return server;
+}

package/dist/tools/automation.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { buildQS, ok, err } from "../paperless/format.js";
+const triggersSchema = z
+    .array(z.record(z.unknown()))
+    .optional()
+    .describe("Workflow triggers. Each object: { type: 1=consumption | 2=document added | 3=document updated; " +
+    "sources?: number[] (1=consume folder, 2=api upload, 3=mail fetch); filter_filename?; filter_path?; " +
+    "filter_has_tags?: number[]; filter_has_correspondent?: number; filter_has_document_type?: number; " +
+    "matching_algorithm?: number; match?: string }");
+const actionsSchema = z
+    .array(z.record(z.unknown()))
+    .optional()
+    .describe("Workflow actions. Each object: { type: 1=assignment | 2=removal | 3=email | 4=webhook; " +
+    "assign_title?; assign_tags?: number[]; assign_correspondent?: number; assign_document_type?: number; " +
+    "assign_storage_path?: number; assign_owner?: number; remove_tags?: number[]; email?: object; webhook?: object }");
+export function registerAutomationTools(server, client) {
+    server.tool("list_workflows", "List all Paperless workflows (document automation; replaces the old consumption templates)", {
+        page: z.number().optional(),
+        page_size: z.number().optional(),
+    }, async (params) => {
+        try {
+            return ok(await client.fetch(`/api/workflows/${buildQS(params)}`));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("get_workflow", "Get a single workflow by ID, including its triggers and actions", { id: z.number() }, async ({ id }) => {
+        try {
+            return ok(await client.fetch(`/api/workflows/${id}/`));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("create_workflow", "Create a new workflow with inline triggers and actions", {
+        name: z.string(),
+        order: z.number().optional(),
+        enabled: z.boolean().optional(),
+        triggers: triggersSchema,
+        actions: actionsSchema,
+    }, async (body) => {
+        try {
+            return ok(await client.fetch("/api/workflows/", {
+                method: "POST",
+                body: JSON.stringify(body),
+            }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+    server.tool("update_workflow", "Update an existing workflow (partial update)", {
+        id: z.number(),
+        name: z.string().optional(),
+        order: z.number().optional(),
+        enabled: z.boolean().optional(),
+        triggers: triggersSchema,
+        actions: actionsSchema,
+    }, async ({ id, ...body }) => {
+        try {
+            return ok(await client.fetch(`/api/workflows/${id}/`, {
+                method: "PATCH",
+                body: JSON.stringify(body),
+            }));
+        }
+        catch (e) {
+            return err(e);
+        }
+    });
+}