@kjanat/paperless-mcp 2.0.0 → 2.1.0

package/README.md

@@ -6,13 +6,30 @@ An MCP (Model Context Protocol) server for interacting with a Paperless-ngx API
 
 ### 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
 
-   ```bash
-   bun install -g @kjanat/paperless-mcp
+1. Add it to your MCP client configuration (using env vars):
+
+   ```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
    {
@@ -29,17 +46,25 @@ An MCP (Model Context Protocol) server for interacting with a Paperless-ngx API
    }
    ```
 
-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.
+
+That's it!
+
+## 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.
 
-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
+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
+```
 
-That's it! Now you can ask Claude to help you manage your Paperless-ngx documents.
+`# or npx -y skills...`
 
 ## Example Usage
 
@@ -54,15 +79,18 @@ 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({
@@ -70,13 +98,13 @@ get_document({
 });
 ```
 
-#### search_documents
+#### `search_documents`
 
 Full-text search across documents.
 
 Parameters:
 
-- query: Search query string
+- `query`: Search query string
 
 ```typescript
 search_documents({
@@ -84,14 +112,14 @@ search_documents({
 });
 ```
 
-#### 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({
@@ -100,39 +128,39 @@ download_document({
 });
 ```
 
-#### 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:
 
@@ -175,22 +203,22 @@ bulk_edit_documents({
 });
 ```
 
-#### 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({
@@ -205,9 +233,13 @@ post_document({
 });
 ```
 
+</details>
+<details>
+<summary>Tag Operations</summary>
+
 ### Tag Operations
 
-#### list_tags
+#### `list_tags`
 
 Get all tags.
 
@@ -215,16 +247,16 @@ 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({
@@ -235,17 +267,17 @@ create_tag({
 });
 ```
 
-#### 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({
@@ -255,13 +287,13 @@ update_tag({
 });
 ```
 
-#### delete_tag
+#### `delete_tag`
 
 Permanently delete a tag. Removes it from all documents.
 
 Parameters:
 
-- id: Tag ID
+- `id`: Tag ID
 
 ```typescript
 delete_tag({
@@ -275,11 +307,11 @@ 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({
@@ -288,9 +320,13 @@ bulk_edit_tags({
 });
 ```
 
+</details>
+<details>
+<summary>Correspondent Operations</summary>
+
 ### Correspondent Operations
 
-#### list_correspondents
+#### `list_correspondents`
 
 Get all correspondents.
 
@@ -304,9 +340,9 @@ 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({
@@ -316,17 +352,17 @@ create_correspondent({
 });
 ```
 
-#### 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({
@@ -335,9 +371,13 @@ bulk_edit_correspondents({
 });
 ```
 
+</details>
+<details>
+<summary>Document Type Operations</summary>
+
 ### Document Type Operations
 
-#### list_document_types
+#### `list_document_types`
 
 Get all document types.
 
@@ -351,9 +391,9 @@ 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({
@@ -363,17 +403,17 @@ create_document_type({
 });
 ```
 
-#### 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({
@@ -382,6 +422,8 @@ bulk_edit_document_types({
 });
 ```
 
+</details>
+
 ## Error Handling
 
 The server will show clear error messages if:
@@ -427,19 +469,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-->