@shuji-bonji/pdf-reader-mcp 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,226 @@
+/**
+ * pdf-reader-mcp shared type definitions
+ */
+/** Metadata extracted from a PDF document */
+export interface PdfMetadata {
+    title: string | null;
+    author: string | null;
+    subject: string | null;
+    keywords: string | null;
+    creator: string | null;
+    producer: string | null;
+    creationDate: string | null;
+    modificationDate: string | null;
+    pageCount: number;
+    pdfVersion: string | null;
+    isLinearized: boolean;
+    isEncrypted: boolean;
+    isTagged: boolean;
+    hasSignatures: boolean;
+    fileSize: number;
+}
+/** A single page's extracted text */
+export interface PageText {
+    page: number;
+    text: string;
+}
+/** A search match within a PDF */
+export interface SearchMatch {
+    page: number;
+    lineIndex: number;
+    text: string;
+    contextBefore: string;
+    contextAfter: string;
+}
+/** Search results response */
+export interface SearchResult {
+    query: string;
+    totalMatches: number;
+    matches: SearchMatch[];
+    truncated: boolean;
+}
+/** An extracted image from a PDF page */
+export interface ExtractedImage {
+    page: number;
+    index: number;
+    width: number;
+    height: number;
+    colorSpace: string;
+    bitsPerComponent: number;
+    dataBase64: string;
+}
+/** Result of image extraction including detected vs extracted counts */
+export interface ImageExtractionResult {
+    images: ExtractedImage[];
+    detectedCount: number;
+    extractedCount: number;
+    skippedCount: number;
+}
+/** Summary report of a PDF document */
+export interface PdfSummary {
+    filePath: string;
+    metadata: PdfMetadata;
+    textPreview: string;
+    imageCount: number;
+    hasText: boolean;
+}
+/** Catalog entry info */
+export interface CatalogEntry {
+    key: string;
+    type: string;
+    value: string;
+}
+/** Page tree statistics */
+export interface PageTreeInfo {
+    totalPages: number;
+    mediaBoxSamples: Array<{
+        page: number;
+        width: number;
+        height: number;
+    }>;
+}
+/** Object statistics */
+export interface ObjectStats {
+    totalObjects: number;
+    streamCount: number;
+    byType: Record<string, number>;
+}
+/** inspect_structure output */
+export interface StructureAnalysis {
+    catalog: CatalogEntry[];
+    pageTree: PageTreeInfo;
+    objectStats: ObjectStats;
+    isEncrypted: boolean;
+    pdfVersion: string | null;
+}
+/** Tag tree node */
+export interface TagNode {
+    role: string;
+    children: TagNode[];
+    contentCount: number;
+}
+/** inspect_tags output */
+export interface TagsAnalysis {
+    isTagged: boolean;
+    rootTag: TagNode | null;
+    maxDepth: number;
+    totalElements: number;
+    roleCounts: Record<string, number>;
+}
+/** Font information */
+export interface FontInfo {
+    name: string;
+    type: string;
+    encoding: string | null;
+    isEmbedded: boolean;
+    isSubset: boolean;
+    pagesUsed: number[];
+}
+/** inspect_fonts output */
+export interface FontsAnalysis {
+    fonts: FontInfo[];
+    totalFontCount: number;
+    embeddedCount: number;
+    subsetCount: number;
+    pagesScanned: number;
+}
+/** Annotation information */
+export interface AnnotationInfo {
+    subtype: string;
+    page: number;
+    rect: number[] | null;
+    contents: string | null;
+    author: string | null;
+    modificationDate: string | null;
+    hasAppearance: boolean;
+}
+/** inspect_annotations output */
+export interface AnnotationsAnalysis {
+    totalAnnotations: number;
+    bySubtype: Record<string, number>;
+    byPage: Record<number, number>;
+    annotations: AnnotationInfo[];
+    hasLinks: boolean;
+    hasForms: boolean;
+    hasMarkup: boolean;
+}
+/** Signature field information */
+export interface SignatureFieldInfo {
+    fieldName: string;
+    isSigned: boolean;
+    signerName: string | null;
+    reason: string | null;
+    location: string | null;
+    contactInfo: string | null;
+    signingTime: string | null;
+    filter: string | null;
+    subFilter: string | null;
+}
+/** inspect_signatures output */
+export interface SignaturesAnalysis {
+    totalFields: number;
+    signedCount: number;
+    unsignedCount: number;
+    fields: SignatureFieldInfo[];
+    note: string;
+}
+/** Severity level for validation issues */
+export type ValidationSeverity = 'error' | 'warning' | 'info';
+/** A single validation issue */
+export interface ValidationIssue {
+    severity: ValidationSeverity;
+    code: string;
+    message: string;
+    details?: string;
+}
+/** validate_tagged output */
+export interface TaggedValidation {
+    isTagged: boolean;
+    totalChecks: number;
+    passed: number;
+    failed: number;
+    warnings: number;
+    issues: ValidationIssue[];
+    summary: string;
+}
+/** validate_metadata output */
+export interface MetadataValidation {
+    totalChecks: number;
+    passed: number;
+    failed: number;
+    warnings: number;
+    issues: ValidationIssue[];
+    metadata: {
+        hasTitle: boolean;
+        hasAuthor: boolean;
+        hasSubject: boolean;
+        hasKeywords: boolean;
+        hasCreator: boolean;
+        hasProducer: boolean;
+        hasCreationDate: boolean;
+        hasModificationDate: boolean;
+        pdfVersion: string | null;
+        isTagged: boolean;
+    };
+    summary: string;
+}
+/** Diff entry for structure comparison */
+export interface StructureDiffEntry {
+    property: string;
+    file1Value: string;
+    file2Value: string;
+    status: 'match' | 'differ';
+}
+/** compare_structure output */
+export interface StructureComparison {
+    file1: string;
+    file2: string;
+    diffs: StructureDiffEntry[];
+    fontComparison: {
+        onlyInFile1: string[];
+        onlyInFile2: string[];
+        inBoth: string[];
+    };
+    summary: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * pdf-reader-mcp shared type definitions
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/utils/batch-processor.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Batch processing utility for large PDFs.
+ *
+ * Processes pages in configurable batches to balance parallelism
+ * with memory usage. Within each batch, pages are processed in
+ * parallel using Promise.all. Batches run sequentially to avoid
+ * excessive memory consumption on large documents.
+ */
+/** Default batch size — balances parallelism and memory */
+export declare const DEFAULT_BATCH_SIZE = 10;
+/**
+ * Process an array of items in parallel batches.
+ *
+ * @param items       Array of items to process (e.g., page numbers).
+ * @param processor   Async function that processes a single item and returns a result.
+ * @param batchSize   Number of items to process concurrently in each batch.
+ * @returns           Array of results in the same order as the input items.
+ *
+ * @example
+ * ```ts
+ * const pageTexts = await processInBatches(
+ *   [1, 2, 3, ..., 200],
+ *   async (pageNum) => {
+ *     const page = await doc.getPage(pageNum);
+ *     return extractPageText(page);
+ *   },
+ *   10, // 10 pages at a time
+ * );
+ * ```
+ */
+export declare function processInBatches<T, R>(items: T[], processor: (item: T) => Promise<R>, batchSize?: number): Promise<R[]>;
+/**
+ * Process items in parallel batches and reduce into a single value.
+ *
+ * Useful when each item produces a partial result that must be merged
+ * (e.g., per-page image counts summed into a total).
+ *
+ * @param items       Array of items to process.
+ * @param processor   Async function that processes a single item.
+ * @param reducer     Function that merges two results into one.
+ * @param initial     Initial value for the reduction.
+ * @param batchSize   Number of items to process concurrently in each batch.
+ * @returns           The fully reduced result.
+ *
+ * @example
+ * ```ts
+ * const totalImages = await processAndReduce(
+ *   pageNumbers,
+ *   async (pageNum) => {
+ *     const page = await doc.getPage(pageNum);
+ *     const ops = await page.getOperatorList();
+ *     return ops.fnArray.filter(op => op === OPS.paintImageXObject).length;
+ *   },
+ *   (sum, count) => sum + count,
+ *   0,
+ * );
+ * ```
+ */
+export declare function processAndReduce<T, R>(items: T[], processor: (item: T) => Promise<R>, reducer: (acc: R, current: R) => R, initial: R, batchSize?: number): Promise<R>;
+//# sourceMappingURL=batch-processor.d.ts.map

package/dist/utils/batch-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-processor.d.ts","sourceRoot":"","sources":["../../src/utils/batch-processor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,2DAA2D;AAC3D,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,CAAC,EACzC,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAClC,SAAS,GAAE,MAA2B,GACrC,OAAO,CAAC,CAAC,EAAE,CAAC,CAWd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,CAAC,EACzC,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAClC,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC,EAClC,OAAO,EAAE,CAAC,EACV,SAAS,GAAE,MAA2B,GACrC,OAAO,CAAC,CAAC,CAAC,CAGZ"}

package/dist/utils/batch-processor.js

@@ -0,0 +1,72 @@
+/**
+ * Batch processing utility for large PDFs.
+ *
+ * Processes pages in configurable batches to balance parallelism
+ * with memory usage. Within each batch, pages are processed in
+ * parallel using Promise.all. Batches run sequentially to avoid
+ * excessive memory consumption on large documents.
+ */
+/** Default batch size — balances parallelism and memory */
+export const DEFAULT_BATCH_SIZE = 10;
+/**
+ * Process an array of items in parallel batches.
+ *
+ * @param items       Array of items to process (e.g., page numbers).
+ * @param processor   Async function that processes a single item and returns a result.
+ * @param batchSize   Number of items to process concurrently in each batch.
+ * @returns           Array of results in the same order as the input items.
+ *
+ * @example
+ * ```ts
+ * const pageTexts = await processInBatches(
+ *   [1, 2, 3, ..., 200],
+ *   async (pageNum) => {
+ *     const page = await doc.getPage(pageNum);
+ *     return extractPageText(page);
+ *   },
+ *   10, // 10 pages at a time
+ * );
+ * ```
+ */
+export async function processInBatches(items, processor, batchSize = DEFAULT_BATCH_SIZE) {
+    const results = [];
+    const effectiveBatchSize = Math.max(1, batchSize);
+    for (let i = 0; i < items.length; i += effectiveBatchSize) {
+        const batch = items.slice(i, i + effectiveBatchSize);
+        const batchResults = await Promise.all(batch.map(processor));
+        results.push(...batchResults);
+    }
+    return results;
+}
+/**
+ * Process items in parallel batches and reduce into a single value.
+ *
+ * Useful when each item produces a partial result that must be merged
+ * (e.g., per-page image counts summed into a total).
+ *
+ * @param items       Array of items to process.
+ * @param processor   Async function that processes a single item.
+ * @param reducer     Function that merges two results into one.
+ * @param initial     Initial value for the reduction.
+ * @param batchSize   Number of items to process concurrently in each batch.
+ * @returns           The fully reduced result.
+ *
+ * @example
+ * ```ts
+ * const totalImages = await processAndReduce(
+ *   pageNumbers,
+ *   async (pageNum) => {
+ *     const page = await doc.getPage(pageNum);
+ *     const ops = await page.getOperatorList();
+ *     return ops.fnArray.filter(op => op === OPS.paintImageXObject).length;
+ *   },
+ *   (sum, count) => sum + count,
+ *   0,
+ * );
+ * ```
+ */
+export async function processAndReduce(items, processor, reducer, initial, batchSize = DEFAULT_BATCH_SIZE) {
+    const results = await processInBatches(items, processor, batchSize);
+    return results.reduce(reducer, initial);
+}
+//# sourceMappingURL=batch-processor.js.map

package/dist/utils/batch-processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-processor.js","sourceRoot":"","sources":["../../src/utils/batch-processor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,2DAA2D;AAC3D,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAU,EACV,SAAkC,EAClC,YAAoB,kBAAkB;IAEtC,MAAM,OAAO,GAAQ,EAAE,CAAC;IACxB,MAAM,kBAAkB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAElD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,kBAAkB,EAAE,CAAC;QAC1D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,kBAAkB,CAAC,CAAC;QACrD,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;QAC7D,OAAO,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,CAAC;IAChC,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAU,EACV,SAAkC,EAClC,OAAkC,EAClC,OAAU,EACV,YAAoB,kBAAkB;IAEtC,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IACpE,OAAO,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC"}

package/dist/utils/error-handler.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Unified error handling for pdf-reader-mcp
+ */
+export declare class PdfReaderError extends Error {
+    readonly code: string;
+    readonly suggestion?: string | undefined;
+    constructor(message: string, code: string, suggestion?: string | undefined);
+}
+/**
+ * Handle errors and return user-friendly messages with actionable suggestions.
+ */
+export declare function handleError(error: unknown): string;
+/**
+ * Validate that a file path points to a PDF.
+ *
+ * Security checks:
+ * - Path must be non-empty
+ * - Path must be absolute (prevents relative path traversal)
+ * - Path must not contain `..` segments after normalization
+ * - Path must have a `.pdf` extension
+ */
+export declare function validatePdfPath(filePath: string): void;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/utils/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../src/utils/error-handler.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,qBAAa,cAAe,SAAQ,KAAK;aAGrB,IAAI,EAAE,MAAM;aACZ,UAAU,CAAC,EAAE,MAAM;gBAFnC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,YAAA;CAKtC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAyClD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAiCtD"}

package/dist/utils/error-handler.js

@@ -0,0 +1,76 @@
+/**
+ * Unified error handling for pdf-reader-mcp
+ */
+import { isAbsolute, normalize } from 'node:path';
+export class PdfReaderError extends Error {
+    code;
+    suggestion;
+    constructor(message, code, suggestion) {
+        super(message);
+        this.code = code;
+        this.suggestion = suggestion;
+        this.name = 'PdfReaderError';
+    }
+}
+/**
+ * Handle errors and return user-friendly messages with actionable suggestions.
+ */
+export function handleError(error) {
+    if (error instanceof PdfReaderError) {
+        let msg = `Error: ${error.message}`;
+        if (error.suggestion) {
+            msg += `\n\nSuggestion: ${error.suggestion}`;
+        }
+        return msg;
+    }
+    if (error instanceof Error) {
+        const message = error.message;
+        // File not found
+        if (message.includes('ENOENT') || message.includes('no such file')) {
+            return 'Error: File not found. Please check the file path is correct and the file exists.';
+        }
+        // Permission denied
+        if (message.includes('EACCES') || message.includes('permission denied')) {
+            return 'Error: Permission denied. Please check file permissions.';
+        }
+        // Invalid PDF
+        if (message.includes('Invalid PDF') || message.includes('PDF header not found')) {
+            return 'Error: The file does not appear to be a valid PDF. Please check the file is not corrupted.';
+        }
+        // Encrypted PDF
+        if (message.includes('password') || message.includes('encrypted')) {
+            return 'Error: This PDF is password-protected. Encrypted PDFs are not currently supported.';
+        }
+        // File too large
+        if (message.includes('too large') || message.includes('MAX_FILE_SIZE')) {
+            return 'Error: File exceeds the 50MB size limit. Try splitting the PDF into smaller parts.';
+        }
+        return `Error: ${message}`;
+    }
+    return `Error: An unexpected error occurred: ${String(error)}`;
+}
+/**
+ * Validate that a file path points to a PDF.
+ *
+ * Security checks:
+ * - Path must be non-empty
+ * - Path must be absolute (prevents relative path traversal)
+ * - Path must not contain `..` segments after normalization
+ * - Path must have a `.pdf` extension
+ */
+export function validatePdfPath(filePath) {
+    if (!filePath) {
+        throw new PdfReaderError('File path is required.', 'MISSING_PATH', 'Provide a valid file path to a PDF document.');
+    }
+    if (!isAbsolute(filePath)) {
+        throw new PdfReaderError('File path must be absolute.', 'RELATIVE_PATH', 'Provide an absolute file path (e.g., /home/user/document.pdf).');
+    }
+    const normalized = normalize(filePath);
+    if (normalized.includes('..')) {
+        throw new PdfReaderError('Path traversal is not allowed.', 'PATH_TRAVERSAL', 'Provide a direct absolute path without ".." segments.');
+    }
+    if (!normalized.toLowerCase().endsWith('.pdf')) {
+        throw new PdfReaderError(`Expected a .pdf file, got: ${filePath}`, 'INVALID_EXTENSION', 'Ensure the file has a .pdf extension.');
+    }
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/utils/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../src/utils/error-handler.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAElD,MAAM,OAAO,cAAe,SAAQ,KAAK;IAGrB;IACA;IAHlB,YACE,OAAe,EACC,IAAY,EACZ,UAAmB;QAEnC,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAQ;QACZ,eAAU,GAAV,UAAU,CAAS;QAGnC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,YAAY,cAAc,EAAE,CAAC;QACpC,IAAI,GAAG,GAAG,UAAU,KAAK,CAAC,OAAO,EAAE,CAAC;QACpC,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YACrB,GAAG,IAAI,mBAAmB,KAAK,CAAC,UAAU,EAAE,CAAC;QAC/C,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAE9B,iBAAiB;QACjB,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;YACnE,OAAO,mFAAmF,CAAC;QAC7F,CAAC;QAED,oBAAoB;QACpB,IAAI,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC;YACxE,OAAO,0DAA0D,CAAC;QACpE,CAAC;QAED,cAAc;QACd,IAAI,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC;YAChF,OAAO,4FAA4F,CAAC;QACtG,CAAC;QAED,gBAAgB;QAChB,IAAI,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;YAClE,OAAO,oFAAoF,CAAC;QAC9F,CAAC;QAED,iBAAiB;QACjB,IAAI,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;YACvE,OAAO,oFAAoF,CAAC;QAC9F,CAAC;QAED,OAAO,UAAU,OAAO,EAAE,CAAC;IAC7B,CAAC;IAED,OAAO,wCAAwC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACjE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,cAAc,CACtB,wBAAwB,EACxB,cAAc,EACd,8CAA8C,CAC/C,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,cAAc,CACtB,6BAA6B,EAC7B,eAAe,EACf,gEAAgE,CACjE,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,cAAc,CACtB,gCAAgC,EAChC,gBAAgB,EAChB,uDAAuD,CACxD,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,cAAc,CACtB,8BAA8B,QAAQ,EAAE,EACxC,mBAAmB,EACnB,uCAAuC,CACxC,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/utils/formatter.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Response formatting utilities for Markdown and JSON output.
+ */
+import type { AnnotationsAnalysis, FontsAnalysis, MetadataValidation, PageText, PdfMetadata, PdfSummary, SearchResult, SignaturesAnalysis, StructureAnalysis, StructureComparison, TaggedValidation, TagsAnalysis } from '../types.js';
+/**
+ * Truncate text to CHARACTER_LIMIT with a notice.
+ */
+export declare function truncateIfNeeded(text: string): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * Format metadata as Markdown.
+ */
+export declare function formatMetadataMarkdown(meta: PdfMetadata): string;
+/**
+ * Format page texts as Markdown.
+ */
+export declare function formatPageTextsMarkdown(pages: PageText[]): string;
+/**
+ * Format search results as Markdown.
+ */
+export declare function formatSearchResultMarkdown(result: SearchResult): string;
+/**
+ * Format summary as Markdown.
+ */
+export declare function formatSummaryMarkdown(summary: PdfSummary): string;
+/**
+ * Format structure analysis as Markdown.
+ */
+export declare function formatStructureMarkdown(analysis: StructureAnalysis): string;
+/**
+ * Format tags analysis as Markdown.
+ */
+export declare function formatTagsMarkdown(analysis: TagsAnalysis): string;
+/**
+ * Format fonts analysis as Markdown.
+ */
+export declare function formatFontsMarkdown(analysis: FontsAnalysis): string;
+/**
+ * Format annotations analysis as Markdown.
+ */
+export declare function formatAnnotationsMarkdown(analysis: AnnotationsAnalysis): string;
+/**
+ * Format signatures analysis as Markdown.
+ */
+export declare function formatSignaturesMarkdown(analysis: SignaturesAnalysis): string;
+/**
+ * Format file size in human-readable form.
+ */
+export declare function formatFileSize(bytes: number): string;
+/**
+ * Format tagged validation results as Markdown.
+ */
+export declare function formatTaggedValidationMarkdown(result: TaggedValidation): string;
+/**
+ * Format metadata validation results as Markdown.
+ */
+export declare function formatMetadataValidationMarkdown(result: MetadataValidation): string;
+/**
+ * Format structure comparison results as Markdown.
+ */
+export declare function formatCompareStructureMarkdown(result: StructureComparison): string;
+//# sourceMappingURL=formatter.d.ts.map

package/dist/utils/formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../../src/utils/formatter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EACV,mBAAmB,EACnB,aAAa,EACb,kBAAkB,EAClB,QAAQ,EACR,WAAW,EACX,UAAU,EACV,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EAEnB,gBAAgB,EAChB,YAAY,EACb,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAWnF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CA6BhE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,CAQjE;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAsBvE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAyBjE;AAID;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAqC3E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CA0BjE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAwBnE;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,CAgC/E;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,MAAM,CA6B7E;AAID;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIpD;AA4BD;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAuB/E;AAED;;GAEG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CA2CnF;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAqClF"}