From e7b6d37cc9da1a79ff64631c8fad15ffcd1b329b Mon Sep 17 00:00:00 2001 From: Marcus van Elst Date: Wed, 20 May 2026 11:30:21 +0200 Subject: [PATCH] feat: rename tool ids from dotted to underscore for claude.ai compat Update stale dotted tool-name references in tool descriptions and docs to match the underscore tool ids required by claude.ai (pattern ^[a-zA-Z0-9_-]{1,64}$). Co-Authored-By: Claude Opus 4.7 --- PaperlessMCP/Tools/DocumentTools.cs | 4 +- README.md | 86 ++++++++++++++-------------- docs/API_REFERENCE.md | 88 ++++++++++++++--------------- 3 files changed, 89 insertions(+), 89 deletions(-) diff --git a/PaperlessMCP/Tools/DocumentTools.cs b/PaperlessMCP/Tools/DocumentTools.cs index a23c18d..f7b7797 100644 --- a/PaperlessMCP/Tools/DocumentTools.cs +++ b/PaperlessMCP/Tools/DocumentTools.cs @@ -32,7 +32,7 @@ public static class DocumentTools [Description("Page number (default: 1)")] int page = 1, [Description("Page size (default: 25, max: 100)")] int pageSize = 25, [Description("Ordering field (e.g., 'created', '-created', 'title')")] string? ordering = null, - [Description("Include document content in results (default: false). Use paperless.documents.get for full content.")] bool includeContent = false, + [Description("Include document content in results (default: false). Use paperless_documents_get for full content.")] bool includeContent = false, [Description("Max content length per document when includeContent=true (default: 500). Use 0 for unlimited.")] int contentMaxLength = 500) { var tagIds = ParseIntArray(tags); @@ -189,7 +189,7 @@ public static class DocumentTools } [McpServerTool(Name = "paperless_documents_upload")] - [Description("Upload a new document to Paperless-ngx. Provide file content as base64. For large files, use paperless.documents.upload_from_path instead.")] + [Description("Upload a new document to Paperless-ngx. Provide file content as base64. For large files, use paperless_documents_upload_from_path instead.")] public static async Task Upload( PaperlessClient client, [Description("Base64-encoded file content")] string fileContent, diff --git a/README.md b/README.md index c2aa165..f9a6a9c 100644 --- a/README.md +++ b/README.md @@ -196,17 +196,17 @@ Requires [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0). | Tool | What it does | |------|--------------| -| `paperless.documents.search` | Find documents with full-text search and filters | -| `paperless.documents.get` | Get a document by ID with all metadata | -| `paperless.documents.upload` | Upload a document (base64) | -| `paperless.documents.upload_from_path` | Upload from a file path | -| `paperless.documents.update` | Update title, tags, correspondent, etc. | -| `paperless.documents.delete` | Delete a document (requires confirmation) | -| `paperless.documents.bulk_update` | Update multiple documents at once | -| `paperless.documents.download` | Get download URL for original file | -| `paperless.documents.preview` | Get preview URL | -| `paperless.documents.thumbnail` | Get thumbnail URL | -| `paperless.documents.reprocess` | Re-run OCR on a document | +| `paperless_documents_search` | Find documents with full-text search and filters | +| `paperless_documents_get` | Get a document by ID with all metadata | +| `paperless_documents_upload` | Upload a document (base64) | +| `paperless_documents_upload_from_path` | Upload from a file path | +| `paperless_documents_update` | Update title, tags, correspondent, etc. | +| `paperless_documents_delete` | Delete a document (requires confirmation) | +| `paperless_documents_bulk_update` | Update multiple documents at once | +| `paperless_documents_download` | Get download URL for original file | +| `paperless_documents_preview` | Get preview URL | +| `paperless_documents_thumbnail` | Get thumbnail URL | +| `paperless_documents_reprocess` | Re-run OCR on a document | @@ -215,12 +215,12 @@ Requires [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0). | Tool | What it does | |------|--------------| -| `paperless.tags.list` | List all tags | -| `paperless.tags.get` | Get a tag by ID | -| `paperless.tags.create` | Create a tag with optional color and matching rules | -| `paperless.tags.update` | Update a tag | -| `paperless.tags.delete` | Delete a tag | -| `paperless.tags.bulk_delete` | Delete multiple tags | +| `paperless_tags_list` | List all tags | +| `paperless_tags_get` | Get a tag by ID | +| `paperless_tags_create` | Create a tag with optional color and matching rules | +| `paperless_tags_update` | Update a tag | +| `paperless_tags_delete` | Delete a tag | +| `paperless_tags_bulk_delete` | Delete multiple tags | @@ -229,12 +229,12 @@ Requires [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0). | Tool | What it does | |------|--------------| -| `paperless.correspondents.list` | List all correspondents | -| `paperless.correspondents.get` | Get a correspondent by ID | -| `paperless.correspondents.create` | Create with optional matching rules | -| `paperless.correspondents.update` | Update a correspondent | -| `paperless.correspondents.delete` | Delete a correspondent | -| `paperless.correspondents.bulk_delete` | Delete multiple correspondents | +| `paperless_correspondents_list` | List all correspondents | +| `paperless_correspondents_get` | Get a correspondent by ID | +| `paperless_correspondents_create` | Create with optional matching rules | +| `paperless_correspondents_update` | Update a correspondent | +| `paperless_correspondents_delete` | Delete a correspondent | +| `paperless_correspondents_bulk_delete` | Delete multiple correspondents | @@ -243,12 +243,12 @@ Requires [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0). | Tool | What it does | |------|--------------| -| `paperless.document_types.list` | List all document types | -| `paperless.document_types.get` | Get a document type by ID | -| `paperless.document_types.create` | Create with optional matching rules | -| `paperless.document_types.update` | Update a document type | -| `paperless.document_types.delete` | Delete a document type | -| `paperless.document_types.bulk_delete` | Delete multiple document types | +| `paperless_document_types_list` | List all document types | +| `paperless_document_types_get` | Get a document type by ID | +| `paperless_document_types_create` | Create with optional matching rules | +| `paperless_document_types_update` | Update a document type | +| `paperless_document_types_delete` | Delete a document type | +| `paperless_document_types_bulk_delete` | Delete multiple document types | @@ -257,12 +257,12 @@ Requires [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0). | Tool | What it does | |------|--------------| -| `paperless.storage_paths.list` | List all storage paths | -| `paperless.storage_paths.get` | Get a storage path by ID | -| `paperless.storage_paths.create` | Create with path template | -| `paperless.storage_paths.update` | Update a storage path | -| `paperless.storage_paths.delete` | Delete a storage path | -| `paperless.storage_paths.bulk_delete` | Delete multiple storage paths | +| `paperless_storage_paths_list` | List all storage paths | +| `paperless_storage_paths_get` | Get a storage path by ID | +| `paperless_storage_paths_create` | Create with path template | +| `paperless_storage_paths_update` | Update a storage path | +| `paperless_storage_paths_delete` | Delete a storage path | +| `paperless_storage_paths_bulk_delete` | Delete multiple storage paths | @@ -271,12 +271,12 @@ Requires [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0). | Tool | What it does | |------|--------------| -| `paperless.custom_fields.list` | List all custom field definitions | -| `paperless.custom_fields.get` | Get a custom field by ID | -| `paperless.custom_fields.create` | Create a field (string, date, number, monetary, etc.) | -| `paperless.custom_fields.update` | Update a field definition | -| `paperless.custom_fields.delete` | Delete a field | -| `paperless.custom_fields.assign` | Assign a field value to a document | +| `paperless_custom_fields_list` | List all custom field definitions | +| `paperless_custom_fields_get` | Get a custom field by ID | +| `paperless_custom_fields_create` | Create a field (string, date, number, monetary, etc.) | +| `paperless_custom_fields_update` | Update a field definition | +| `paperless_custom_fields_delete` | Delete a field | +| `paperless_custom_fields_assign` | Assign a field value to a document | @@ -285,8 +285,8 @@ Requires [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0). | Tool | What it does | |------|--------------| -| `paperless.ping` | Check connectivity and auth | -| `paperless.capabilities` | List supported features | +| `paperless_ping` | Check connectivity and auth | +| `paperless_capabilities` | List supported features | diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index 639fe8a..20f8937 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -16,12 +16,12 @@ Complete reference for all MCP tools provided by PaperlessMCP. ## Health & Capabilities -### `paperless.ping` +### `paperless_ping` Verify connectivity and authentication with Paperless-ngx. **Returns:** Connection status and server version -### `paperless.capabilities` +### `paperless_capabilities` Return supported API endpoints and detected Paperless-ngx version information. **Returns:** Available endpoints, bulk operations, and server capabilities @@ -30,7 +30,7 @@ Return supported API endpoints and detected Paperless-ngx version information. ## Document Operations -### `paperless.documents.search` +### `paperless_documents_search` Search for documents with full-text search and filters. | Parameter | Type | Required | Default | Description | @@ -54,7 +54,7 @@ Search for documents with full-text search and filters. **Returns:** Paginated list of document summaries -### `paperless.documents.get` +### `paperless_documents_get` Get a document by its ID. | Parameter | Type | Required | Description | @@ -63,7 +63,7 @@ Get a document by its ID. **Returns:** Complete document details including content -### `paperless.documents.download` +### `paperless_documents_download` Get download URLs for a document's original file, preview, and thumbnail. | Parameter | Type | Required | Description | @@ -72,7 +72,7 @@ Get download URLs for a document's original file, preview, and thumbnail. **Returns:** Object with `original_url`, `preview_url`, `thumbnail_url` -### `paperless.documents.preview` +### `paperless_documents_preview` Get the preview URL for a document. | Parameter | Type | Required | Description | @@ -81,7 +81,7 @@ Get the preview URL for a document. **Returns:** Preview URL -### `paperless.documents.thumbnail` +### `paperless_documents_thumbnail` Get the thumbnail URL for a document. | Parameter | Type | Required | Description | @@ -90,7 +90,7 @@ Get the thumbnail URL for a document. **Returns:** Thumbnail URL -### `paperless.documents.upload` +### `paperless_documents_upload` Upload a new document to Paperless-ngx via base64-encoded content. | Parameter | Type | Required | Default | Description | @@ -107,9 +107,9 @@ Upload a new document to Paperless-ngx via base64-encoded content. **Returns:** Task ID and upload status -> **Note:** For large files, use `paperless.documents.upload_from_path` instead. +> **Note:** For large files, use `paperless_documents_upload_from_path` instead. -### `paperless.documents.upload_from_path` +### `paperless_documents_upload_from_path` Upload a document from a local file path. More reliable for large files. | Parameter | Type | Required | Default | Description | @@ -127,7 +127,7 @@ Upload a document from a local file path. More reliable for large files. **Features:** Supports `~/` expansion, automatic retries, file validation -### `paperless.documents.update` +### `paperless_documents_update` Update document metadata. | Parameter | Type | Required | Default | Description | @@ -143,7 +143,7 @@ Update document metadata. **Returns:** Updated document -### `paperless.documents.delete` +### `paperless_documents_delete` Delete a document. Requires explicit confirmation. | Parameter | Type | Required | Default | Description | @@ -155,7 +155,7 @@ Delete a document. Requires explicit confirmation. > **Safety:** Without `confirm=true`, returns a dry-run preview showing what would be deleted. -### `paperless.documents.bulk_update` +### `paperless_documents_bulk_update` Perform bulk operations on multiple documents. | Parameter | Type | Required | Default | Description | @@ -170,7 +170,7 @@ Perform bulk operations on multiple documents. > **Safety:** Defaults to dry-run mode to prevent accidental changes. -### `paperless.documents.reprocess` +### `paperless_documents_reprocess` Reprocess a document's OCR and content extraction. | Parameter | Type | Required | Default | Description | @@ -184,7 +184,7 @@ Reprocess a document's OCR and content extraction. ## Tag Operations -### `paperless.tags.list` +### `paperless_tags_list` List all tags with pagination. | Parameter | Type | Required | Default | Description | @@ -195,7 +195,7 @@ List all tags with pagination. **Returns:** Paginated list of tags -### `paperless.tags.get` +### `paperless_tags_get` Get a tag by its ID. | Parameter | Type | Required | Description | @@ -204,7 +204,7 @@ Get a tag by its ID. **Returns:** Tag details -### `paperless.tags.create` +### `paperless_tags_create` Create a new tag. | Parameter | Type | Required | Default | Description | @@ -226,7 +226,7 @@ Create a new tag. **Returns:** Created tag -### `paperless.tags.update` +### `paperless_tags_update` Update an existing tag. | Parameter | Type | Required | Description | @@ -240,7 +240,7 @@ Update an existing tag. **Returns:** Updated tag -### `paperless.tags.delete` +### `paperless_tags_delete` Delete a tag. Requires explicit confirmation. | Parameter | Type | Required | Default | Description | @@ -250,7 +250,7 @@ Delete a tag. Requires explicit confirmation. **Returns:** Deletion status or dry-run preview -### `paperless.tags.bulk_delete` +### `paperless_tags_bulk_delete` Delete multiple tags. | Parameter | Type | Required | Default | Description | @@ -265,7 +265,7 @@ Delete multiple tags. ## Correspondent Operations -### `paperless.correspondents.list` +### `paperless_correspondents_list` List all correspondents with pagination. | Parameter | Type | Required | Default | Description | @@ -276,7 +276,7 @@ List all correspondents with pagination. **Returns:** Paginated list of correspondents -### `paperless.correspondents.get` +### `paperless_correspondents_get` Get a correspondent by its ID. | Parameter | Type | Required | Description | @@ -285,7 +285,7 @@ Get a correspondent by its ID. **Returns:** Correspondent details -### `paperless.correspondents.create` +### `paperless_correspondents_create` Create a new correspondent. | Parameter | Type | Required | Default | Description | @@ -296,7 +296,7 @@ Create a new correspondent. **Returns:** Created correspondent -### `paperless.correspondents.update` +### `paperless_correspondents_update` Update an existing correspondent. | Parameter | Type | Required | Description | @@ -308,7 +308,7 @@ Update an existing correspondent. **Returns:** Updated correspondent -### `paperless.correspondents.delete` +### `paperless_correspondents_delete` Delete a correspondent. Requires explicit confirmation. | Parameter | Type | Required | Default | Description | @@ -318,7 +318,7 @@ Delete a correspondent. Requires explicit confirmation. **Returns:** Deletion status or dry-run preview -### `paperless.correspondents.bulk_delete` +### `paperless_correspondents_bulk_delete` Delete multiple correspondents. | Parameter | Type | Required | Default | Description | @@ -333,7 +333,7 @@ Delete multiple correspondents. ## Document Type Operations -### `paperless.document_types.list` +### `paperless_document_types_list` List all document types with pagination. | Parameter | Type | Required | Default | Description | @@ -344,7 +344,7 @@ List all document types with pagination. **Returns:** Paginated list of document types -### `paperless.document_types.get` +### `paperless_document_types_get` Get a document type by its ID. | Parameter | Type | Required | Description | @@ -353,7 +353,7 @@ Get a document type by its ID. **Returns:** Document type details -### `paperless.document_types.create` +### `paperless_document_types_create` Create a new document type. | Parameter | Type | Required | Default | Description | @@ -364,7 +364,7 @@ Create a new document type. **Returns:** Created document type -### `paperless.document_types.update` +### `paperless_document_types_update` Update an existing document type. | Parameter | Type | Required | Description | @@ -376,7 +376,7 @@ Update an existing document type. **Returns:** Updated document type -### `paperless.document_types.delete` +### `paperless_document_types_delete` Delete a document type. Requires explicit confirmation. | Parameter | Type | Required | Default | Description | @@ -386,7 +386,7 @@ Delete a document type. Requires explicit confirmation. **Returns:** Deletion status or dry-run preview -### `paperless.document_types.bulk_delete` +### `paperless_document_types_bulk_delete` Delete multiple document types. | Parameter | Type | Required | Default | Description | @@ -401,7 +401,7 @@ Delete multiple document types. ## Storage Path Operations -### `paperless.storage_paths.list` +### `paperless_storage_paths_list` List all storage paths with pagination. | Parameter | Type | Required | Default | Description | @@ -412,7 +412,7 @@ List all storage paths with pagination. **Returns:** Paginated list of storage paths -### `paperless.storage_paths.get` +### `paperless_storage_paths_get` Get a storage path by its ID. | Parameter | Type | Required | Description | @@ -421,7 +421,7 @@ Get a storage path by its ID. **Returns:** Storage path details -### `paperless.storage_paths.create` +### `paperless_storage_paths_create` Create a new storage path. | Parameter | Type | Required | Default | Description | @@ -433,7 +433,7 @@ Create a new storage path. **Returns:** Created storage path -### `paperless.storage_paths.update` +### `paperless_storage_paths_update` Update an existing storage path. | Parameter | Type | Required | Description | @@ -446,7 +446,7 @@ Update an existing storage path. **Returns:** Updated storage path -### `paperless.storage_paths.delete` +### `paperless_storage_paths_delete` Delete a storage path. Requires explicit confirmation. | Parameter | Type | Required | Default | Description | @@ -456,7 +456,7 @@ Delete a storage path. Requires explicit confirmation. **Returns:** Deletion status or dry-run preview -### `paperless.storage_paths.bulk_delete` +### `paperless_storage_paths_bulk_delete` Delete multiple storage paths. | Parameter | Type | Required | Default | Description | @@ -471,7 +471,7 @@ Delete multiple storage paths. ## Custom Field Operations -### `paperless.custom_fields.list` +### `paperless_custom_fields_list` List all custom field definitions with pagination. | Parameter | Type | Required | Default | Description | @@ -481,7 +481,7 @@ List all custom field definitions with pagination. **Returns:** Paginated list of custom field definitions -### `paperless.custom_fields.get` +### `paperless_custom_fields_get` Get a custom field definition by its ID. | Parameter | Type | Required | Description | @@ -490,7 +490,7 @@ Get a custom field definition by its ID. **Returns:** Custom field details -### `paperless.custom_fields.create` +### `paperless_custom_fields_create` Create a new custom field definition. | Parameter | Type | Required | Default | Description | @@ -513,7 +513,7 @@ Create a new custom field definition. **Returns:** Created custom field -### `paperless.custom_fields.update` +### `paperless_custom_fields_update` Update an existing custom field definition. | Parameter | Type | Required | Description | @@ -525,7 +525,7 @@ Update an existing custom field definition. **Returns:** Updated custom field -### `paperless.custom_fields.delete` +### `paperless_custom_fields_delete` Delete a custom field definition. Requires explicit confirmation. | Parameter | Type | Required | Default | Description | @@ -535,7 +535,7 @@ Delete a custom field definition. Requires explicit confirmation. **Returns:** Deletion status or dry-run preview -### `paperless.custom_fields.assign` +### `paperless_custom_fields_assign` Assign a custom field value to a document. | Parameter | Type | Required | Description |