paperless-mcp

Implementation Reference

• src/tools/documentTypes.ts:51-62 (registration)

  Registers the 'get_document_type' MCP tool with input schema {id: z.number()} and handler that fetches the document type via API and enhances the matching algorithm field.

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

• src/tools/documentTypes.ts:54-61 (handler)

  The handler function for get_document_type tool: checks API, requests /document_types/{id}/, enhances response, returns JSON text content.

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

• src/tools/documentTypes.ts:53-53 (schema)

  Input schema for get_document_type: requires 'id' as number.

  { id: z.number() },

• src/api/utils.ts:20-32 (helper)

  Helper function used in the handler to enrich the document type's matching_algorithm field with a human-readable name.

  export function enhanceMatchingAlgorithm<
    T extends { matching_algorithm: MatchingAlgorithm }
  >(obj: T): T & { matching_algorithm: NamedItem } {
    return {
      ...obj,
      matching_algorithm: {
        id: obj.matching_algorithm,
        name:
          MATCHING_ALGORITHM_OPTIONS[obj.matching_algorithm] ||
          String(obj.matching_algorithm),
      },
    };
  }

• src/api/types.ts:131-143 (schema)

  TypeScript interface defining the structure of a DocumentType object, used in responses.

  export interface DocumentType {
    id: number;
    slug: string;
    name: string;
    match: string;
    matching_algorithm: MatchingAlgorithm;
    is_insensitive: boolean;
    document_count: number;
    last_correspondence: string;
    owner: number | null;
    permissions: Record<string, unknown>;
    user_can_change: boolean;
  }