# PDF Inspector MCP Server (HTTP)

Classify PDFs (text-based vs scanned vs image vs mixed), extract text, and
convert to clean Markdown — over a Streamable HTTP MCP transport. Powered by
the native [`@firecrawl/pdf-inspector`](https://github.com/firecrawl/pdf-inspector)
library (Rust via napi-rs).

**No API key. No external API. Pure local compute.** Because the server is
remote, every tool takes a PDF as either a `url` (downloaded server-side) or a
base64 `base64` string — not a local file path.

## Tools (6)

| Tool | What it does |
|------|--------------|
| `classify_pdf` | Fast classify: `TextBased` / `Scanned` / `ImageBased` / `Mixed` + confidence + OCR pages |
| `detect_pdf` | Fast metadata (type, page count, OCR pages) — no markdown |
| `process_pdf` | Full parse: type, text, and Markdown with layout metadata |
| `pdf_to_markdown` | Per-page clean Markdown + table/column/OCR layout flags |
| `extract_text` | Plain text extraction |
| `extract_text_with_positions` | Positioned text items with font / bbox metadata |

Each tool accepts `{ url }` **or** `{ base64 }`. `process_pdf`,
`pdf_to_markdown`, and `extract_text_with_positions` also accept an optional
`pages` array (0-indexed) to restrict output.

### The classify-before-OCR gate

`classify_pdf` is the cheap front door for any document pipeline: it decides
whether a PDF is real text or a scan in ~tens of milliseconds, so an agent can
skip OCR entirely on native PDFs and only fall back to OCR / a vision model on
the pages that actually need it (`pagesNeedingOcr`).

## Auth

Dual-mode, matching the AgenticLedger fleet convention for credential-less
MCPs. The server stores nothing:

- **Bearer passthrough** — `Authorization: Bearer <any-token>`. Any non-empty
  token is accepted (access control only).
- **OAuth 2.0 Client Credentials** — `POST /oauth/token` with
  `client_id=pdf-inspector&client_secret=<any>&grant_type=client_credentials`,
  then use the returned `mcp_`-prefixed token as the Bearer.

## Client config

```json
{
  "mcpServers": {
    "pdf-inspector": {
      "type": "streamable-http",
      "url": "https://pdfinspectormcp.agenticledger.ai/mcp",
      "headers": { "Authorization": "Bearer pdf" }
    }
  }
}
```

## Hosting note

`@firecrawl/pdf-inspector` ships prebuilt native binaries as optional
dependencies (`linux-x64-gnu`, `darwin-arm64`, `win32-x64-msvc`). Railway's
linux-x64 build pulls the `linux-x64-gnu` prebuilt automatically via
`npm install` — **no Rust toolchain / Docker image needed.**

## Local dev

```bash
npm install
npm run build
npm start           # serves on :3100
```

Deployed to Railway (project **FinanceMCPs**) from
`agenticledger/pdf-inspector-mcp-http`.