@baruchiro/paperless-mcp 0.0.0-test1

package/src/api/types.ts

@@ -0,0 +1,97 @@
+export interface Tag {
+  id: number;
+  slug: string;
+  name: string;
+  color: string;
+  text_color: string;
+  match: string;
+  matching_algorithm: number;
+  is_insensitive: boolean;
+  is_inbox_tag: boolean;
+  document_count: number;
+  owner: number | null;
+  user_can_change: boolean;
+}
+
+export interface PaginationResponse<T> {
+  count: number;
+  next: string | null;
+  previous: string | null;
+  all: number[];
+  results: T[];
+}
+
+export interface GetTagsResponse extends PaginationResponse<Tag> {}
+
+export interface DocumentsResponse extends PaginationResponse<Document> {}
+
+export interface Document {
+  id: number;
+  correspondent: number | null;
+  document_type: number | null;
+  storage_path: string | null;
+  title: string;
+  content: string | null;
+  tags: number[];
+  created: string;
+  created_date: string;
+  modified: string;
+  added: string;
+  deleted_at: string | null;
+  archive_serial_number: string | null;
+  original_file_name: string;
+  archived_file_name: string;
+  owner: number | null;
+  user_can_change: boolean;
+  is_shared_by_requester: boolean;
+  notes: any[];
+  custom_fields: any[];
+  page_count: number;
+  mime_type: string;
+  __search_hit__?: SearchHit;
+}
+
+export interface SearchHit {
+  score: number;
+  highlights: string;
+  note_highlights: string;
+  rank: number;
+}
+
+export interface Correspondent {
+  id: number;
+  slug: string;
+  name: string;
+  match: string;
+  matching_algorithm: number;
+  is_insensitive: boolean;
+  document_count: number;
+  last_correspondence: string;
+  owner: number | null;
+  permissions: any;
+  user_can_change: boolean;
+}
+
+export interface GetCorrespondentsResponse
+  extends PaginationResponse<Correspondent> {}
+
+export interface DocumentType {
+  id: number;
+  slug: string;
+  name: string;
+  match: string;
+  matching_algorithm: number;
+  is_insensitive: boolean;
+  document_count: number;
+  last_correspondence: string;
+  owner: number | null;
+  permissions: any;
+  user_can_change: boolean;
+}
+
+export interface GetDocumentTypesResponse
+  extends PaginationResponse<DocumentType> {}
+
+export interface BulkEditDocumentsResult {
+  result: string;
+}

package/src/api/utils.ts

@@ -0,0 +1,11 @@
+export const headersToObject = (headers: any): Record<string, string> => {
+  if (!headers) return {};
+  if (typeof headers.forEach === "function") {
+    const obj: Record<string, string> = {};
+    headers.forEach((value: string, key: string) => {
+      obj[key] = value;
+    });
+    return obj;
+  }
+  return headers;
+};

package/src/index.ts

@@ -0,0 +1,165 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import express from "express";
+import { PaperlessAPI } from "./api/PaperlessAPI";
+import { registerCorrespondentTools } from "./tools/correspondents";
+import { registerDocumentTools } from "./tools/documents";
+import { registerDocumentTypeTools } from "./tools/documentTypes";
+import { registerTagTools } from "./tools/tags";
+
+// Simple CLI argument parsing
+const args = process.argv.slice(2);
+const useHttp = args.includes("--http");
+let port = 3000;
+const portIndex = args.indexOf("--port");
+if (portIndex !== -1 && args[portIndex + 1]) {
+  const parsed = parseInt(args[portIndex + 1], 10);
+  if (!isNaN(parsed)) port = parsed;
+}
+
+async function main() {
+  let baseUrl: string | undefined;
+  let token: string | undefined;
+
+  if (useHttp) {
+    baseUrl = process.env.PAPERLESS_URL;
+    token = process.env.API_KEY;
+    if (!baseUrl || !token) {
+      console.error(
+        "When using --http, PAPERLESS_URL and API_KEY environment variables must be set."
+      );
+      process.exit(1);
+    }
+  } else {
+    baseUrl = args[0];
+    token = args[1];
+    if (!baseUrl || !token) {
+      console.error(
+        "Usage: paperless-mcp <baseUrl> <token> [--http] [--port <port>]"
+      );
+      console.error(
+        "Example: paperless-mcp http://localhost:8000 your-api-token --http --port 3000"
+      );
+      console.error(
+        "When using --http, PAPERLESS_URL and API_KEY environment variables must be set."
+      );
+      process.exit(1);
+    }
+  }
+
+  // Initialize API client and server once
+  const api = new PaperlessAPI(baseUrl, token);
+  const server = new McpServer({ name: "paperless-ngx", version: "1.0.0" });
+  registerDocumentTools(server, api);
+  registerTagTools(server, api);
+  registerCorrespondentTools(server, api);
+  registerDocumentTypeTools(server, api);
+
+  if (useHttp) {
+    const app = express();
+    app.use(express.json());
+
+    // Store transports for each session
+    const sseTransports: Record<string, SSEServerTransport> = {};
+
+    app.post("/mcp", async (req, res) => {
+      try {
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: undefined,
+        });
+        res.on("close", () => {
+          transport.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+      } catch (error) {
+        console.error("Error handling MCP request:", error);
+        if (!res.headersSent) {
+          res.status(500).json({
+            jsonrpc: "2.0",
+            error: {
+              code: -32603,
+              message: "Internal server error",
+            },
+            id: null,
+          });
+        }
+      }
+    });
+
+    app.get("/mcp", async (req, res) => {
+      res.writeHead(405).end(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          error: {
+            code: -32000,
+            message: "Method not allowed.",
+          },
+          id: null,
+        })
+      );
+    });
+
+    app.delete("/mcp", async (req, res) => {
+      res.writeHead(405).end(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          error: {
+            code: -32000,
+            message: "Method not allowed.",
+          },
+          id: null,
+        })
+      );
+    });
+
+    app.get("/sse", async (req, res) => {
+      console.log("SSE request received");
+      try {
+        const transport = new SSEServerTransport("/messages", res);
+        sseTransports[transport.sessionId] = transport;
+        res.on("close", () => {
+          delete sseTransports[transport.sessionId];
+          transport.close();
+        });
+        await server.connect(transport);
+      } catch (error) {
+        console.error("Error handling SSE request:", error);
+        if (!res.headersSent) {
+          res.status(500).json({
+            jsonrpc: "2.0",
+            error: {
+              code: -32603,
+              message: "Internal server error",
+            },
+            id: null,
+          });
+        }
+      }
+    });
+
+    app.post("/messages", async (req, res) => {
+      const sessionId = req.query.sessionId as string;
+      const transport = sseTransports[sessionId];
+      if (transport) {
+        await transport.handlePostMessage(req, res, req.body);
+      } else {
+        res.status(400).send("No transport found for sessionId");
+      }
+    });
+
+    app.listen(port, () => {
+      console.log(
+        `MCP Stateless Streamable HTTP Server listening on port ${port}`
+      );
+    });
+  } else {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.log("MCP server running with stdio transport");
+  }
+}
+
+main().catch((e) => console.error(e.message));

package/src/tools/correspondents.ts

@@ -0,0 +1,137 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp";
+import { z } from "zod";
+import { errorMiddleware } from "./utils/middlewares";
+import { buildQueryString } from "./utils/queryString";
+
+export function registerCorrespondentTools(server: McpServer, api) {
+  server.tool(
+    "list_correspondents",
+    {
+      page: z.number().optional(),
+      page_size: z.number().optional(),
+      name__icontains: z.string().optional(),
+      name__iendswith: z.string().optional(),
+      name__iexact: z.string().optional(),
+      name__istartswith: z.string().optional(),
+      ordering: z.string().optional(),
+    },
+    errorMiddleware(async (args, extra) => {
+      if (!api) throw new Error("Please configure API connection first");
+      const queryString = buildQueryString(args);
+      const response = await api.request(
+        `/correspondents/${queryString ? `?${queryString}` : ""}`
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(response),
+          },
+        ],
+      };
+    })
+  );
+
+  server.tool(
+    "get_correspondent",
+    { id: z.number() },
+    errorMiddleware(async (args, extra) => {
+      if (!api) throw new Error("Please configure API connection first");
+      const response = await api.request(`/correspondents/${args.id}/`);
+      return {
+        content: [{ type: "text", text: JSON.stringify(response) }],
+      };
+    })
+  );
+
+  server.tool(
+    "create_correspondent",
+    {
+      name: z.string(),
+      match: z.string().optional(),
+      matching_algorithm: z
+        .enum(["any", "all", "exact", "regular expression", "fuzzy"])
+        .optional(),
+    },
+    errorMiddleware(async (args, extra) => {
+      if (!api) throw new Error("Please configure API connection first");
+      const response = await api.createCorrespondent(args);
+      return {
+        content: [{ type: "text", text: JSON.stringify(response) }],
+      };
+    })
+  );
+
+  server.tool(
+    "update_correspondent",
+    {
+      id: z.number(),
+      name: z.string(),
+      match: z.string().optional(),
+      matching_algorithm: z
+        .enum(["any", "all", "exact", "regular expression", "fuzzy"])
+        .optional(),
+    },
+    errorMiddleware(async (args, extra) => {
+      if (!api) throw new Error("Please configure API connection first");
+      const response = await api.request(`/correspondents/${args.id}/`, {
+        method: "PUT",
+        body: JSON.stringify(args),
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(response) }],
+      };
+    })
+  );
+
+  server.tool(
+    "delete_correspondent",
+    { id: z.number() },
+    errorMiddleware(async (args, extra) => {
+      if (!api) throw new Error("Please configure API connection first");
+      await api.request(`/correspondents/${args.id}/`, { method: "DELETE" });
+      return {
+        content: [
+          { type: "text", text: JSON.stringify({ status: "deleted" }) },
+        ],
+      };
+    })
+  );
+
+  server.tool(
+    "bulk_edit_correspondents",
+    {
+      correspondent_ids: z.array(z.number()),
+      operation: z.enum(["set_permissions", "delete"]),
+      owner: z.number().optional(),
+      permissions: z
+        .object({
+          view: z.object({
+            users: z.array(z.number()).optional(),
+            groups: z.array(z.number()).optional(),
+          }),
+          change: z.object({
+            users: z.array(z.number()).optional(),
+            groups: z.array(z.number()).optional(),
+          }),
+        })
+        .optional(),
+      merge: z.boolean().optional(),
+    },
+    errorMiddleware(async (args, extra) => {
+      if (!api) throw new Error("Please configure API connection first");
+      return api.bulkEditObjects(
+        args.correspondent_ids,
+        "correspondents",
+        args.operation,
+        args.operation === "set_permissions"
+          ? {
+              owner: args.owner,
+              permissions: args.permissions,
+              merge: args.merge,
+            }
+          : {}
+      );
+    })
+  );
+}

package/src/tools/documentTypes.ts

@@ -0,0 +1,137 @@
+import { z } from "zod";
+import { errorMiddleware } from "./utils/middlewares";
+import { buildQueryString } from "./utils/queryString";
+
+export function registerDocumentTypeTools(server, api) {
+  server.tool(
+    "list_document_types",
+    "List all document types. IMPORTANT: When a user query may refer to a document type or tag, you should fetch all document types and all tags up front (with a large enough page_size), cache them for the session, and search locally for matches by name or slug before making further API calls. This reduces redundant requests and handles ambiguity between tags and document types efficiently.",
+    {
+      page: z.number().optional(),
+      page_size: z.number().optional(),
+      name__icontains: z.string().optional(),
+      name__iendswith: z.string().optional(),
+      name__iexact: z.string().optional(),
+      name__istartswith: z.string().optional(),
+      ordering: z.string().optional(),
+    },
+    errorMiddleware(async (args: any = {}, extra) => {
+      if (!api) throw new Error("Please configure API connection first");
+      const queryString = buildQueryString(args);
+      const response = await api.request(
+        `/document_types/${queryString ? `?${queryString}` : ""}`
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(response),
+          },
+        ],
+      };
+    })
+  );
+
+  server.tool(
+    "get_document_type",
+    { id: z.number() },
+    errorMiddleware(async (args, extra) => {
+      if (!api) throw new Error("Please configure API connection first");
+      const response = await api.request(`/document_types/${args.id}/`);
+      return {
+        content: [{ type: "text", text: JSON.stringify(response) }],
+      };
+    })
+  );
+
+  server.tool(
+    "create_document_type",
+    {
+      name: z.string(),
+      match: z.string().optional(),
+      matching_algorithm: z
+        .enum(["any", "all", "exact", "regular expression", "fuzzy"])
+        .optional(),
+    },
+    errorMiddleware(async (args, extra) => {
+      if (!api) throw new Error("Please configure API connection first");
+      const response = await api.createDocumentType(args);
+      return {
+        content: [{ type: "text", text: JSON.stringify(response) }],
+      };
+    })
+  );
+
+  server.tool(
+    "update_document_type",
+    {
+      id: z.number(),
+      name: z.string(),
+      match: z.string().optional(),
+      matching_algorithm: z
+        .enum(["any", "all", "exact", "regular expression", "fuzzy"])
+        .optional(),
+    },
+    errorMiddleware(async (args, extra) => {
+      if (!api) throw new Error("Please configure API connection first");
+      const response = await api.request(`/document_types/${args.id}/`, {
+        method: "PUT",
+        body: JSON.stringify(args),
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(response) }],
+      };
+    })
+  );
+
+  server.tool(
+    "delete_document_type",
+    { id: z.number() },
+    errorMiddleware(async (args, extra) => {
+      if (!api) throw new Error("Please configure API connection first");
+      await api.request(`/document_types/${args.id}/`, { method: "DELETE" });
+      return {
+        content: [
+          { type: "text", text: JSON.stringify({ status: "deleted" }) },
+        ],
+      };
+    })
+  );
+
+  server.tool(
+    "bulk_edit_document_types",
+    {
+      document_type_ids: z.array(z.number()),
+      operation: z.enum(["set_permissions", "delete"]),
+      owner: z.number().optional(),
+      permissions: z
+        .object({
+          view: z.object({
+            users: z.array(z.number()).optional(),
+            groups: z.array(z.number()).optional(),
+          }),
+          change: z.object({
+            users: z.array(z.number()).optional(),
+            groups: z.array(z.number()).optional(),
+          }),
+        })
+        .optional(),
+      merge: z.boolean().optional(),
+    },
+    errorMiddleware(async (args, extra) => {
+      if (!api) throw new Error("Please configure API connection first");
+      return api.bulkEditObjects(
+        args.document_type_ids,
+        "document_types",
+        args.operation,
+        args.operation === "set_permissions"
+          ? {
+              owner: args.owner,
+              permissions: args.permissions,
+              merge: args.merge,
+            }
+          : {}
+      );
+    })
+  );
+}