paperless-mcp

Implementation Reference

• src/tools/correspondents.ts:48-61 (registration)

  Primary registration of the 'get_correspondent' MCP tool, including input schema validation with Zod ({ id: z.number() }) and the handler function that fetches and enhances the correspondent data.

  server.tool(
    "get_correspondent",
    { id: z.number() },
    withErrorHandling(async (args, extra) => {
      if (!api) throw new Error("Please configure API connection first");
      const response = await api.getCorrespondent(args.id);
      const enhancedCorrespondent = enhanceMatchingAlgorithm(response);
      return {
        content: [
          { type: "text", text: JSON.stringify(enhancedCorrespondent) },
        ],
      };
    })
  );

• src/tools/correspondents.ts:51-60 (handler)

  The core handler function for the 'get_correspondent' tool. Validates API availability, retrieves the correspondent by ID via PaperlessAPI, enhances it with matching algorithm details, and returns formatted JSON content.

  withErrorHandling(async (args, extra) => {
    if (!api) throw new Error("Please configure API connection first");
    const response = await api.getCorrespondent(args.id);
    const enhancedCorrespondent = enhanceMatchingAlgorithm(response);
    return {
      content: [
        { type: "text", text: JSON.stringify(enhancedCorrespondent) },
      ],
    };
  })

• src/api/PaperlessAPI.ts:214-216 (helper)

  Helper method in PaperlessAPI class that performs the HTTP request to fetch a single correspondent by ID from the Paperless-ngx API.

  async getCorrespondent(id: number): Promise<Correspondent> {
    return this.request<Correspondent>(`/correspondents/${id}/`);
  }

• src/index.ts:71-71 (registration)

  Top-level call to register all correspondent-related tools, including 'get_correspondent', on the MCP server.

  registerCorrespondentTools(server, api);

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

  Zod input schema for the 'get_correspondent' tool, requiring a numeric 'id' parameter.

  { id: z.number() },