feat(assets): PDF text extraction via unpdf

[aliasunder]

What does this PR do?

Adds PDF text extraction to vault_read_asset via unpdf — a MIT-licensed, zero-dep, serverless-first PDF.js bundle. When a PDF is read, its text content is extracted and returned as a text content block, just like .svg, .json, and other text formats.

Scanned/image-only PDFs that yield no extractable text throw a structured error naming the file, its size, and page count — guiding the caller toward the limitation rather than returning empty content silently.

Key implementation details:

• unpdf's extractText requires Uint8Array input (rejects Buffer), so the dispatch creates a zero-copy view via the shared ArrayBuffer
• mergePages: true returns all pages as a single string
• Output goes through the existing assertTextWithinCap guard
• The .pdf case in the unsupported-type error is removed; .pdf added to the readable-types list in that error message
• Tool descriptions updated to list PDF as a supported format

Type of change

• New MCP tool
• Bug fix
• Refactoring
• Documentation
• CI / workflow change
• Infrastructure (SST, Docker)
• Other: New asset type support (PDF text extraction)

Checklist

• npm test passes
• npm run lint passes
• npm run prettier:check passes
• npm run build succeeds
• New MCP tools follow the naming and description conventions in AGENTS.md
• README or ARCHITECTURE.md updated (if user-facing behavior changed)

Note: No new tools — this extends the existing vault_read_asset tool's dispatch. One pre-existing flaky test (fit-image-to-byte-budget alpha WebP timeout) is unrelated to this change.

Summary by CodeRabbit

• New Features

  • Added PDF text extraction for readable PDF assets.
  • Added clear errors for scanned or image-only PDFs without extractable text.
  • Added configurable limits for asset input size and image output size.

• Documentation

  • Updated asset-handling guidance to describe PDF support, extraction behavior, and size-limit settings.
  • Updated supported asset types to include PDF files.

[sourcery-ai]

Sorry @aliasunder, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	unpdf@​1.6.2

View full report

[umm-actually]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Handle PDF extraction errors gracefully The extractText call is not wrapped in a try/catch. If unpdf throws (e.g., on a corrupted or password-protected PDF), the error propagates as an unhandled rejection, bypassing the structured error path and potentially crashing the tool handler. Wrap the call in a try/catch and re-throw a descriptive error that includes the path and original cause. src/vault-mcp/vault-operations/asset-operations.ts [137-146] -const extracted = await extractText(pdfData, { mergePages: true }) +let extracted: Awaited<ReturnType<typeof extractText>> +try { + extracted = await extractText(pdfData, { mergePages: true }) +} catch (cause) { + throw new Error( + `PDF extraction failed: "${path}" exists (${asset.bytes} bytes) but could not be read`, + { cause }, + ) +} const text = typeof extracted.text === "string" ? extracted.text : "" if (!text.trim()) { throw new Error( `PDF has no extractable text: "${path}" exists ` + `(${asset.bytes} bytes, ${extracted.totalPages} pages) but ` + `contains no text content — it may be a scanned document or ` + `image-only PDF`, ) } Suggestion importance[1-10]: 5 __ Why: Adding error handling for extractText provides a more descriptive error message, but the existing code already throws errors and the suggestion is a minor improvement.	Low
General	Tighten error assertion to prevent false passes The test for whitespace-only PDF content uses .rejects.toThrow("PDF has no extractable text") without a more specific assertion. If the code throws a different error (e.g., a generic "text output too large" or an unrelated exception), this test would still pass because the error message contains the substring. Use an exact match or a regex anchored to the start of the message to ensure the correct error is thrown. src/vault-mcp/vault-operations/tests/asset-operations.test.ts [80-97] it("throws for PDFs with only whitespace content", async () => { mockedReadAsset.mockResolvedValue({ buffer: Buffer.from("fake-pdf"), bytes: 1_000, extension: ".pdf", }) mockedExtractText.mockResolvedValue({ totalPages: 1, text: " \n\t \n ", }) await expect( assetOperations.readAssetContent( { ...defaultParams, path: "empty.pdf" }, logger, ), - ).rejects.toThrow("PDF has no extractable text") + ).rejects.toThrow(/^PDF has no extractable text/) }) Suggestion importance[1-10]: 5 __ Why: Tightening the error assertion to a regex anchored at the start improves test specificity and prevents false passes, a minor but valid enhancement.	Low

[aliasunder]

@CodeRabbit review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 0e898cc5-d23a-4cbf-b3a1-27694459a05d

📥 Commits

Reviewing files that changed from the base of the PR and between 29e3325 and d955522.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (10)

• ARCHITECTURE.md
• DOCKERHUB.md
• README.md
• package.json
• src/vault-mcp/config.ts
• src/vault-mcp/mcp-core/__tests__/pdf-fixture.ts
• src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts
• src/vault-mcp/mcp-core/tools/asset-tools.ts
• src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts
• src/vault-mcp/vault-operations/asset-operations.ts

---

📝 Walkthrough

Walkthrough

Changes

PDF assets are now read through unpdf, with extracted text validation, updated tool messaging, integration coverage, and documentation for PDF behavior and asset size limits.

PDF asset support

Layer / File(s)	Summary
PDF extraction and validation package.json, src/vault-mcp/vault-operations/..., src/vault-mcp/mcp-core/__tests__/...	Adds unpdf extraction, empty-text and output-size errors, extraction failure propagation, and PDF test fixtures and coverage.
Tool behavior and integration src/vault-mcp/mcp-core/tools/asset-tools.ts, src/vault-mcp/mcp-core/__tests__/tool-definitions.test.ts, src/vault-mcp/vault-operations/__tests__/asset-operations.test.ts	Marks PDFs as readable in tool descriptions and verifies extracted text and updated readable-type errors.
Documentation and asset limits ARCHITECTURE.md, README.md, DOCKERHUB.md, src/vault-mcp/config.ts	Documents PDF extraction, scanned/image-only PDF errors, and asset/image output byte limits.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• aliasunder/vault-cortex#272: Related test adjustments in tool-definitions.test.ts, including readable-type expectations.

Suggested labels: Review effort 3/5

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding PDF text extraction support via unpdf.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/vault-bootstrap-setup-nfpewt

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install timed out. The project may have too many dependencies for the sandbox.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}