fix(document-to-markdown): clamp page ranges, update descriptions, and improve tests

- Clamp pageStart/pageEnd to valid bounds to fix wrong page numbering
  when callers pass out-of-range values (e.g. pageStart: 0)
- Update MCP tool and REST endpoint descriptions to remove "using OCR"
  and note that capabilities depend on the configured provider
- Fix stale docstring: providerName default is "unpdf", not "mistral"
- Remove 2 duplicate tests in Provider Registry
- Add 3 edge case tests: pageStart-only, pageEnd-only, single-page PDF

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Jurij Skornik

package-lock.json

@@ -32,13 +32,15 @@
     "@mistralai/mistralai": "^1.3.0",
     "busboy": "^1.6.0",
     "sparqljs": "^3.7.3",
-    "undici": "^6.19.0"
+    "undici": "^6.19.0",
+    "unpdf": "^0.12.1"
   },
   "devDependencies": {
     "@dkg/eslint-config": "*",
     "@dkg/typescript-config": "*",
     "@types/busboy": "^1.5.4",
     "@types/sparqljs": "^3.1.12",
+    "pdf-lib": "^1.17.1",
     "tsup": "^8.5.0"
   }
 }

packages/plugin-dkg-essentials/package.json

@@ -29,6 +29,8 @@ export {
   isProviderAvailable,
   MistralProvider,
   createMistralProvider,
+  UnpdfProvider,
+  createUnpdfProvider,
 } from "./plugins/document-to-markdown";
 
 export default defineDkgPlugin((ctx, mcp, api) => {

packages/plugin-dkg-essentials/src/index.ts

@@ -2,11 +2,11 @@
  * Document to Markdown MCP Tool
  *
  * Converts PDF, DOCX, and PPTX documents to Markdown using configurable OCR providers.
- * Default provider: Mistral OCR.
+ * Default provider: unpdf (zero-config PDF text extraction).
  *
  * Environment variables:
- * - MISTRAL_API_KEY (required for Mistral provider)
- * - DOCUMENT_CONVERSION_PROVIDER (optional, default: "mistral")
+ * - DOCUMENT_CONVERSION_PROVIDER (optional, default: "unpdf")
+ * - MISTRAL_API_KEY (required when using Mistral provider)
  */
 
 import { Readable } from "stream";
@@ -44,6 +44,8 @@ export {
   isProviderAvailable,
   MistralProvider,
   createMistralProvider,
+  UnpdfProvider,
+  createUnpdfProvider,
 } from "./providers";
 
 // Re-export validation utilities
@@ -104,7 +106,7 @@ export function createDocumentToMarkdownPlugin(
         config?.providerName ??
         // eslint-disable-next-line turbo/no-undeclared-env-vars
         process.env.DOCUMENT_CONVERSION_PROVIDER ??
-        "mistral";
+        "unpdf";
 
       provider = createProvider(providerName);
     }
@@ -120,7 +122,8 @@ export function createDocumentToMarkdownPlugin(
         {
           summary: "Convert document to Markdown",
           description:
-            "Upload a PDF, DOCX, or PPTX file and convert it to Markdown using OCR. " +
+            "Upload a PDF, DOCX, or PPTX file and convert it to Markdown. " +
+            "Supported document types and image extraction capabilities depend on the configured provider. " +
             "Returns the extracted markdown content and any images stored in blob storage.",
           tag: "Documents",
           response: {
@@ -231,8 +234,9 @@ export function createDocumentToMarkdownPlugin(
       {
         title: "Document to Markdown",
         description:
-          "Convert PDF, DOCX, or PPTX documents to Markdown using OCR. " +
-          "Extracts text and images from documents. Use this as the first step when publishing documents to the DKG - " +
+          "Convert PDF, DOCX, or PPTX documents to Markdown. " +
+          "Supported document types and image extraction capabilities depend on the configured provider. " +
+          "Use this as the first step when publishing documents to the DKG - " +
           "the markdown output can then be transformed to JSON-LD and published using dkg-create.",
         inputSchema: {
           blobId: z
@@ -343,7 +347,7 @@ export function createDocumentToMarkdownPlugin(
 }
 
 /**
- * Default plugin export - uses Mistral provider.
- * For custom provider configuration, use createDocumentToMarkdownPlugin().
+ * Default plugin export - uses unpdf provider (zero-config).
+ * For Mistral OCR, use createDocumentToMarkdownPlugin({ providerName: "mistral" }).
  */
 export default createDocumentToMarkdownPlugin();

packages/plugin-dkg-essentials/src/plugins/document-to-markdown/index.ts

@@ -5,9 +5,11 @@
 
 import type { DocumentConversionProvider } from "../types";
 import { createMistralProvider } from "./mistral";
+import { createUnpdfProvider } from "./unpdf";
 
 // Re-export provider implementations
 export { MistralProvider, createMistralProvider } from "./mistral";
+export { UnpdfProvider, createUnpdfProvider } from "./unpdf";
 
 /**
  * Map of provider names to factory functions
@@ -17,12 +19,13 @@ const PROVIDER_FACTORIES: Record<
   (options?: Record<string, unknown>) => DocumentConversionProvider
 > = {
   mistral: (options) => createMistralProvider(options?.apiKey as string),
+  unpdf: () => createUnpdfProvider(),
 };
 
 /**
  * Default provider name
  */
-const DEFAULT_PROVIDER = "mistral";
+const DEFAULT_PROVIDER = "unpdf";
 
 /**
  * Get list of available provider names
@@ -41,7 +44,7 @@ export function isProviderAvailable(name: string): boolean {
 /**
  * Create a provider by name.
  *
- * @param name - Provider name (default: "mistral")
+ * @param name - Provider name (default: "unpdf")
  * @param options - Provider-specific options
  * @throws Error if provider is not found
  */
@@ -60,8 +63,8 @@ export function createProvider(
 }
 
 /**
- * Get the default provider (Mistral).
- * This is the most common use case - just get a working provider.
+ * Get the default provider (unpdf).
+ * This is the most common use case - just get a working provider with zero config.
  */
 export function getDefaultProvider(): DocumentConversionProvider {
   return createProvider(DEFAULT_PROVIDER);

packages/plugin-dkg-essentials/src/plugins/document-to-markdown/providers/index.ts

@@ -0,0 +1,77 @@
+/**
+ * unpdf provider for document-to-markdown conversion.
+ * Uses Mozilla pdf.js (via unpdf) to extract text from non-scanned PDFs.
+ * Zero-config — no API key required.
+ */
+
+import { extractText } from "unpdf";
+
+import type {
+  DocumentConversionProvider,
+  DocumentConversionOptions,
+  DocumentConversionOutput,
+} from "../types";
+import { getFileExtension, validateFileSize } from "../validation";
+
+const PROVIDER_NAME = "unpdf";
+
+/**
+ * unpdf provider for PDF text extraction.
+ * Supports .pdf files only — for .docx/.pptx or scanned PDFs, use Mistral.
+ */
+export class UnpdfProvider implements DocumentConversionProvider {
+  readonly name = PROVIDER_NAME;
+
+  async convert(
+    buffer: Buffer,
+    filename: string,
+    options?: DocumentConversionOptions,
+  ): Promise<DocumentConversionOutput> {
+    // Only PDF is supported — reject other formats with a helpful message
+    const ext = getFileExtension(filename);
+    if (ext !== ".pdf") {
+      throw new Error(
+        `The unpdf provider only supports .pdf files, got '${ext || "(no extension)"}'. ` +
+          `For .docx and .pptx support, use the Mistral provider ` +
+          `(set DOCUMENT_CONVERSION_PROVIDER=mistral and provide MISTRAL_API_KEY).`,
+      );
+    }
+
+    validateFileSize(buffer.length);
+
+    // Extract text from PDF using pdf.js
+    const { totalPages, text } = await extractText(new Uint8Array(buffer), {
+      mergePages: false,
+    });
+
+    // Clamp page range to valid bounds (1-indexed inputs, 0-indexed array)
+    const effectiveStart = Math.max(1, options?.pageStart ?? 1);
+    const effectiveEnd = Math.min(totalPages, options?.pageEnd ?? totalPages);
+
+    let pages = text;
+    if (options?.pageStart != null || options?.pageEnd != null) {
+      pages = text.slice(effectiveStart - 1, effectiveEnd);
+    }
+
+    // Format pages with separators
+    const markdown = pages
+      .map((pageText, i) => {
+        const pageNum = effectiveStart + i;
+        return `<!-- Page ${pageNum} -->\n\n${pageText}`;
+      })
+      .join("\n\n");
+
+    return {
+      markdown,
+      images: [],
+      pageCount: totalPages,
+    };
+  }
+}
+
+/**
+ * Create an unpdf provider instance. No configuration required.
+ */
+export function createUnpdfProvider(): UnpdfProvider {
+  return new UnpdfProvider();
+}

packages/plugin-dkg-essentials/src/plugins/document-to-markdown/providers/unpdf.ts

@@ -87,6 +87,6 @@ export interface DocumentConversionProvider {
 export interface DocumentConversionConfig {
   /** Provider to use for conversion (default: auto-detected) */
   provider?: DocumentConversionProvider;
-  /** Provider name to use if no provider instance given (default: "mistral") */
+  /** Provider name to use if no provider instance given (default: "unpdf") */
   providerName?: string;
 }