paperless-mcp

Implementation Reference

• src/tools/correspondents.ts:102-112 (handler)

  Handler function that extracts id and data from args, calls PaperlessAPI.updateCorrespondent, enhances the response with matching algorithm details, and returns it as JSON text content.

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

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

  Zod schema for input validation of the update_correspondent tool: requires id and name, optional match and matching_algorithm.

  {
    id: z.number(),
    name: z.string(),
    match: z.string().optional(),
    matching_algorithm: z
      .number()
      .int()
      .min(0)
      .max(6)
      .optional()
      .describe(MATCHING_ALGORITHM_DESCRIPTION),
  },

• src/tools/correspondents.ts:88-113 (registration)

  MCP server.tool registration for update_correspondent, specifying name, input schema, and handler wrapped with error handling.

  server.tool(
    "update_correspondent",
    {
      id: z.number(),
      name: z.string(),
      match: z.string().optional(),
      matching_algorithm: z
        .number()
        .int()
        .min(0)
        .max(6)
        .optional()
        .describe(MATCHING_ALGORITHM_DESCRIPTION),
    },
    withErrorHandling(async (args, extra) => {
      if (!api) throw new Error("Please configure API connection first");
      const { id, ...data } = args;
      const response = await api.updateCorrespondent(id, data);
      const enhancedCorrespondent = enhanceMatchingAlgorithm(response);
      return {
        content: [
          { type: "text", text: JSON.stringify(enhancedCorrespondent) },
        ],
      };
    })
  );

• src/api/PaperlessAPI.ts:227-235 (helper)

  Low-level API method in PaperlessAPI class that sends PUT request to update correspondent via HTTP.

  async updateCorrespondent(
    id: number,
    data: Partial<Correspondent>
  ): Promise<Correspondent> {
    return this.request<Correspondent>(`/correspondents/${id}/`, {
      method: "PUT",
      body: JSON.stringify(data),
    });
  }