@kjanat/paperless-mcp 1.0.1-dev.1 → 2.0.0

package/README.md

@@ -16,16 +16,16 @@ An MCP (Model Context Protocol) server for interacting with a Paperless-ngx API
 
    ```jsonc
    {
-   	"mcpServers": {
-   		"paperless": {
-   			"command": "bunx", // or npx
-   			"args": [
-   				"@kjanat/paperless-mcp",
-   				"http://your-paperless-instance:8000",
-   				"your-api-token",
-   			],
-   		},
-   	},
+     "mcpServers": {
+       "paperless": {
+         "command": "bunx", // or npx
+         "args": [
+           "@kjanat/paperless-mcp",
+           "http://your-paperless-instance:8000",
+           "your-api-token",
+         ],
+       },
+     },
    }
    ```
 
@@ -66,7 +66,7 @@ Parameters:
 
 ```typescript
 get_document({
-	id: 123,
+  id: 123,
 });
 ```
 
@@ -80,7 +80,7 @@ Parameters:
 
 ```typescript
 search_documents({
-	query: 'invoice 2024',
+  query: "invoice 2024",
 });
 ```
 
@@ -95,8 +95,8 @@ Parameters:
 
 ```typescript
 download_document({
-	id: 123,
-	original: false,
+  id: 123,
+  original: false,
 });
 ```
 
@@ -139,39 +139,39 @@ Examples:
 ```typescript
 // Add a tag to multiple documents
 bulk_edit_documents({
-	documents: [1, 2, 3],
-	method: 'add_tag',
-	tag: 5,
+  documents: [1, 2, 3],
+  method: "add_tag",
+  tag: 5,
 });
 
 // Set correspondent and document type
 bulk_edit_documents({
-	documents: [4, 5],
-	method: 'set_correspondent',
-	correspondent: 2,
+  documents: [4, 5],
+  method: "set_correspondent",
+  correspondent: 2,
 });
 
 // Merge documents
 bulk_edit_documents({
-	documents: [6, 7, 8],
-	method: 'merge',
-	metadata_document_id: 6,
-	delete_originals: true,
+  documents: [6, 7, 8],
+  method: "merge",
+  metadata_document_id: 6,
+  delete_originals: true,
 });
 
 // Split document into parts
 bulk_edit_documents({
-	documents: [9],
-	method: 'split',
-	pages: '[1-2,3-4,5]',
+  documents: [9],
+  method: "split",
+  pages: "[1-2,3-4,5]",
 });
 
 // Modify multiple tags at once
 bulk_edit_documents({
-	documents: [10, 11],
-	method: 'modify_tags',
-	add_tags: [1, 2],
-	remove_tags: [3, 4],
+  documents: [10, 11],
+  method: "modify_tags",
+  add_tags: [1, 2],
+  remove_tags: [3, 4],
 });
 ```
 
@@ -194,14 +194,14 @@ Parameters:
 
 ```typescript
 post_document({
-	file: 'base64_encoded_content',
-	filename: 'invoice.pdf',
-	title: 'January Invoice',
-	created: '2024-01-19',
-	correspondent: 1,
-	document_type: 2,
-	tags: [1, 3],
-	archive_serial_number: '2024-001',
+  file: "base64_encoded_content",
+  filename: "invoice.pdf",
+  title: "January Invoice",
+  created: "2024-01-19",
+  correspondent: 1,
+  document_type: 2,
+  tags: [1, 3],
+  archive_serial_number: "2024-001",
 });
 ```
 
@@ -228,10 +228,10 @@ Parameters:
 
 ```typescript
 create_tag({
-	name: 'Invoice',
-	color: '#ff0000',
-	match: 'invoice',
-	matching_algorithm: 5,
+  name: "Invoice",
+  color: "#ff0000",
+  match: "invoice",
+  matching_algorithm: 5,
 });
 ```
 
@@ -249,9 +249,9 @@ Parameters:
 
 ```typescript
 update_tag({
-	id: 5,
-	name: 'Invoices',
-	color: '#00ff00',
+  id: 5,
+  name: "Invoices",
+  color: "#00ff00",
 });
 ```
 
@@ -265,7 +265,7 @@ Parameters:
 
 ```typescript
 delete_tag({
-	id: 5,
+  id: 5,
 });
 ```
 
@@ -283,8 +283,8 @@ Parameters:
 
 ```typescript
 bulk_edit_tags({
-	tag_ids: [1, 2, 3],
-	operation: 'delete',
+  tag_ids: [1, 2, 3],
+  operation: "delete",
 });
 ```
 
@@ -310,9 +310,9 @@ Parameters:
 
 ```typescript
 create_correspondent({
-	name: 'ACME Corp',
-	match: 'ACME',
-	matching_algorithm: 5,
+  name: "ACME Corp",
+  match: "ACME",
+  matching_algorithm: 5,
 });
 ```
 
@@ -330,8 +330,8 @@ Parameters:
 
 ```typescript
 bulk_edit_correspondents({
-	correspondent_ids: [1, 2],
-	operation: 'delete',
+  correspondent_ids: [1, 2],
+  operation: "delete",
 });
 ```
 
@@ -357,9 +357,9 @@ Parameters:
 
 ```typescript
 create_document_type({
-	name: 'Invoice',
-	match: 'invoice total amount due',
-	matching_algorithm: 1,
+  name: "Invoice",
+  match: "invoice total amount due",
+  matching_algorithm: 1,
 });
 ```
 
@@ -377,8 +377,8 @@ Parameters:
 
 ```typescript
 bulk_edit_document_types({
-	document_type_ids: [1, 2],
-	operation: 'delete',
+  document_type_ids: [1, 2],
+  operation: "delete",
 });
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kjanat/paperless-mcp",
-  "version": "1.0.1-dev.1",
+  "version": "2.0.0",
   "description": "MCP server for interacting with Paperless-ngx document management system.",
   "keywords": [
     "mcp",
@@ -27,10 +27,10 @@
   ],
   "scripts": {
     "bd": "bun build src/index.ts --minify --outdir=dist --target=node --banner='#!/usr/bin/env node'",
-    "fmt": "dprint fmt .",
-    "fmt:check": "dprint check .",
+    "fmt": "dprint fmt",
+    "fmt:check": "dprint check",
     "inspect": "bunx @modelcontextprotocol/inspector bun src/index.ts",
-    "prepack": "bun bd",
+    "prepack": "bun bd && bunx prettier README.md --write",
     "start": "bun src/index.ts",
     "typecheck": "tsgo --noEmit"
   },
@@ -40,7 +40,8 @@
   },
   "devDependencies": {
     "@types/bun": "^1.3.9",
-    "@typescript/native-preview": "^7.0.0-dev.20260220.1",
+    "@typescript/native-preview": "^7.0.0-dev.20260221.1",
+    "dprint": "^0.51.1",
     "typescript": "^5.9.3"
   },
   "optionalDependencies": {

package/src/index.ts

@@ -0,0 +1,144 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+
+import { PaperlessAPI } from './api/paperless-api';
+import { registerCorrespondentTools } from './tools/correspondents';
+import { registerDocumentTools } from './tools/documents';
+import { registerDocumentTypeTools } from './tools/documentTypes';
+import { registerTagTools } from './tools/tags';
+
+// CLI argument parsing
+const args = process.argv.slice(2);
+const useHttp = args.includes('--http');
+
+function parsePort(): number {
+	const portIndex = args.indexOf('--port');
+	if (portIndex !== -1) {
+		const raw = args[portIndex + 1];
+		if (raw == null) {
+			console.warn('--port flag provided without a value, using default 3000');
+			return 3000;
+		}
+		const parsed = parseInt(raw, 10);
+		if (isNaN(parsed)) {
+			console.warn(`--port value "${raw}" is not a valid number, using default 3000`);
+			return 3000;
+		}
+		return parsed;
+	}
+	return 3000;
+}
+
+const port = parsePort();
+
+/** Express request with parsed body attached by express.json() middleware. */
+interface ParsedRequest extends IncomingMessage {
+	body?: unknown;
+}
+
+/** JSON-RPC error response shape. */
+interface JsonRpcError {
+	readonly jsonrpc: '2.0';
+	readonly error: { readonly code: number; readonly message: string };
+	readonly id: null;
+}
+
+function jsonRpcError(code: number, message: string): JsonRpcError {
+	return { jsonrpc: '2.0', error: { code, message }, id: null };
+}
+
+async function main(): Promise<void> {
+	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);
+		}
+	}
+
+	const api = new PaperlessAPI(baseUrl, token);
+
+	/** Create a fresh McpServer with all tools registered. */
+	function createServer(): McpServer {
+		const server = new McpServer({ name: 'paperless-ngx', version: '1.0.0' });
+		registerDocumentTools(server, api);
+		registerTagTools(server, api);
+		registerCorrespondentTools(server, api);
+		registerDocumentTypeTools(server, api);
+		return server;
+	}
+
+	if (useHttp) {
+		const app = createMcpExpressApp({ host: '0.0.0.0' });
+
+		app.post('/mcp', async (req: ParsedRequest, res: ServerResponse) => {
+			try {
+				const transport = new StreamableHTTPServerTransport({
+					sessionIdGenerator: undefined,
+				});
+				res.on('close', () => {
+					void transport.close();
+				});
+				const server = createServer();
+				await server.connect(transport);
+				await transport.handleRequest(req, res, req.body);
+			} catch (error: unknown) {
+				console.error('Error handling MCP request:', error);
+				if (!res.headersSent) {
+					res.writeHead(500, { 'Content-Type': 'application/json' });
+					res.end(JSON.stringify(jsonRpcError(-32603, 'Internal server error')));
+				}
+			}
+		});
+
+		app.get('/mcp', (_req: ParsedRequest, res: ServerResponse) => {
+			res.writeHead(405, { 'Content-Type': 'application/json' });
+			res.end(JSON.stringify(jsonRpcError(-32000, 'Method not allowed.')));
+		});
+
+		app.delete('/mcp', (_req: ParsedRequest, res: ServerResponse) => {
+			res.writeHead(405, { 'Content-Type': 'application/json' });
+			res.end(JSON.stringify(jsonRpcError(-32000, 'Method not allowed.')));
+		});
+
+		app.listen(port, () => {
+			console.log(
+				`MCP Stateless Streamable HTTP Server listening on port ${port}`,
+			);
+		});
+	} else {
+		const server = createServer();
+		const transport = new StdioServerTransport();
+		await server.connect(transport);
+	}
+}
+
+main().catch((e: unknown) => {
+	const message = e instanceof Error ? e.message : String(e);
+	console.error(message);
+});