paperless-mcp

Implementation Reference

• src/tools/correspondents.ts:27-46 (handler)

  The core handler logic for the 'list_correspondents' tool. It validates the API connection, builds a query string from input parameters, fetches the list of correspondents using PaperlessAPI, enhances each result with matching algorithm details, and returns the paginated response as JSON-formatted text content.

    withErrorHandling(async (args, extra) => {
      if (!api) throw new Error("Please configure API connection first");
      const queryString = buildQueryString(args);
      const response = await api.getCorrespondents(queryString);
      const enhancedResults = enhanceMatchingAlgorithmArray(
        response.results || []
      );
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              ...response,
              results: enhancedResults,
            }),
          },
        ],
      };
    })
  );

• src/tools/correspondents.ts:19-26 (schema)

  Zod schema for input validation of the 'list_correspondents' tool, supporting optional pagination (page, page_size), name-based filtering (icontains, iendswith, iexact, istartswith), and ordering parameters.

    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/correspondents.ts:17-46 (registration)

  Registration of the 'list_correspondents' MCP tool on the server, including the tool name, input schema, and inline handler wrapped in error handling middleware.

    "list_correspondents",
    {
      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, extra) => {
      if (!api) throw new Error("Please configure API connection first");
      const queryString = buildQueryString(args);
      const response = await api.getCorrespondents(queryString);
      const enhancedResults = enhanceMatchingAlgorithmArray(
        response.results || []
      );
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              ...response,
              results: enhancedResults,
            }),
          },
        ],
      };
    })
  );