@kjanat/paperless-mcp 2.0.1 → 2.1.1

package/README.md

@@ -1,45 +1,72 @@
 # Paperless-ngx MCP Server
 
+[![NPM Version](https://img.shields.io/npm/v/@kjanat/paperless-mcp?logo=npm&labelColor=CB3837&color=black)](https://www.npmjs.com/package/@kjanat/paperless-mcp)
+
 An MCP (Model Context Protocol) server for interacting with a Paperless-ngx API server. This server provides tools for managing documents, tags, correspondents, and document types in your Paperless-ngx instance.
 
 ## Quick Start
 
 ### Installation
 
-1. Install the MCP server (optional):
+1. Get your API token:
+   1. Log into your Paperless-ngx instance
+   2. Click your username in the top right
+   3. Select "My Profile"
+   4. Click the circular arrow button to generate a new token
+
+1. Add it to your MCP client configuration (using env vars):
 
-   ```bash
-   bun install -g @kjanat/paperless-mcp
+   ```jsonc
+   {
+   	"mcpServers": {
+   		"paperless": {
+   			"command": "bunx", // or npx
+   			"args": ["@kjanat/paperless-mcp"],
+   			"env": {
+   				"PAPERLESS_URL": "http://your-paperless-instance:8000",
+   				"PAPERLESS_API_KEY": "your-api-token",
+   			},
+   		},
+   	},
+   }
    ```
 
-1. Add it to your configuration:
+   Or pass them as positional arguments:
 
    ```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",
+   			],
+   		},
+   	},
    }
    ```
 
-1. Get your API token:
-   1. Log into your Paperless-ngx instance
-   2. Click your username in the top right
-   3. Select "My Profile"
-   4. Click the circular arrow button to generate a new token
+   CLI args take precedence over env vars when both are provided.
 
-1. Replace the placeholders in your MCP config:
-   - `http://your-paperless-instance:8000` with your Paperless-ngx URL
-   - `your-api-token` with the token you just generated
+That's it!
 
-That's it! Now you can ask Claude to help you manage your Paperless-ngx documents.
+## Agent Skill
+
+This package ships an [Agent Skill](https://agentskills.io/specification) in
+`skills/paperless-ngx/` with decision trees, tool reference docs, query syntax
+guide, and workflow templates for AI agents.
+
+View the skill on the registry: https://skills.sh/kjanat/paperless-mcp/paperless-ngx
+
+_Add using_:
+
+```bash
+bunx skills add https://github.com/kjanat/paperless-mcp --skill paperless-ngx
+```
+
+`# or npx -y skills...`
 
 ## Example Usage
 
@@ -54,160 +81,167 @@ Here are some things you can ask Claude to do:
 
 ## Available Tools
 
+<details>
+<summary>Document Operations</summary>
+
 ### Document Operations
 
-#### get_document
+#### `get_document`
 
 Get a specific document by ID.
 
 Parameters:
 
-- id: Document ID
+- `id`: Document ID
 
 ```typescript
 get_document({
-  id: 123,
+	id: 123,
 });
 ```
 
-#### search_documents
+#### `search_documents`
 
 Full-text search across documents.
 
 Parameters:
 
-- query: Search query string
+- `query`: Search query string
 
 ```typescript
 search_documents({
-  query: "invoice 2024",
+	query: "invoice 2024",
 });
 ```
 
-#### download_document
+#### `download_document`
 
 Download a document file by ID.
 
 Parameters:
 
-- id: Document ID
-- original (optional): If true, downloads original file instead of archived version
+- `id`: Document ID
+- `original` (optional): If true, downloads original file instead of archived version
 
 ```typescript
 download_document({
-  id: 123,
-  original: false,
+	id: 123,
+	original: false,
 });
 ```
 
-#### bulk_edit_documents
+#### `bulk_edit_documents`
 
 Perform bulk operations on multiple documents.
 
 Parameters:
 
-- documents: Array of document IDs
-- method: One of:
-  - set_correspondent: Set correspondent for documents
-  - set_document_type: Set document type for documents
-  - set_storage_path: Set storage path for documents
-  - add_tag: Add a tag to documents
-  - remove_tag: Remove a tag from documents
-  - modify_tags: Add and/or remove multiple tags
-  - delete: Delete documents
-  - reprocess: Reprocess documents
-  - set_permissions: Set document permissions
-  - merge: Merge multiple documents
-  - split: Split a document into multiple documents
-  - rotate: Rotate document pages
-  - delete_pages: Delete specific pages from a document
-- Additional parameters based on method:
-  - correspondent: ID for set_correspondent
-  - document_type: ID for set_document_type
-  - storage_path: ID for set_storage_path
-  - tag: ID for add_tag/remove_tag
-  - add_tags: Array of tag IDs for modify_tags
-  - remove_tags: Array of tag IDs for modify_tags
-  - permissions: Object for set_permissions with owner, permissions, merge flag
-  - metadata_document_id: ID for merge to specify metadata source
-  - delete_originals: Boolean for merge/split
-  - pages: String for split "[1,2-3,4,5-7]" or delete_pages "[2,3,4]"
-  - degrees: Number for rotate (90, 180, or 270)
+- `documents`: Array of document IDs
+- `method`: One of:
+  - `set_correspondent`: Set correspondent for documents
+  - `set_document_type`: Set document type for documents
+  - `set_storage_path`: Set storage path for documents
+  - `add_tag`: Add a tag to documents
+  - `remove_tag`: Remove a tag from documents
+  - `modify_tags`: Add and/or remove multiple tags
+  - `delete`: Delete documents
+  - `reprocess`: Reprocess documents
+  - `set_permissions`: Set document permissions
+  - `merge`: Merge multiple documents
+  - `split`: Split a document into multiple documents
+  - `rotate`: Rotate document pages
+  - `delete_pages`: Delete specific pages from a document
+- Additional parameters based on `method`:
+  - `correspondent`: ID for set_correspondent
+  - `document_type`: ID for set_document_type
+  - `storage_path`: ID for set_storage_path
+  - `tag`: ID for add_tag/remove_tag
+  - `add_tags`: Array of tag IDs for modify_tags
+  - `remove_tags`: Array of tag IDs for modify_tags
+  - `permissions`: Object for set_permissions with owner, permissions, merge flag
+  - `metadata_document_id`: ID for merge to specify metadata source
+  - `delete_originals`: Boolean for merge/split
+  - `pages`: String for split "[1,2-3,4,5-7]" or `delete_pages` "[2,3,4]"
+  - `degrees`: Number for rotate (90, 180, or 270)
 
 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],
 });
 ```
 
-#### post_document
+#### `post_document`
 
 Upload a new document to Paperless-ngx.
 
 Parameters:
 
-- file: Base64 encoded file content
-- filename: Name of the file
-- title (optional): Title for the document
-- created (optional): DateTime when the document was created (e.g. "2024-01-19" or "2024-01-19 06:15:00+02:00")
-- correspondent (optional): ID of a correspondent
-- document_type (optional): ID of a document type
-- storage_path (optional): ID of a storage path
-- tags (optional): Array of tag IDs
-- archive_serial_number (optional): Archive serial number
-- custom_fields (optional): Array of custom field IDs
+- `file`: Base64 encoded file content
+- `filename`: Name of the file
+- `title` (optional): Title for the document
+- `created` (optional): DateTime when the document was created (e.g. "2024-01-19" or "2024-01-19 06:15:00+02:00")
+- `correspondent` (optional): ID of a correspondent
+- `document_type` (optional): ID of a document type
+- `storage_path` (optional): ID of a storage path
+- `tags` (optional): Array of tag IDs
+- `archive_serial_number` (optional): Archive serial number
+- `custom_fields` (optional): Array of custom field IDs
 
 ```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",
 });
 ```
 
+</details>
+<details>
+<summary>Tag Operations</summary>
+
 ### Tag Operations
 
-#### list_tags
+#### `list_tags`
 
 Get all tags.
 
@@ -215,57 +249,57 @@ Get all tags.
 list_tags();
 ```
 
-#### create_tag
+#### `create_tag`
 
 Create a new tag.
 
 Parameters:
 
-- name: Tag name
-- color (optional): Hex color code (e.g. "#ff0000")
-- match (optional): Text pattern to match
-- matching_algorithm (optional): Integer 0-6 (0=none, 1=any, 2=all, 3=exact, 4=regex, 5=fuzzy, 6=auto)
+- `name`: Tag name
+- `color` (optional): Hex color code (e.g. "#ff0000")
+- `match` (optional): Text pattern to match
+- `matching_algorithm` (optional): Integer 0-6 (0=none, 1=any, 2=all, 3=exact, 4=regex, 5=fuzzy, 6=auto)
 
 ```typescript
 create_tag({
-  name: "Invoice",
-  color: "#ff0000",
-  match: "invoice",
-  matching_algorithm: 5,
+	name: "Invoice",
+	color: "#ff0000",
+	match: "invoice",
+	matching_algorithm: 5,
 });
 ```
 
-#### update_tag
+#### `update_tag`
 
 Update an existing tag's name, color, or matching rules.
 
 Parameters:
 
-- id: Tag ID
-- name: New tag name
-- color (optional): Hex color code (e.g. "#ff0000")
-- match (optional): Text pattern to match
-- matching_algorithm (optional): Integer 0-6 (0=none, 1=any, 2=all, 3=exact, 4=regex, 5=fuzzy, 6=auto)
+- `id`: Tag ID
+- `name`: New tag name
+- `color` (optional): Hex color code (e.g. "#ff0000")
+- `match` (optional): Text pattern to match
+- `matching_algorithm` (optional): Integer 0-6 (0=none, 1=any, 2=all, 3=exact, 4=regex, 5=fuzzy, 6=auto)
 
 ```typescript
 update_tag({
-  id: 5,
-  name: "Invoices",
-  color: "#00ff00",
+	id: 5,
+	name: "Invoices",
+	color: "#00ff00",
 });
 ```
 
-#### delete_tag
+#### `delete_tag`
 
 Permanently delete a tag. Removes it from all documents.
 
 Parameters:
 
-- id: Tag ID
+- `id`: Tag ID
 
 ```typescript
 delete_tag({
-  id: 5,
+	id: 5,
 });
 ```
 
@@ -275,22 +309,26 @@ Bulk set permissions or delete multiple tags.
 
 Parameters:
 
-- tag_ids: Array of tag IDs
-- operation: "set_permissions" or "delete"
-- owner (optional): User ID (for set_permissions)
-- permissions (optional): Object with view/change user and group IDs
-- merge (optional): Merge with existing permissions (default false)
+- `tag_ids`: Array of tag IDs
+- `operation`: "set_permissions" or "delete"
+- `owner` (optional): User ID (for set_permissions)
+- `permissions` (optional): Object with view/change user and group IDs
+- `merge` (optional): Merge with existing permissions (default false)
 
 ```typescript
 bulk_edit_tags({
-  tag_ids: [1, 2, 3],
-  operation: "delete",
+	tag_ids: [1, 2, 3],
+	operation: "delete",
 });
 ```
 
+</details>
+<details>
+<summary>Correspondent Operations</summary>
+
 ### Correspondent Operations
 
-#### list_correspondents
+#### `list_correspondents`
 
 Get all correspondents.
 
@@ -304,40 +342,44 @@ Create a new correspondent.
 
 Parameters:
 
-- name: Correspondent name
-- match (optional): Text pattern to match
-- matching_algorithm (optional): Integer 0-6 (0=none, 1=any, 2=all, 3=exact, 4=regex, 5=fuzzy, 6=auto)
+- `name`: Correspondent name
+- `match` (optional): Text pattern to match
+- `matching_algorithm` (optional): Integer 0-6 (0=none, 1=any, 2=all, 3=exact, 4=regex, 5=fuzzy, 6=auto)
 
 ```typescript
 create_correspondent({
-  name: "ACME Corp",
-  match: "ACME",
-  matching_algorithm: 5,
+	name: "ACME Corp",
+	match: "ACME",
+	matching_algorithm: 5,
 });
 ```
 
-#### bulk_edit_correspondents
+#### `bulk_edit_correspondents`
 
 Bulk set permissions or delete multiple correspondents.
 
 Parameters:
 
-- correspondent_ids: Array of correspondent IDs
-- operation: "set_permissions" or "delete"
-- owner (optional): User ID (for set_permissions)
-- permissions (optional): Object with view/change user and group IDs
-- merge (optional): Merge with existing permissions (default false)
+- `correspondent_ids`: Array of correspondent IDs
+- `operation`: "set_permissions" or "delete"
+- `owner` (optional): User ID (for set_permissions)
+- `permissions` (optional): Object with view/change user and group IDs
+- `merge` (optional): Merge with existing permissions (default false)
 
 ```typescript
 bulk_edit_correspondents({
-  correspondent_ids: [1, 2],
-  operation: "delete",
+	correspondent_ids: [1, 2],
+	operation: "delete",
 });
 ```
 
+</details>
+<details>
+<summary>Document Type Operations</summary>
+
 ### Document Type Operations
 
-#### list_document_types
+#### `list_document_types`
 
 Get all document types.
 
@@ -351,37 +393,39 @@ Create a new document type.
 
 Parameters:
 
-- name: Document type name
-- match (optional): Text pattern to match
-- matching_algorithm (optional): Integer 0-6 (0=none, 1=any, 2=all, 3=exact, 4=regex, 5=fuzzy, 6=auto)
+- `name`: Document type name
+- `match` (optional): Text pattern to match
+- `matching_algorithm` (optional): Integer 0-6 (0=none, 1=any, 2=all, 3=exact, 4=regex, 5=fuzzy, 6=auto)
 
 ```typescript
 create_document_type({
-  name: "Invoice",
-  match: "invoice total amount due",
-  matching_algorithm: 1,
+	name: "Invoice",
+	match: "invoice total amount due",
+	matching_algorithm: 1,
 });
 ```
 
-#### bulk_edit_document_types
+#### `bulk_edit_document_types`
 
 Bulk set permissions or delete multiple document types.
 
 Parameters:
 
-- document_type_ids: Array of document type IDs
-- operation: "set_permissions" or "delete"
-- owner (optional): User ID (for set_permissions)
-- permissions (optional): Object with view/change user and group IDs
-- merge (optional): Merge with existing permissions (default false)
+- `document_type_ids`: Array of document type IDs
+- `operation`: "set_permissions" or "delete"
+- `owner` (optional): User ID (for set_permissions)
+- `permissions` (optional): Object with view/change user and group IDs
+- `merge` (optional): Merge with existing permissions (default false)
 
 ```typescript
 bulk_edit_document_types({
-  document_type_ids: [1, 2],
-  operation: "delete",
+	document_type_ids: [1, 2],
+	operation: "delete",
 });
 ```
 
+</details>
+
 ## Error Handling
 
 The server will show clear error messages if:
@@ -427,19 +471,33 @@ The MCP server can be run in two modes:
 This is the default mode. The server communicates over stdio, suitable for CLI and direct integrations.
 
 ```bash
-bun start -- <baseUrl> <token>
+# via .env file (Bun loads .env automatically)
+bun start
+
+# via inline env vars
+PAPERLESS_URL=http://localhost:8000 PAPERLESS_API_KEY=your-token bun start
+
+# via positional args
+bun start http://localhost:8000 your-token
 ```
 
+> [!TIP]
+> When using Bun, env vars in a `.env` file are loaded automatically —
+> no extra setup needed. Just create a `.env` with `PAPERLESS_URL` and
+> `PAPERLESS_API_KEY` and run `bun start`.
+
 ### 2. HTTP (Streamable HTTP Transport)
 
-To run the server as an HTTP service, use the `--http` flag. You can also specify the port with `--port` (default: 3000). This mode requires [Express](https://expressjs.com/) to be installed (it is included as a dependency).
+To run the server as an HTTP service, use the `--http` flag. You can also specify the port with `--port` (default: 3000).
 
 ```bash
-bun start -- <baseUrl> <token> --http --port 3000
+PAPERLESS_URL=http://localhost:8000 PAPERLESS_API_KEY=your-token bun start --http --port 3000
 ```
 
+With a `.env` file, this simplifies to `bun start --http`.
+
 - The MCP API will be available at `POST /mcp` on the specified port.
 - Each request is handled statelessly, following the [StreamableHTTPServerTransport](https://github.com/modelcontextprotocol/typescript-sdk) pattern.
 - GET and DELETE requests to `/mcp` will return 405 Method Not Allowed.
 
-<!--markdownlint-disable-file no-hard-tabs-->
+<!--markdownlint-disable-file no-hard-tabs no-inline-html no-bare-urls-->