PDFCanon.Mcp 1.0.3

PDFCanon MCP Server

An official Model Context Protocol (MCP) server for PDFCanon that allows AI assistants and agents to perform PDF normalization, structural inspection, compliance reporting, and integrity verification as native tools — all backed by the PDFCanon REST API.

Overview

PDFCanon is deterministic — not AI-powered — but providing an MCP server positions it as AI-compatible infrastructure, lowering friction for developers building AI agents that handle untrusted documents.

Every tool call uploads a local PDF file to the PDFCanon production API using your API key. No local qpdf installation is required.

Prerequisites

• .NET 10 runtime
• A PDFCanon API key (pdfn_...). Generate one from the dashboard.

Installation

As a .NET Global Tool

dotnet tool install -g PDFCanon.Mcp

From Source

git clone https://github.com/napzoom/PDFCanon
cd PDFCanon
dotnet run --project src/PDFCanon.Mcp

Configuration

API Key

The server reads your API key from the PDFCANON_API_KEY environment variable. A .env file in the working directory is also supported.

# .env
PDFCANON_API_KEY=pdfn_your_key_here

# Optional — override the API base URL (defaults to https://api.pdfcanon.com)
# PDFCANON_BASE_URL=https://api.pdfcanon.com

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "pdfcanon": {
      "command": "pdfcanon-mcp",
      "env": {
        "PDFCANON_API_KEY": "pdfn_your_key_here"
      }
    }
  }
}

VS Code (with MCP extension)

Add to .vscode/mcp.json:

{
  "mcpServers": {
    "pdfcanon": {
      "command": "pdfcanon-mcp",
      "env": {
        "PDFCANON_API_KEY": "pdfn_your_key_here"
      }
    }
  }
}

Tools

normalize_pdf

Uploads a local PDF to the PDFCanon API for normalization. Active content (JavaScript, OpenActions, embedded files) is stripped server-side. The normalized PDF is downloaded and saved locally.

Parameters:

Example response:

{
  "status": "success",
  "submission_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "original_sha256": "a1b2c3...",
  "normalized_sha256": "e5f6a7...",
  "normalized_file": "/tmp/pdfcanon_mcp/normalized_e5f6a7.pdf",
  "processing_time_ms": 1340,
  "summary": {
    "javascript_removed": true,
    "open_actions_removed": true,
    "embedded_files_removed": false,
    "rich_media_removed": false,
    "launch_actions_removed": false,
    "incremental_saves_collapsed": true,
    "metadata_stripped": true,
    "acroform_flattened": false,
    "annotations_removed": false,
    "xref_rebuilt": true
  },
  "warnings": ["Non-embedded font: Arial"]
}

get_report

Fetches the compliance report for a normalized PDF directly from the PDFCanon API.

Parameters:

inspect_structure

Uploads a local PDF to the PDFCanon API and returns a security and validation analysis based on the normalization report. The normalized file is not downloaded locally.

Parameters:

Example response:

{
  "status": "success",
  "file_path": "/path/to/document.pdf",
  "original_sha256": "a1b2c3...",
  "normalized_sha256": "e5f6a7...",
  "encrypted": false,
  "active_content": [
    { "type": "javascript", "risk": "high" },
    { "type": "open_action", "risk": "high" }
  ],
  "normalization_changes": {
    "javascript_removed": true,
    "open_actions_removed": true,
    "embedded_files_removed": false
  }
}

verify_integrity

Uploads a local PDF to the PDFCanon API, normalizes it, and verifies that the resulting normalized SHA-256 matches a provided expected hash.

Parameters:

Example response (match):

{
  "status": "success",
  "file_path": "/path/to/document.pdf",
  "valid": true,
  "actual_hash": "e5f6a7...",
  "expected_hash": "e5f6a7..."
}

Example response (drift):

{
  "status": "success",
  "file_path": "/path/to/document.pdf",
  "valid": false,
  "actual_hash": "b8c9d0...",
  "expected_hash": "e5f6a7...",
  "drift_details": "Expected 'e5f6a7...' but got 'b8c9d0...'. The file may have been modified..."
}

Error Responses

All tools return a structured error response on failure:

{
  "status": "error",
  "error_code": "UNAUTHORIZED",
  "message": "Invalid or missing API key. Check PDFCANON_API_KEY."
}

Common error codes:

Use Cases

AI-Safe Document Reading

User: "Summarize this contract.pdf"
Agent: [calls normalize_pdf] → downloads safe normalized version → [reads and summarizes]

Automated Compliance Audits

User: "Audit all PDFs in /documents for security issues"
Agent: [calls inspect_structure for each file] → generates natural-language risk report

Developer Explainability

User: "What was removed from this PDF to make it canonical?"
Agent: [calls normalize_pdf, then get_report] → explains structural delta

Integrity Verification in Workflows

Agent: [calls verify_integrity with expected hash] → confirms document hasn't been tampered with