@kjanat/paperless-mcp 2.0.1 → 2.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +219 -161
  2. package/dist/index.js +124 -97
  3. package/package.json +62 -53
  4. package/skills/paperless-ngx/SKILL.md +13 -13
  5. package/skills/paperless-ngx/references/query-syntax.md +5 -5
  6. package/skills/paperless-ngx/references/tools.md +28 -25
  7. package/skills/paperless-ngx/references/workflows.md +34 -14
  8. package/skills/paperless-ngx/scripts/test-connection.sh +4 -4
package/package.json CHANGED
@@ -1,55 +1,64 @@
1
1
  {
2
- "name": "@kjanat/paperless-mcp",
3
- "version": "2.0.1",
4
- "description": "MCP server for interacting with Paperless-ngx document management system.",
5
- "keywords": [
6
- "mcp",
7
- "paperless-ngx",
8
- "document-management",
9
- "ai",
10
- "claude",
11
- "model-context-protocol",
12
- "paperless"
13
- ],
14
- "repository": {
15
- "type": "git",
16
- "url": "git+https://github.com/kjanat/paperless-mcp.git"
17
- },
18
- "license": "MIT",
19
- "author": "Kaj Kowalski",
20
- "type": "module",
21
- "bin": {
22
- "paperless-mcp": "dist/index.js"
23
- },
24
- "files": [
25
- "dist",
26
- "skills"
27
- ],
28
- "scripts": {
29
- "bd": "bun build src/index.ts --minify --outdir=dist --target=node --banner='#!/usr/bin/env node'",
30
- "fmt": "dprint fmt",
31
- "fmt:check": "dprint check",
32
- "inspect": "bunx @modelcontextprotocol/inspector bun src/index.ts",
33
- "prepack": "bun bd && bunx prettier README.md --write",
34
- "start": "bun src/index.ts",
35
- "typecheck": "tsgo --noEmit"
36
- },
37
- "dependencies": {
38
- "@modelcontextprotocol/sdk": "^1.26.0",
39
- "zod": "^4.3.6"
40
- },
41
- "devDependencies": {
42
- "@types/bun": "^1.3.9",
43
- "@typescript/native-preview": "^7.0.0-dev.20260221.1",
44
- "dprint": "^0.51.1",
45
- "typescript": "^5.9.3"
46
- },
47
- "optionalDependencies": {
48
- "express": "^5.2.1"
49
- },
50
- "packageManager": "bun@1.3.9",
51
- "publishConfig": {
52
- "access": "public",
53
- "tag": "dev"
54
- }
2
+ "name": "@kjanat/paperless-mcp",
3
+ "version": "2.1.1",
4
+ "description": "MCP server for interacting with Paperless-ngx document management system.",
5
+ "keywords": [
6
+ "paperless-ngx",
7
+ "paperless",
8
+ "ai",
9
+ "mcp",
10
+ "model-context-protocol",
11
+ "document-management"
12
+ ],
13
+ "repository": {
14
+ "type": "git",
15
+ "url": "git+https://github.com/kjanat/paperless-mcp.git"
16
+ },
17
+ "license": "MIT",
18
+ "author": "Kaj Kowalski",
19
+ "type": "module",
20
+ "imports": {
21
+ "#*": "./src/*.ts"
22
+ },
23
+ "bin": {
24
+ "paperless-mcp": "dist/index.js"
25
+ },
26
+ "files": [
27
+ "dist",
28
+ "skills"
29
+ ],
30
+ "scripts": {
31
+ "bd": "bun build src/index.ts --minify --outdir=dist --target=node --banner='#!/usr/bin/env node'",
32
+ "meta": "bash scripts/meta.sh",
33
+ "fmt": "dprint fmt",
34
+ "fmt:check": "dprint check",
35
+ "mcp": "bun src/index.ts",
36
+ "inspect": "bunx @modelcontextprotocol/inspector run mcp",
37
+ "prepack": "bun bd",
38
+ "start": "run mcp",
39
+ "typecheck": "tsgo --noEmit"
40
+ },
41
+ "devDependencies": {
42
+ "@modelcontextprotocol/sdk": "^1.29.0",
43
+ "@types/bun": "^1.3.14",
44
+ "@types/express": "^5.0.6",
45
+ "@typescript/native-preview": "^7.0.0-dev.20260606.1",
46
+ "dprint": "0.51.1",
47
+ "express": "^5.2.1",
48
+ "runner-run": "^0.12.1",
49
+ "typescript": "^6.0.3",
50
+ "zod": "^4.4.3"
51
+ },
52
+ "packageManager": "bun@1.3.14",
53
+ "engines": {
54
+ "node": ">=22"
55
+ },
56
+ "publishConfig": {
57
+ "access": "public",
58
+ "tag": "dev"
59
+ },
60
+ "volta": {
61
+ "node": "26.3.0",
62
+ "npm": "11.16.0"
63
+ }
55
64
  }
package/skills/paperless-ngx/SKILL.md CHANGED
@@ -1,16 +1,16 @@
1
1
  ---
2
2
  name: paperless-ngx
3
- description: Manage documents in Paperless-NGX via MCP tools. Search, upload, tag, organize, and bulk-edit documents, correspondents, and document types. Use when working with Paperless-NGX, document management, OCR, or any mcp_paperless_* tool task.
4
- license: ISC
5
- compatibility: Requires a running Paperless-NGX instance with API token. MCP server must be connected with mcp_paperless_* tools available.
3
+ description: Manages documents in Paperless-ngx via MCP tools. Searches, uploads, tags, organizes, and bulk-edits documents, correspondents, and document types. Use when working with Paperless-ngx, document management, OCR, or any mcp_paperless_* tool task.
4
+ license: MIT
5
+ compatibility: Requires a running Paperless-ngx instance with API token. MCP server must be connected with mcp_paperless_* tools available.
6
6
  metadata:
7
7
  author: kjanat
8
- version: "1.0"
8
+ version: "2.0.1"
9
9
  ---
10
10
 
11
- # Paperless-NGX Document Management
11
+ # Paperless-ngx Document Management
12
12
 
13
- Orchestrate Paperless-NGX through 16 MCP tools across 4 domains.
13
+ Orchestrate Paperless-ngx through 16 MCP tools across 4 domains.
14
14
 
15
15
  ## Tool Catalog
16
16
 
@@ -54,7 +54,7 @@ Orchestrate Paperless-NGX through 16 MCP tools across 4 domains.
54
54
 
55
55
  ### Find a Document
56
56
 
57
- ```
57
+ ```txt
58
58
  What do you know?
59
59
  ├─ Keywords/content → search_documents(query="term1 term2")
60
60
  ├─ Document ID → get_document(id=N)
@@ -67,7 +67,7 @@ What do you know?
67
67
 
68
68
  ### Organize Documents
69
69
 
70
- ```
70
+ ```txt
71
71
  What operation?
72
72
  ├─ Add tag → bulk_edit_documents(method="add_tag", tag=ID)
73
73
  ├─ Remove tag → bulk_edit_documents(method="remove_tag", tag=ID)
@@ -83,7 +83,7 @@ What operation?
83
83
 
84
84
  ### Upload a Document
85
85
 
86
- ```
86
+ ```txt
87
87
  1. Resolve metadata IDs first:
88
88
  ├─ list_tags → find or create_tag
89
89
  ├─ list_correspondents → find or create_correspondent
@@ -93,7 +93,7 @@ What operation?
93
93
 
94
94
  ### Manage Taxonomy (Tags/Correspondents/Types)
95
95
 
96
- ```
96
+ ```txt
97
97
  Need to change metadata objects?
98
98
  ├─ View all → list_tags / list_correspondents / list_document_types
99
99
  ├─ Create new → create_tag / create_correspondent / create_document_type
@@ -107,9 +107,9 @@ Need to change metadata objects?
107
107
  - **search_documents strips `content`** to save tokens. Use `get_document` for
108
108
  full OCR text.
109
109
  - **post_document requires base64** file content, not file paths.
110
- - **matching_algorithm inconsistency**: numeric `0-4` for tags, string enum
111
- (`"any"`, `"all"`, `"exact"`, `"regular expression"`, `"fuzzy"`) for
112
- correspondents/document types. See [tools.md](references/tools.md).
110
+ - **matching_algorithm** is integer `0-6` across all endpoints (tags,
111
+ correspondents, document types): `0`=none, `1`=any, `2`=all, `3`=exact,
112
+ `4`=regex, `5`=fuzzy, `6`=auto. See [tools.md](references/tools.md).
113
113
  - **Bulk delete is permanent and irreversible.**
114
114
  - **download_document** returns base64 blob + filename from content-disposition.
115
115
 
package/skills/paperless-ngx/references/query-syntax.md CHANGED
@@ -1,4 +1,4 @@
1
- # Paperless-NGX Search Query Syntax
1
+ # Paperless-ngx Search Query Syntax
2
2
 
3
3
  Reference for the `query` parameter of `search_documents`.
4
4
 
@@ -6,7 +6,7 @@ Reference for the `query` parameter of `search_documents`.
6
6
 
7
7
  Words separated by spaces match documents containing **ALL** words.
8
8
 
9
- ```
9
+ ```txt
10
10
  invoice electricity # docs with BOTH "invoice" AND "electricity"
11
11
  ```
12
12
 
@@ -23,7 +23,7 @@ invoice electricity # docs with BOTH "invoice" AND "electricity"
23
23
 
24
24
  ## Logical Operators
25
25
 
26
- ```
26
+ ```txt
27
27
  term1 AND term2 # Both required (default behavior)
28
28
  term1 OR term2 # Either matches
29
29
  NOT term1 # Exclude term
@@ -43,14 +43,14 @@ term1 AND (term2 OR term3) # Grouping with parentheses
43
43
 
44
44
  ## Wildcards
45
45
 
46
- ```
46
+ ```txt
47
47
  prod*name # Matches "production name", "product name", etc.
48
48
  inv?ice # Single character wildcard
49
49
  ```
50
50
 
51
51
  ## Combined Queries
52
52
 
53
- ```
53
+ ```txt
54
54
  # Unpaid invoices from 2024
55
55
  tag:unpaid type:invoice created:2024
56
56
 
package/skills/paperless-ngx/references/tools.md CHANGED
@@ -1,6 +1,13 @@
1
1
  # MCP Tool Reference
2
2
 
3
- Full parameter signatures for all 16 Paperless-NGX MCP tools.
3
+ Full parameter signatures for all 16 Paperless-ngx MCP tools.
4
+
5
+ ## Contents
6
+
7
+ - [Document Tools](#document-tools) — search, get, post, download, bulk_edit
8
+ - [Tag Tools](#tag-tools) — list, create, update, delete, bulk_edit
9
+ - [Correspondent Tools](#correspondent-tools) — list, create, bulk_edit
10
+ - [Document Type Tools](#document-type-tools) — list, create, bulk_edit
4
11
 
5
12
  ## Document Tools
6
13
 
@@ -8,7 +15,7 @@ Full parameter signatures for all 16 Paperless-NGX MCP tools.
8
15
 
9
16
  | Param | Type | Required | Notes |
10
17
  | ----------- | ------ | -------- | --------------------------- |
11
- | `query` | string | yes | Paperless-NGX search syntax |
18
+ | `query` | string | yes | Paperless-ngx search syntax |
12
19
  | `page` | number | no | Pagination, starts at 1 |
13
20
  | `page_size` | number | no | Default 25, max 100 |
14
21
 
@@ -32,7 +39,7 @@ Returns metadata **without** `content` field. Use `get_document` for full text.
32
39
  | `document_type` | number | no | Document type ID |
33
40
  | `storage_path` | number | no | Storage path ID |
34
41
  | `tags` | number[] | no | Array of tag IDs |
35
- | `archive_serial_number` | string | no | External filing reference |
42
+ | `archive_serial_number` | integer | no | External filing reference (≥0) |
36
43
  | `custom_fields` | number[] | no | Custom field IDs |
37
44
 
38
45
  ### download_document
@@ -75,22 +82,22 @@ No parameters. Returns all tags with name, color, matching rules.
75
82
 
76
83
  ### create_tag
77
84
 
78
- | Param | Type | Required | Notes |
79
- | -------------------- | ------ | -------- | ------------------------------------------------- |
80
- | `name` | string | yes | Unique tag name |
81
- | `color` | string | no | Hex: `#FF0000` |
82
- | `match` | string | no | Auto-assign pattern |
83
- | `matching_algorithm` | int | no | `0`=any, `1`=all, `2`=exact, `3`=regex, `4`=fuzzy |
85
+ | Param | Type | Required | Notes |
86
+ | -------------------- | ------ | -------- | --------------------------------------------------------------------- |
87
+ | `name` | string | yes | Unique tag name |
88
+ | `color` | string | no | Hex: `#FF0000` |
89
+ | `match` | string | no | Auto-assign pattern |
90
+ | `matching_algorithm` | int | no | `0`=none, `1`=any, `2`=all, `3`=exact, `4`=regex, `5`=fuzzy, `6`=auto |
84
91
 
85
92
  ### update_tag
86
93
 
87
94
  | Param | Type | Required | Notes |
88
95
  | -------------------- | ------ | -------- | ------------------------ |
89
96
  | `id` | number | yes | Tag ID from list_tags |
90
- | `name` | string | yes | New name |
97
+ | `name` | string | no | New name |
91
98
  | `color` | string | no | Hex color |
92
99
  | `match` | string | no | Auto-assign pattern |
93
- | `matching_algorithm` | int | no | `0`-`4` (same as create) |
100
+ | `matching_algorithm` | int | no | `0`-`6` (same as create) |
94
101
 
95
102
  ### delete_tag
96
103
 
@@ -116,13 +123,11 @@ No parameters.
116
123
 
117
124
  ### create_correspondent
118
125
 
119
- | Param | Type | Required | Notes |
120
- | -------------------- | ------ | -------- | ---------------------------------------------------------- |
121
- | `name` | string | yes | Person/company/org name |
122
- | `match` | string | no | Auto-assign pattern |
123
- | `matching_algorithm` | enum | no | `"any"`,`"all"`,`"exact"`,`"regular expression"`,`"fuzzy"` |
124
-
125
- **Note:** String enum, not numeric like tags.
126
+ | Param | Type | Required | Notes |
127
+ | -------------------- | ------ | -------- | --------------------------------------------------------------------- |
128
+ | `name` | string | yes | Person/company/org name |
129
+ | `match` | string | no | Auto-assign pattern |
130
+ | `matching_algorithm` | int | no | `0`=none, `1`=any, `2`=all, `3`=exact, `4`=regex, `5`=fuzzy, `6`=auto |
126
131
 
127
132
  ### bulk_edit_correspondents
128
133
 
@@ -142,13 +147,11 @@ No parameters.
142
147
 
143
148
  ### create_document_type
144
149
 
145
- | Param | Type | Required | Notes |
146
- | -------------------- | ------ | -------- | ---------------------------------------------------------- |
147
- | `name` | string | yes | Type name (Invoice, Receipt, etc.) |
148
- | `match` | string | no | Auto-assign pattern |
149
- | `matching_algorithm` | enum | no | `"any"`,`"all"`,`"exact"`,`"regular expression"`,`"fuzzy"` |
150
-
151
- **Note:** String enum, not numeric like tags.
150
+ | Param | Type | Required | Notes |
151
+ | -------------------- | ------ | -------- | --------------------------------------------------------------------- |
152
+ | `name` | string | yes | Type name (Invoice, Receipt, etc.) |
153
+ | `match` | string | no | Auto-assign pattern |
154
+ | `matching_algorithm` | int | no | `0`=none, `1`=any, `2`=all, `3`=exact, `4`=regex, `5`=fuzzy, `6`=auto |
152
155
 
153
156
  ### bulk_edit_document_types
154
157
 
package/skills/paperless-ngx/references/workflows.md CHANGED
@@ -1,10 +1,20 @@
1
1
  # Common Workflows
2
2
 
3
- Multi-step operations for Paperless-NGX document management.
3
+ Multi-step operations for Paperless-ngx document management.
4
+
5
+ ## Contents
6
+
7
+ 1. [Classify Untagged Documents](#1-classify-untagged-documents)
8
+ 2. [Bulk Reclassify by Correspondent](#2-bulk-reclassify-by-correspondent)
9
+ 3. [Upload and Categorize a Batch](#3-upload-and-categorize-a-batch)
10
+ 4. [Merge Related Documents](#4-merge-related-documents)
11
+ 5. [Export Documents for External Use](#5-export-documents-for-external-use)
12
+ 6. [Set Up Auto-Classification Rules](#6-set-up-auto-classification-rules)
13
+ 7. [Audit and Clean Up Tags](#7-audit-and-clean-up-tags)
4
14
 
5
15
  ## 1. Classify Untagged Documents
6
16
 
7
- ```
17
+ ```txt
8
18
  1. search_documents(query="NOT tag:*")
9
19
  → get list of untagged document IDs + titles
10
20
 
@@ -24,7 +34,7 @@ Multi-step operations for Paperless-NGX document management.
24
34
 
25
35
  ## 2. Bulk Reclassify by Correspondent
26
36
 
27
- ```
37
+ ```txt
28
38
  1. list_correspondents()
29
39
  → identify current + target correspondent IDs
30
40
 
@@ -40,7 +50,7 @@ Multi-step operations for Paperless-NGX document management.
40
50
 
41
51
  ## 3. Upload and Categorize a Batch
42
52
 
43
- ```
53
+ ```txt
44
54
  For each file:
45
55
 
46
56
  1. Resolve metadata:
@@ -56,11 +66,15 @@ For each file:
56
66
  document_type=2,
57
67
  created="2024-03-15"
58
68
  )
69
+ → returns task ID (processing is async)
70
+
71
+ 3. Verify: search_documents(query="receipt-2024-03")
72
+ → confirm document appears with expected metadata
59
73
  ```
60
74
 
61
75
  ## 4. Merge Related Documents
62
76
 
63
- ```
77
+ ```txt
64
78
  1. search_documents(query="invoice acme created:[2024-01 to 2024-03]")
65
79
  → collect document IDs
66
80
 
@@ -73,11 +87,14 @@ For each file:
73
87
  metadata_document_id=PRIMARY_ID,
74
88
  delete_originals=false # keep originals until verified
75
89
  )
90
+
91
+ 4. Verify: get_document(id=PRIMARY_ID)
92
+ → confirm merged content is correct before deleting originals
76
93
  ```
77
94
 
78
95
  ## 5. Export Documents for External Use
79
96
 
80
- ```
97
+ ```txt
81
98
  1. search_documents(query="tag:export-ready")
82
99
  → collect IDs
83
100
 
@@ -90,31 +107,31 @@ For each file:
90
107
 
91
108
  ## 6. Set Up Auto-Classification Rules
92
109
 
93
- ```
110
+ ```txt
94
111
  1. create_tag(
95
112
  name="electricity",
96
113
  match="electricity power grid kwh",
97
- matching_algorithm=0 # any word matches
114
+ matching_algorithm=1 # 1=any word matches
98
115
  )
99
116
 
100
117
  2. create_correspondent(
101
118
  name="Power Company",
102
119
  match="Power Co energy provider",
103
- matching_algorithm="fuzzy" # note: string enum for correspondents
120
+ matching_algorithm=5 # 5=fuzzy
104
121
  )
105
122
 
106
123
  3. create_document_type(
107
124
  name="Utility Bill",
108
125
  match="utility bill statement due",
109
- matching_algorithm="any"
126
+ matching_algorithm=1 # 1=any word matches
110
127
  )
111
128
 
112
- Future uploads auto-classified by Paperless-NGX matching engine.
129
+ Future uploads auto-classified by Paperless-ngx matching engine.
113
130
  ```
114
131
 
115
132
  ## 7. Audit and Clean Up Tags
116
133
 
117
- ```
134
+ ```txt
118
135
  1. list_tags()
119
136
  → review all tags, identify duplicates/unused
120
137
 
@@ -124,7 +141,10 @@ Future uploads auto-classified by Paperless-NGX matching engine.
124
141
  3. If migrating:
125
142
  search → collect IDs → bulk_edit add new tag → bulk_edit remove old tag
126
143
 
127
- 4. delete_tag(id=OLD_TAG_ID)
144
+ 4. Verify: search_documents(query="tag:new-tag-name")
145
+ → confirm all documents migrated before deleting old tag
146
+
147
+ 5. delete_tag(id=OLD_TAG_ID)
128
148
  or bulk_edit_tags(tag_ids=[...], operation="delete")
129
149
  ```
130
150
 
@@ -132,7 +152,7 @@ Future uploads auto-classified by Paperless-NGX matching engine.
132
152
 
133
153
  All document operations use numeric IDs, not names. Always:
134
154
 
135
- ```
155
+ ```txt
136
156
  list_*() → find ID for name
137
157
  → if not found: create_*() → get ID from response
138
158
  → then use ID in subsequent operations
package/skills/paperless-ngx/scripts/test-connection.sh CHANGED
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env bash
2
2
  set -euo pipefail
3
3
 
4
- # Test Paperless-NGX API connectivity and authentication.
4
+ # Test Paperless-ngx API connectivity and authentication.
5
5
  # Usage: test-connection.sh <base_url> <api_token>
6
6
  # Example: test-connection.sh https://docs.example.com abc123token
7
7
 
@@ -35,7 +35,7 @@ echo " Reachable (HTTP ${HTTP_CODE})"
35
35
  AUTH_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
36
36
  --max-time 10 \
37
37
  -H "Authorization: Token ${TOKEN}" \
38
- -H "Accept: application/json; version=5" \
38
+ -H "Accept: application/json; version=6" \
39
39
  "${BASE_URL}/api/documents/" 2>/dev/null)
40
40
 
41
41
  if [[ "${AUTH_CODE}" == "401" || "${AUTH_CODE}" == "403" ]]; then
@@ -53,7 +53,7 @@ echo " Authenticated (HTTP ${AUTH_CODE})"
53
53
  # 3. Quick stats
54
54
  RESPONSE=$(curl -s --max-time 10 \
55
55
  -H "Authorization: Token ${TOKEN}" \
56
- -H "Accept: application/json; version=5" \
56
+ -H "Accept: application/json; version=6" \
57
57
  "${BASE_URL}/api/documents/?page_size=1" 2>/dev/null)
58
58
 
59
59
  DOC_COUNT=$(echo "${RESPONSE}" | grep -o '"count":[0-9]*' | head -1 | cut -d: -f2)
@@ -61,7 +61,7 @@ echo " Documents: ${DOC_COUNT:-unknown}"
61
61
 
62
62
  TAG_RESPONSE=$(curl -s --max-time 10 \
63
63
  -H "Authorization: Token ${TOKEN}" \
64
- -H "Accept: application/json; version=5" \
64
+ -H "Accept: application/json; version=6" \
65
65
  "${BASE_URL}/api/tags/" 2>/dev/null)
66
66
 
67
67
  TAG_COUNT=$(echo "${TAG_RESPONSE}" | grep -o '"count":[0-9]*' | head -1 | cut -d: -f2)