fix(pdf-server): handle separated field/widget trees in extractFormSchema

pdfjs getFieldObjects() returns the full field-tree array. For PDFs with
a separated structure (pdf-lib, some authoring tools) the typed widget
sits at fields[1+] behind a typeless container at fields[0]; the previous
code only inspected fields[0] and skipped them all. Pick the first entry
with a non-empty type instead.

Makes the e2e forms.pdf fixture fully generated (no checked-in third-party
asset on the hot path); fw9.pdf stays as a unit-test fixture for the
hierarchical/XFA case.

Author: ochafik

examples/pdf-server/server.test.ts

@@ -4,9 +4,12 @@ import os from "node:os";
 import path from "node:path";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { getDocument } from "pdfjs-dist/legacy/build/pdf.mjs";
+import { PDFDocument } from "pdf-lib";
 import {
   createPdfCache,
   createServer,
+  extractFormSchema,
   validateUrl,
   isAncestorDir,
   allowedLocalFiles,
@@ -289,6 +292,84 @@ describe("PDF Cache with Timeouts", () => {
   // through manual testing or E2E tests.
 });
 
+describe("extractFormSchema field-tree handling", () => {
+  async function schemaFor(bytes: Uint8Array) {
+    const doc = await getDocument({ data: bytes }).promise;
+    try {
+      return await extractFormSchema(doc);
+    } finally {
+      doc.destroy();
+    }
+  }
+
+  it("handles pdf-lib separated field/widget structure", async () => {
+    const d = await PDFDocument.create();
+    const form = d.getForm();
+    d.addPage([612, 792]);
+    form
+      .createTextField("alpha")
+      .addToPage(d.getPage(0), { x: 50, y: 700, width: 200, height: 20 });
+    form
+      .createCheckBox("agree")
+      .addToPage(d.getPage(0), { x: 50, y: 660, width: 20, height: 20 });
+    form
+      .createDropdown("choice")
+      .addToPage(d.getPage(0), { x: 50, y: 620, width: 100, height: 20 });
+
+    const schema = await schemaFor(await d.save());
+    expect(schema).not.toBeNull();
+    expect(schema!.properties.alpha).toEqual({
+      type: "string",
+      title: "alpha",
+    });
+    expect(schema!.properties.agree).toEqual({
+      type: "boolean",
+      title: "agree",
+    });
+    expect(schema!.properties.choice.type).toBe("string");
+  });
+
+  it("handles fields with multiple widgets across pages", async () => {
+    const d = await PDFDocument.create();
+    const form = d.getForm();
+    d.addPage([612, 792]);
+    d.addPage([612, 792]);
+    const tf = form.createTextField("shared");
+    tf.addToPage(d.getPage(0), { x: 50, y: 700, width: 200, height: 20 });
+    tf.addToPage(d.getPage(1), { x: 50, y: 700, width: 200, height: 20 });
+
+    const schema = await schemaFor(await d.save());
+    expect(schema?.properties.shared).toEqual({
+      type: "string",
+      title: "shared",
+    });
+  });
+
+  it("skips container nodes and finds leaf fields (W-9 style)", async () => {
+    const bytes = fs.readFileSync(
+      path.join(__dirname, "../../tests/helpers/assets/fw9.pdf"),
+    );
+    const doc = await getDocument({ data: new Uint8Array(bytes) }).promise;
+    try {
+      const fo = (await doc.getFieldObjects()) as Record<string, unknown[]>;
+      // Container nodes (no leaf type) should not crash extraction
+      expect(fo["topmostSubform[0]"]).toBeDefined();
+      // Schema is null for W-9 (mechanical names), but extraction must not throw
+      const schema = await extractFormSchema(doc);
+      expect(schema).toBeNull();
+    } finally {
+      doc.destroy();
+    }
+  });
+
+  it("returns null when no AcroForm present", async () => {
+    const d = await PDFDocument.create();
+    d.addPage([612, 792]);
+    const schema = await schemaFor(await d.save());
+    expect(schema).toBeNull();
+  });
+});
+
 describe("validateUrl with MCP roots (allowedLocalDirs)", () => {
   const savedFiles = new Set(allowedLocalFiles);
   const savedDirs = new Set(allowedLocalDirs);

examples/pdf-server/server.ts

@@ -1039,7 +1039,7 @@ async function extractFormFieldInfo(
   return fields;
 }
 
-async function extractFormSchema(
+export async function extractFormSchema(
   pdfDoc: PDFDocumentProxy,
   fieldObjects?: Record<string, PdfJsFieldObject[]> | null,
 ): Promise<{
@@ -1063,7 +1063,11 @@ async function extractFormSchema(
 
   const properties: Record<string, PrimitiveSchemaDefinition> = {};
   for (const [name, fields] of Object.entries(fieldObjects)) {
-    const field = fields[0]; // first widget determines the type
+    // pdfjs returns the full field-tree array: for separated structures
+    // (pdf-lib) the typed widget is at [1+] behind a container at [0]; for
+    // merged/leaf entries (W-9, most authoring tools) it's at [0]. Pick the
+    // first entry that actually has a field type.
+    const field = fields.find((f) => f.type) ?? fields[0];
     if (!field.editable) continue;
 
     switch (field.type) {

tests/e2e/pdf-incremental-load.spec.ts

@@ -79,12 +79,14 @@ test.describe("PDF Server — incremental loading", () => {
   }) => {
     await displayPdf(page, `${rangeServer.baseUrl}/forms.pdf`);
     const sc = await readStructuredContent(page);
-    // formSchema may be null when field names are mechanical (W-9 uses
-    // f1_01[0]-style names), but formFields (bounding boxes) is always
-    // populated when the PDF has an AcroForm.
-    const fields = sc.formFields as unknown[] | undefined;
-    expect(fields).toBeDefined();
-    expect(fields!.length).toBeGreaterThanOrEqual(10);
+    const fields = sc.formFields as Array<{ name: string }> | undefined;
+    expect(fields?.map((f) => f.name).sort()).toEqual([
+      "city",
+      "email",
+      "name",
+      "notes",
+      "phone",
+    ]);
   });
 
   test("display_pdf on a no-forms PDF fetches <30% of the file", async ({
@@ -93,7 +95,7 @@ test.describe("PDF Server — incremental loading", () => {
     const fileSize = rangeServer.fileSizes["/noforms.pdf"];
     await displayPdf(page, `${rangeServer.baseUrl}/noforms.pdf`);
     const sc = await readStructuredContent(page);
-    expect(sc.formSchema ?? null).toBeNull();
+    expect(sc.formFields).toBeUndefined();
 
     const { totalBytesServed } = rangeServer.stats();
     // Guard against display_pdf downloading the whole file for form analysis.

tests/helpers/range-counting-server.ts

@@ -5,10 +5,9 @@
  */
 import https from "node:https";
 import { execFileSync } from "node:child_process";
-import fs, { mkdtempSync, readFileSync } from "node:fs";
+import { mkdtempSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import type { AddressInfo } from "node:net";
 import { PDFDocument, StandardFonts } from "pdf-lib";
 
@@ -96,13 +95,16 @@ function makeRandomJpeg(len: number): Uint8Array {
 }
 
 async function buildFormsPdf(): Promise<Uint8Array> {
-  // pdf-lib generates a separated field/widget tree that pdfjs's
-  // getFieldObjects() reports without type/editable, so extractFormSchema
-  // skips them. Use a real-world form PDF (IRS W-9) instead — it's the same
-  // asset the server is expected to handle in production.
-  return fs.readFileSync(
-    path.join(path.dirname(fileURLToPath(import.meta.url)), "assets/fw9.pdf"),
-  );
+  const doc = await PDFDocument.create();
+  const form = doc.getForm();
+  for (let p = 0; p < 2; p++) doc.addPage([612, 792]);
+  const [page1] = doc.getPages();
+  const fields = ["name", "email", "phone", "city", "notes"];
+  fields.forEach((name, i) => {
+    const f = form.createTextField(name);
+    f.addToPage(page1, { x: 100, y: 650 - i * 60, width: 300, height: 24 });
+  });
+  return doc.save();
 }
 
 function generateSelfSignedCert(): { key: Buffer; cert: Buffer } {