Metadata-Version: 2.5
Name: docsend2pdf-mcp
Version: 0.2.0
Summary: MCP server for converting DocSend documents to PDF via docsend2pdf.com
Author-email: Docsend2PDF <docsend2pdf@proton.me>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp<2.0.0,>=1.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# docsend2pdf-mcp

MCP server for converting DocSend documents to PDF via docsend2pdf.com

## Installation

Requires Python 3.10+.

```bash
pip install docsend2pdf-mcp
```

## Configuration

```json
{
    "mcpServers": {
        "docsend2pdf": {
            "command": "python",
            "args": ["-m", "docsend2pdf_mcp"],
            "env": {
                "DOCSEND2PDF_DOWNLOAD_DIR": "~/Downloads/docsend_pdfs"
            }
        }
    }
}
```

## Usage

- Convert: `"Convert this DocSend to PDF: https://docsend.com/view/abc123"`
- With password: `"Convert https://docsend.com/view/xyz789 (password: mypass)"`
- With email: `"Convert https://docsend.com/view/doc456 (email: user@example.com)"`
- Custom filename: `"Save https://docsend.com/view/doc789 as report.pdf"`

Most decks ask for an email. The agent should ask for an address you can read
before converting if you have not supplied one. The deck owner will see it.
Email remains optional for public documents. Password-protected documents need
`passcode`.

Both `docsend.com/view/...` and `docsend.com/v/...` document links work.
Space links (`/view/s/`) do not: provide the individual document link instead.

### Email verification

If DocSend sends a verification email, `convert_docsend` returns
`status: "email_verification_required"`, `session_id`, and `expires_at`.
Copy the link behind the **"Verify email address"** button **without opening it**,
then give it to the agent. The link is single-use.

The agent calls `submit_verification_link(session_id, verification_url)`. The MCP
server submits the link to the verification API, polls until the PDF is ready,
and saves it using the original custom filename, if any. Queued conversions are
also polled automatically.

Verification sessions are held in memory until expiry (normally 24 hours).
If the MCP server restarts, the session expires, or you already opened the email
link, start a new conversion for a fresh verification email.

### Results

Results retain the human-readable message and the `Saved to: <path>` line.
Every result also contains a fenced JSON block with `status`, `error_code`,
`retryable`, `recovery_action`, `task_id`, `session_id`, and `saved_path`.
Unavailable values are `null`. Successful conversions use `status: "completed"`;
failures use `"error"`. Verification handoffs also include `expires_at` and
the exact copying instruction.

API failures preserve `details.error_code`, `details.retryable`, and
`recovery_action` so agents can ask for missing email or credentials, restart
verification, or stop retrying a dead link. Errors remain text, not MCP
`isError` results, for compatibility with older clients.

## Features

- Password-protected documents
- Email-gated documents, including completion of email verification inside MCP
- Custom filenames, sanitized to stay inside the download directory
- Rate limiting (5 req/sec)
- Explicit blocking requests (`async: false`) with a versioned
  `DocSend2PDF-MCP/0.2.0` User-Agent
- Readable five-minute timeout errors

PDFs still default to `~/Downloads/docsend_pdfs`; override this with
`DOCSEND2PDF_DOWNLOAD_DIR`. Clients must be able to read that local path.

## Upgrading

0.2.0 keeps the existing `convert_docsend` arguments and requires Python 3.10+
and MCP 1.x. Users of `uvx docsend2pdf-mcp@latest` pick up the release on their
next client restart. Pinned pipx installations need an explicit upgrade:

```bash
pipx upgrade docsend2pdf-mcp
```

## Development

```bash
pip install -e ".[dev]"
python -m pytest
python -m build
```

`pyproject.toml` is the only packaging file. The package is split into
`api.py` (HTTP client, polling, verification sessions), `files.py` (PDF saving),
`server.py` (MCP tools), and `__main__.py` (stdio entry point).

The tracked unit suite (`tests/unit`) uses mock HTTP responses, temporary
download directories, and no live DocSend links or email. The build produces
both a wheel and an sdist. The sdist includes only package sources, unit tests,
and distribution metadata; anything else in the working tree is excluded.

## License

MIT
