# DreamPDF PDF Engine + MCP Server

Two small Node packages, published separately, usually used together:

| Package | What it is |
|---|---|
| [`pdf_server`](./pdf_server) (`@dreampdf/pdf-server`) | The underlying AcroForm extract/fill/export engine, built on [`pdf-lib`](https://pdf-lib.js.org/). Usable standalone via its CLI. |
| [`pdf_mcp`](./pdf_mcp) (`@dreampdf/pdf-mcp`) | A local-only [MCP](https://modelcontextprotocol.io) server exposing that engine to AI agents — Claude Code, Claude Desktop, or any other MCP client. |

**Local-only. No API key. No third-party network calls.** Every tool runs
against a PDF on your own filesystem, over stdio; nothing is uploaded
anywhere.

## What it can do

- Open a PDF form, read its AcroForm fields, fill them, export the result
- Build a brand-new **fillable** PDF form from a declarative field list — no
  source PDF needed
- Extract and search text (fast path), or run full layout analysis
  (headings/paragraphs/tables/figures) when the optional self-hosted
  `layout_service` companion is running
- Read and edit detected text/layout blocks, then re-export
- A redaction-safe **reconstruct** export profile that rebuilds a PDF from
  extracted content plus current field values, rather than editing the
  original page content in place

See [`pdf_mcp/README.md`](./pdf_mcp/README.md) for the full tool reference,
workflow examples, and known limitations.

## Quickstart

```bash
npm install -g @dreampdf/pdf-mcp
claude mcp add dreampdf-pdf -- dreampdf-pdf-mcp
```

```
pdf_open({ path: "/absolute/path/to/form.pdf" })
pdf_set_fields({ path: "...", fields: { "<field_id>": "value" } })
pdf_export({ path: "...", outPath: "/absolute/path/to/filled.pdf" })
```

## Why this exists

This engine is the headless counterpart to
[DreamPDF](https://github.com/homezloco/dreampdf), a mobile-first PDF form
editor: the app is for a human tapping through a form on a phone, this is
for an agent doing the same thing programmatically. Installing DreamPDF Pro
additionally unlocks `pdf_get_profile` — an agent can then autofill forms
from your saved name/contact/signature profile.

## Development

This is an npm workspace with two packages:

```bash
npm install
npm test --workspaces
```

`pdf_mcp` depends on `pdf_server` via a normal published semver range; there
is no build step.

## License

Apache-2.0 — see [LICENSE](./LICENSE). Copyright Canweb.net.