Metadata-Version: 2.4
Name: pdf-agent-kit
Version: 0.1.3
Summary: Extract structured JSON from PDFs via CLI, Python API, or MCP server.
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=2.0.0; python_version >= "3.10"
Requires-Dist: httpx>=0.28.0
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.0; extra == "dev"

# pdf-agent-kit

`pdf-agent-kit` is a local adapter package for the pdf-agent-kit cloud API.

- MCP entrypoint: `pdf-agent-kit` (stdio, one tool: `extract_pdf_to_json`)
- CLI entrypoint: `pdf-edit`
- Python import: `from pdf_agent_kit import extract`

The package is thin by design: it reads a local PDF file and forwards it to the cloud API.
If `PDF_EDITOR_API_KEY` is present, it uses your paid account. If not, it auto-creates a guest session with free credits.

## Quickstart For Agents

```python
from pdf_agent_kit import extract

result = extract("/absolute/path/to/file.pdf", pages="1-3")
```

## Install

```bash
pip install pdf-agent-kit
```

or:

```bash
uvx pdf-agent-kit
```

## Python Compatibility

- CLI (`pdf-edit`) works on Python `3.9+`.
- MCP server (`pdf-agent-kit`) requires Python `3.10+` because `fastmcp` is only installed on 3.10+.
- If your agent is pinned to older Python, use `pdf-edit` directly or use `uvx pdf-agent-kit` for MCP runtime.

## Auth Modes

```bash
export PDF_EDITOR_API_KEY="sk_live_..."
```

If no key is set, `pdf-agent-kit` uses guest mode automatically.

You can also persist your API key locally (avoids exporting every session):

```bash
pdf-edit setup --save-api-key
```

When guest credits run out, the CLI/MCP response points users to [pdfagentkit.com/dashboard](https://pdfagentkit.com/dashboard) to register and continue.

## MCP Tool

Tool name: `extract_pdf_to_json`

Parameters:

- `file_path` (required)
- `pages` (optional, default `all`)
- `filename` (optional override)

Returns API JSON: metadata + per-page text + usage stats.

## CLI

```bash
pdf-edit extract /path/to/file.pdf
pdf-edit extract /path/to/file.pdf --pages "1-5"
pdf-edit extract /path/to/file.pdf -o /path/to/output.json
pdf-edit status
pdf-edit setup --save-api-key
```

CLI contract:

- success JSON goes to stdout
- errors go to stderr
- exit code `0` success, `1` user error, `2` server/network error
- `extract` prints a concise usage summary to stderr (`pages + remaining credits`)

## Setup

`pdf-edit setup`:

1. Reads `PDF_EDITOR_API_KEY` (or prompts once if missing)
2. Verifies key with `/v1/account/status`
3. Patches MCP config for:
   - Claude Desktop
   - Cursor
   - VS Code
4. Tries to add Claude Code integration via `claude mcp add-json`
5. Optionally saves API key to `~/.pdf-agent-kit/config.json` with `--save-api-key`

Injected server entry:

```json
{
  "mcpServers": {
    "pdf-agent-kit": {
      "command": "uvx",
      "args": ["pdf-agent-kit"],
      "env": {
        "PDF_EDITOR_API_KEY": "sk_live_..."
      }
    }
  }
}
```

## Development

```bash
pip install -e .[dev]
pytest -q
```
