paperless-mcp

Implementation Reference

• src/tools/correspondents.ts:63-86 (registration)

  Registration of the MCP 'create_correspondent' tool, including inline input schema and handler function that invokes PaperlessAPI.createCorrespondent and enhances the response with matching algorithm details.

  server.tool(
    "create_correspondent",
    {
      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 response = await api.createCorrespondent(args);
      const enhancedCorrespondent = enhanceMatchingAlgorithm(response);
      return {
        content: [
          { type: "text", text: JSON.stringify(enhancedCorrespondent) },
        ],
      };
    })
  );

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

  Zod input schema for the create_correspondent tool: requires name, optional match and matching_algorithm (0-6).

  {
    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:76-86 (handler)

  Handler executes the tool: checks API, calls createCorrespondent on PaperlessAPI, enhances response, returns JSON as text content.

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

• src/api/PaperlessAPI.ts:218-225 (helper)

  PaperlessAPI helper method: POST request to /correspondents/ with correspondent data to create a new correspondent.

  async createCorrespondent(
    data: Partial<Correspondent>
  ): Promise<Correspondent> {
    return this.request<Correspondent>("/correspondents/", {
      method: "POST",
      body: JSON.stringify(data),
    });
  }