branded-pdf-service

A self-hosted, agent-friendly Markdown-to-PDF rendering service with pluggable brand templates.

[](https://github.com/tsayles/branded-pdf-service/actions/workflows/ci.yml) [](LICENSE)

---

Primary users: AI agents and automation pipelines.

This service is designed to be called by agentic workers -- Claude, GPT-based agents, LangChain pipelines, CI/CD workflows -- that need to produce branded, print-ready PDFs from Markdown without human involvement. Every design decision optimizes for machine-friendly operation:

• Simple JSON request body -- no multipart forms, no file uploads for rendering
• Predictable error responses with HTTP status codes agents can branch on
• Bearer token auth -- one env var, one header, done
• MCP tool interface -- native tool discovery for MCP-compatible agents (stdio transport, python -m app.mcp_server)
• No browser, no GUI, no polling -- POST /render returns the PDF bytes directly

Human operators configure and maintain the service; agents are the primary callers at runtime.

---

# Build the image
docker build -t branded-pdf-service:latest .

# Run (open mode — no auth)
docker run -d \
  --name branded-pdf \
  -p 8100:8000 \
  -v ./brands/acme-corp:/brands/acme-corp \
  branded-pdf-service:latest

Render a document (open mode — no auth header needed):

curl -s -X POST http://localhost:8100/render \
  -H "Content-Type: application/json" \
  -d '{"brand":"acme-corp","markdown":"# Hello World\n\nThis is a test."}' \
  -o output.pdf

# With auth enabled (PDF_API_KEYS set)
curl -s -X POST http://localhost:8100/render \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{"brand":"acme-corp","markdown":"# Hello World\n\nThis is a test."}' \
  -