paperless-mcp

Implementation Reference

• src/tools/tags.ts:65-77 (handler)

  Handler function for the create_tag tool: validates API connection, calls api.createTag(args), enhances the tag with matching algorithm info, and returns JSON text content.

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

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

  Zod input schema for create_tag tool: requires name, optional color (hex), match, and matching_algorithm (0-6).

  {
    name: z.string(),
    color: z
      .string()
      .regex(/^#[0-9A-Fa-f]{6}$/)
      .optional(),
    match: z.string().optional(),
    matching_algorithm: z
      .number()
      .int()
      .min(0)
      .max(6)
      .optional()
      .describe(MATCHING_ALGORITHM_DESCRIPTION),
  },

• src/tools/tags.ts:48-78 (registration)

  MCP tool registration for create_tag using server.tool with schema and wrapped handler.

  server.tool(
    "create_tag",
    {
      name: z.string(),
      color: z
        .string()
        .regex(/^#[0-9A-Fa-f]{6}$/)
        .optional(),
      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 tag = await api.createTag(args);
      const enhancedTag = enhanceMatchingAlgorithm(tag);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(enhancedTag),
          },
        ],
      };
    })
  );

• src/api/PaperlessAPI.ts:184-189 (helper)

  PaperlessAPI.createTag method: POST request to /tags/ with JSON data, called by the tool handler.

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