@modelcontextprotocol/server-pdf 1.2.1 → 1.3.0

package/dist/src/commands.d.ts

@@ -0,0 +1,81 @@
+/**
+ * PdfCommand — the wire protocol between server and viewer.
+ *
+ * The server enqueues these via the `interact` tool; the viewer polls
+ * `poll_pdf_commands` and receives them as `structuredContent.commands`.
+ *
+ * This file is the single source of truth for the command shape. Both
+ * `server.ts` (which enqueues) and `mcp-app.ts` (which consumes) import
+ * from here — a new command variant must be added exactly once.
+ *
+ * Uses `import type` so neither side pulls pdf-lib into its bundle.
+ */
+import type { PdfAnnotationDef } from "./pdf-annotations.js";
+/** Single form field assignment, as sent by `fill_form`. */
+export interface FormFieldFill {
+    name: string;
+    value: string | boolean;
+}
+/**
+ * Partial annotation update: `id` + `type` pin the target, everything
+ * else is optional. Server validates shape; viewer merges into existing.
+ */
+export type PdfAnnotationPatch = Partial<PdfAnnotationDef> & {
+    id: string;
+    type: PdfAnnotationDef["type"];
+};
+/** Page range for text/screenshot extraction. Omitted bound = open-ended. */
+export interface PageInterval {
+    start?: number;
+    end?: number;
+}
+/**
+ * Commands the server can send to the viewer via the poll queue.
+ * Adding a variant here means adding a `case` in both the server's
+ * `interact` handler (to enqueue) and the viewer's `processCommands`
+ * (to execute).
+ */
+export type PdfCommand = {
+    type: "navigate";
+    page: number;
+} | {
+    type: "search";
+    query: string;
+} | {
+    type: "find";
+    query: string;
+} | {
+    type: "search_navigate";
+    matchIndex: number;
+} | {
+    type: "zoom";
+    scale: number;
+} | {
+    type: "add_annotations";
+    annotations: PdfAnnotationDef[];
+} | {
+    type: "update_annotations";
+    annotations: PdfAnnotationPatch[];
+} | {
+    type: "remove_annotations";
+    ids: string[];
+} | {
+    type: "highlight_text";
+    id: string;
+    query: string;
+    page?: number;
+    color?: string;
+    content?: string;
+} | {
+    type: "fill_form";
+    fields: FormFieldFill[];
+} | {
+    type: "get_pages";
+    requestId: string;
+    intervals: PageInterval[];
+    getText: boolean;
+    getScreenshots: boolean;
+} | {
+    type: "file_changed";
+    mtimeMs: number;
+};

package/dist/src/pdf-annotations.d.ts

@@ -0,0 +1,186 @@
+/**
+ * PDF Annotation Helpers
+ *
+ * Pure functions for annotation persistence (diff-based model),
+ * color conversion, and PDF annotation dict creation using pdf-lib.
+ *
+ * The diff-based model stores only changes relative to the PDF's
+ * native annotations: additions, removals, and modifications.
+ * This keeps localStorage small and preserves round-trip fidelity.
+ */
+import { PDFDocument } from "pdf-lib";
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface AnnotationBase {
+    id: string;
+    page: number;
+}
+export interface HighlightAnnotation extends AnnotationBase {
+    type: "highlight";
+    rects: Rect[];
+    color?: string;
+    content?: string;
+}
+export interface UnderlineAnnotation extends AnnotationBase {
+    type: "underline";
+    rects: Rect[];
+    color?: string;
+}
+export interface StrikethroughAnnotation extends AnnotationBase {
+    type: "strikethrough";
+    rects: Rect[];
+    color?: string;
+}
+export interface NoteAnnotation extends AnnotationBase {
+    type: "note";
+    x: number;
+    y: number;
+    content: string;
+    color?: string;
+}
+export interface RectangleAnnotation extends AnnotationBase {
+    type: "rectangle";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    color?: string;
+    fillColor?: string;
+    rotation?: number;
+}
+export interface CircleAnnotation extends AnnotationBase {
+    type: "circle";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    color?: string;
+    fillColor?: string;
+}
+export interface LineAnnotation extends AnnotationBase {
+    type: "line";
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    color?: string;
+}
+export interface FreetextAnnotation extends AnnotationBase {
+    type: "freetext";
+    x: number;
+    y: number;
+    content: string;
+    fontSize?: number;
+    color?: string;
+}
+export interface StampAnnotation extends AnnotationBase {
+    type: "stamp";
+    x: number;
+    y: number;
+    label: string;
+    color?: string;
+    rotation?: number;
+}
+export interface ImageAnnotation extends AnnotationBase {
+    type: "image";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    imageData?: string;
+    imageUrl?: string;
+    mimeType?: string;
+    rotation?: number;
+    aspect?: "preserve" | "ignore";
+}
+export type PdfAnnotationDef = HighlightAnnotation | UnderlineAnnotation | StrikethroughAnnotation | NoteAnnotation | RectangleAnnotation | CircleAnnotation | LineAnnotation | FreetextAnnotation | StampAnnotation | ImageAnnotation;
+/**
+ * Convert annotation coordinates from model space (top-left origin, Y↓)
+ * to internal PDF space (bottom-left origin, Y↑).
+ *
+ * Call this when receiving coordinates from the model via add/update_annotations.
+ */
+export declare function convertFromModelCoords(def: PdfAnnotationDef, pageHeight: number): PdfAnnotationDef;
+/**
+ * Convert annotation coordinates from internal PDF space (bottom-left origin, Y↑)
+ * to model space (top-left origin, Y↓).
+ *
+ * Call this when presenting coordinates to the model (e.g. in context strings).
+ */
+export declare function convertToModelCoords(def: PdfAnnotationDef, pageHeight: number): PdfAnnotationDef;
+/**
+ * Represents changes relative to the PDF's native annotations.
+ * Only this diff is stored in localStorage, keeping it small.
+ */
+export interface AnnotationDiff {
+    /** Annotations created by the user (not in the original PDF) */
+    added: PdfAnnotationDef[];
+    /** PDF annotation ref strings that the user deleted */
+    removed: string[];
+    /** Form field values the user filled in */
+    formFields: Record<string, string | boolean>;
+}
+/** Create an empty diff */
+export declare function emptyDiff(): AnnotationDiff;
+/** Check if a diff has any changes */
+export declare function isDiffEmpty(diff: AnnotationDiff): boolean;
+/** Serialize diff to JSON string for localStorage */
+export declare function serializeDiff(diff: AnnotationDiff): string;
+/** Deserialize diff from JSON string. Returns empty diff on error. */
+export declare function deserializeDiff(json: string): AnnotationDiff;
+/**
+ * Merge PDF-native annotations with user diff to produce the final annotation set.
+ *
+ * @param pdfAnnotations - Annotations imported from the PDF file
+ * @param diff - User's local changes (additions, removals)
+ * @returns Merged annotation list
+ */
+export declare function mergeAnnotations(pdfAnnotations: PdfAnnotationDef[], diff: AnnotationDiff): PdfAnnotationDef[];
+/**
+ * Compute a diff given the PDF-native annotations and the current full set.
+ *
+ * @param pdfAnnotations - Original annotations from the PDF
+ * @param currentAnnotations - Current full annotation set (after user edits)
+ * @param formFields - Current form field values
+ * @returns The diff to persist
+ */
+export declare function computeDiff(pdfAnnotations: PdfAnnotationDef[], currentAnnotations: PdfAnnotationDef[], formFields: Map<string, string | boolean>, baselineFormFields?: Map<string, string | boolean>): AnnotationDiff;
+/**
+ * Parse a CSS color string to normalized RGB values (0-1 range).
+ * Supports hex (#rgb, #rrggbb, #rrggbbaa) and rgb()/rgba() notation.
+ */
+export declare function cssColorToRgb(color: string): {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+/** Default colors for each annotation type */
+export declare function defaultColor(type: PdfAnnotationDef["type"]): string;
+/**
+ * Add proper PDF annotation objects to a pdf-lib PDFDocument.
+ * Creates /Type /Annot dictionaries with correct /Subtype for each annotation type.
+ * These are real PDF annotations, editable in Acrobat/Preview.
+ */
+export declare function addAnnotationDicts(pdfDoc: PDFDocument, annotations: PdfAnnotationDef[]): Promise<void>;
+/**
+ * Build annotated PDF bytes from the original document.
+ * Applies user annotations and form fills, returns Uint8Array of the new PDF.
+ */
+export declare function buildAnnotatedPdfBytes(pdfBytes: Uint8Array, annotations: PdfAnnotationDef[], formFields: Map<string, string | boolean>): Promise<Uint8Array>;
+/**
+ * Convert a single PDF.js annotation object to our PdfAnnotationDef format.
+ * Returns null for unsupported annotation types.
+ */
+export declare function importPdfjsAnnotation(ann: any, pageNum: number, index: number): PdfAnnotationDef | null;
+/**
+ * Convert base64 string to Uint8Array.
+ */
+export declare function base64ToUint8Array(base64: string): Uint8Array;
+/**
+ * Convert Uint8Array to base64 string.
+ */
+export declare function uint8ArrayToBase64(bytes: Uint8Array): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelcontextprotocol/server-pdf",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "type": "module",
   "description": "MCP server for loading and extracting text from PDF files with chunked pagination and interactive viewer",
   "repository": {
@@ -16,7 +16,7 @@
   "scripts": {
     "build": "tsc --noEmit && cross-env INPUT=mcp-app.html vite build && tsc -p tsconfig.server.json && bun build server.ts --outdir dist --target node --external pdfjs-dist && bun build main.ts --outfile dist/index.js --target node --external \"./server.js\" --external pdfjs-dist --banner \"#!/usr/bin/env node\"",
     "watch": "cross-env INPUT=mcp-app.html vite build --watch",
-    "serve": "bun --watch main.ts",
+    "serve": "bun --watch main.ts --enable-interact",
     "serve:stdio": "bun main.ts --stdio",
     "start": "cross-env NODE_ENV=development npm run build && npm run serve",
     "start:stdio": "cross-env NODE_ENV=development npm run build 1>&2 && npm run serve:stdio",
@@ -28,6 +28,7 @@
     "@modelcontextprotocol/sdk": "^1.24.0",
     "cors": "^2.8.5",
     "express": "^5.1.0",
+    "pdf-lib": "^1.17.1",
     "pdfjs-dist": "^5.0.0",
     "zod": "^4.1.13"
   },