list_tags
Retrieve and manage all tags in your Paperless-NGX instance efficiently. Use filters like name, ordering, and pagination to fetch and cache tags, reducing redundant API calls during sessions.
Instructions
List all tags. IMPORTANT: When a user query may refer to a tag or document type, you should fetch all tags and all document types up front (with a large enough page_size), cache them for the session, and search locally for matches by name or slug before making further API calls. This reduces redundant requests and handles ambiguity between tags and document types efficiently.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name__icontains | No | ||
| name__iendswith | No | ||
| name__iexact | No | ||
| name__istartswith | No | ||
| ordering | No | ||
| page | No | ||
| page_size | No |
Implementation Reference
- src/tools/tags.ts:25-46 (handler)Executes the list_tags tool: builds query string from input args, fetches tags via PaperlessAPI from /tags/ endpoint, enhances results with matching algorithm details, and returns structured JSON response as text content.
withErrorHandling(async (args = {}) => { if (!api) throw new Error("Please configure API connection first"); const queryString = buildQueryString(args); const tagsResponse = await api.request( `/tags/${queryString ? `?${queryString}` : ""}` ); const enhancedResults = enhanceMatchingAlgorithmArray( tagsResponse.results || [] ); return { content: [ { type: "text", text: JSON.stringify({ ...tagsResponse, results: enhancedResults, }), }, ], }; }) ); - src/tools/tags.ts:16-24 (schema)Zod schema defining optional input parameters for list_tags: pagination (page, page_size), name-based filters (icontains, iendswith, iexact, istartswith), and ordering.
{ page: z.number().optional(), page_size: z.number().optional(), name__icontains: z.string().optional(), name__iendswith: z.string().optional(), name__iexact: z.string().optional(), name__istartswith: z.string().optional(), ordering: z.string().optional(), }, - src/tools/tags.ts:13-46 (registration)Registers the list_tags tool on the MCP server, providing name, detailed description advising on caching strategy, input schema, and handler function.
server.tool( "list_tags", "List all tags. IMPORTANT: When a user query may refer to a tag or document type, you should fetch all tags and all document types up front (with a large enough page_size), cache them for the session, and search locally for matches by name or slug before making further API calls. This reduces redundant requests and handles ambiguity between tags and document types efficiently.", { page: z.number().optional(), page_size: z.number().optional(), name__icontains: z.string().optional(), name__iendswith: z.string().optional(), name__iexact: z.string().optional(), name__istartswith: z.string().optional(), ordering: z.string().optional(), }, withErrorHandling(async (args = {}) => { if (!api) throw new Error("Please configure API connection first"); const queryString = buildQueryString(args); const tagsResponse = await api.request( `/tags/${queryString ? `?${queryString}` : ""}` ); const enhancedResults = enhanceMatchingAlgorithmArray( tagsResponse.results || [] ); return { content: [ { type: "text", text: JSON.stringify({ ...tagsResponse, results: enhancedResults, }), }, ], }; }) ); - src/index.ts:70-70 (registration)Top-level invocation of registerTagTools function within the main MCP server setup, which registers the list_tags tool among others.
registerTagTools(server, api);