paperless-mcp

Implementation Reference

• src/tools/documents.ts:195-257 (handler)

  Core handler logic for the 'get_document' tool: fetches document by ID, enriches with readable names for related entities (correspondents, types, tags, custom fields), and returns as JSON.

  withErrorHandling(async (args, extra) => {
    if (!api) throw new Error("Please configure API connection first");
    const doc = await api.getDocument(args.id);
    const [correspondents, documentTypes, tags, customFields] =
      await Promise.all([
        api.getCorrespondents(),
        api.getDocumentTypes(),
        api.getTags(),
        api.getCustomFields(),
      ]);
    const correspondentMap = new Map(
      (correspondents.results || []).map((c) => [c.id, c.name])
    );
    const documentTypeMap = new Map(
      (documentTypes.results || []).map((dt) => [dt.id, dt.name])
    );
    const tagMap = new Map(
      (tags.results || []).map((tag) => [tag.id, tag.name])
    );
    const customFieldMap = new Map(
      (customFields.results || []).map((cf) => [cf.id, cf.name])
    );
    const docWithNames = {
      ...doc,
      correspondent: doc.correspondent
        ? {
            id: doc.correspondent,
            name:
              correspondentMap.get(doc.correspondent) ||
              String(doc.correspondent),
          }
        : null,
      document_type: doc.document_type
        ? {
            id: doc.document_type,
            name:
              documentTypeMap.get(doc.document_type) ||
              String(doc.document_type),
          }
        : null,
      tags: Array.isArray(doc.tags)
        ? doc.tags.map((tagId) => ({
            id: tagId,
            name: tagMap.get(tagId) || String(tagId),
          }))
        : doc.tags,
      custom_fields: Array.isArray(doc.custom_fields)
        ? doc.custom_fields.map((field) => ({
            field: field.field,
            name: customFieldMap.get(field.field) || String(field.field),
            value: field.value,
          }))
        : doc.custom_fields,
    };
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(docWithNames),
        },
      ],
    };
  })

• src/tools/documents.ts:192-194 (schema)

  Input schema for 'get_document' tool: requires a numeric 'id' parameter.

  {
    id: z.number(),
  },

• src/tools/documents.ts:190-258 (registration)

  Registers the 'get_document' tool on the MCP server with its schema and handler function.

  server.tool(
    "get_document",
    {
      id: z.number(),
    },
    withErrorHandling(async (args, extra) => {
      if (!api) throw new Error("Please configure API connection first");
      const doc = await api.getDocument(args.id);
      const [correspondents, documentTypes, tags, customFields] =
        await Promise.all([
          api.getCorrespondents(),
          api.getDocumentTypes(),
          api.getTags(),
          api.getCustomFields(),
        ]);
      const correspondentMap = new Map(
        (correspondents.results || []).map((c) => [c.id, c.name])
      );
      const documentTypeMap = new Map(
        (documentTypes.results || []).map((dt) => [dt.id, dt.name])
      );
      const tagMap = new Map(
        (tags.results || []).map((tag) => [tag.id, tag.name])
      );
      const customFieldMap = new Map(
        (customFields.results || []).map((cf) => [cf.id, cf.name])
      );
      const docWithNames = {
        ...doc,
        correspondent: doc.correspondent
          ? {
              id: doc.correspondent,
              name:
                correspondentMap.get(doc.correspondent) ||
                String(doc.correspondent),
            }
          : null,
        document_type: doc.document_type
          ? {
              id: doc.document_type,
              name:
                documentTypeMap.get(doc.document_type) ||
                String(doc.document_type),
            }
          : null,
        tags: Array.isArray(doc.tags)
          ? doc.tags.map((tagId) => ({
              id: tagId,
              name: tagMap.get(tagId) || String(tagId),
            }))
          : doc.tags,
        custom_fields: Array.isArray(doc.custom_fields)
          ? doc.custom_fields.map((field) => ({
              field: field.field,
              name: customFieldMap.get(field.field) || String(field.field),
              value: field.value,
            }))
          : doc.custom_fields,
      };
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(docWithNames),
          },
        ],
      };
    })
  );

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

  Top-level call to register all document tools, including 'get_document', on the MCP server.

  registerDocumentTools(server, api);

• src/api/PaperlessAPI.ts:147-149 (helper)

  Helper API method called by the tool handler to retrieve the raw document data from Paperless-NGX server.

  async getDocument(id: number): Promise<Document> {
    return this.request<Document>(`/documents/${id}/`);
  }