Knuckles-Team/stirlingpdf-agent

## CLI or API | MCP | Agent
> Documentation — Installation, deployment, usage across the MCP, API, and CLI
> interfaces, and guidance for provisioning the Stirling PDF service are maintained in
> the official documentation.
## 📚 Table of Contents
Overview
Key Features
Installation
Quick Start & Usage Examples
MCP Server Mode
Available MCP Tools
MCP Configuration Examples
Agent Mode
Running the Agent CLI
Docker Compose Orchestration
Environment Variables Reference
Security & Governance
Developer & Contribute Guidelines
Documentation
## Overview
Stirling PDF Agent is a production-grade Agent and Model Context Protocol (MCP) server designed to interface directly with Stirling PDF via REST APIs. It provides smooth capability to manipulate, edit, and overlay PDFs (e.g. adding watermarks) programmatically or using large language models.
## Key Features
Consolidated Action-Routed MCP Tools: Minimizes token overhead and eliminates tool bloat in LLM contexts by grouping methods into optimized, togglable tool modules.
Enterprise-Grade Security: Complete support for Eunomia policies, OIDC token delegation, and granular execution context tracking.
Integrated Graph Agent: Built-in Pydantic AI agent supporting the Agent Control Protocol (ACP) and standard Web interfaces (AG-UI).
Native Telemetry & Tracing: Out-of-the-box OpenTelemetry exports and native Langfuse tracing.
## Installation
Pick the extra that matches what the operator want to run:
| Extra | Installs | Use when |
| stirlingpdf-agent[mcp] | Connector-focused MCP server (scion-sdk[mcp] — FastMCP/FastAPI + epistemic-graph[full]) | The operator only run the MCP server (smallest install / image) |
| stirlingpdf-agent[agent] | Agent runtime (scion-sdk[agent-runtime,logfire] — model orchestration + epistemic-graph[full]) | The operator run the integrated agent |
| stirlingpdf-agent[all] | Everything (mcp + agent + logfire) | Development / both surfaces |
bash
# Connector-focused MCP server (includes the shared graph engine)
uv pip install "stirlingpdf-agent[mcp]"
# Agent runtime (adds model orchestration to the shared graph engine)
uv pip install "stirlingpdf-agent[agent]"
# Everything (development)
uv pip install "stirlingpdf-agent[all]" # or: python -m pip install "stirlingpdf-agent[all]"
### Container images (:mcp vs :agent)
One multi-stage docker/Dockerfile builds two right-sized images, selected by --target:
| Image tag | Build target | Contents | Entrypoint |
| knucklessg1/stirlingpdf-agent:mcp | --target mcp | stirlingpdf-agent[mcp] — connector-focused, includes epistemic-graph[full]; no model-orchestration stack | stirlingpdf-mcp |
| knucklessg1/stirlingpdf-agent:2.4.6 | --target agent (default) | stirlingpdf-agent[agent] — agent runtime, model orchestration + epistemic-graph[full] | stirlingpdf-agent |
bash
docker build --target mcp -t knucklessg1/stirlingpdf-agent:mcp docker/ # connector-focused MCP server
docker build --target agent -t knucklessg1/stirlingpdf-agent:2.4.6 docker/ # agent runtime
docker/mcp.compose.yml runs the connector-focused :mcp server; docker/agent.compose.yml runs the
agent (:2.4.6) with a co-located :mcp sidecar. Both compose files require the deployed