MCP 核心工具（Core Tools）¶

以下 9 個工具隨 nextpdf/mcp-server 免費提供（LGPL-3.0），無需授權金鑰。

`parse_pdf`¶

解析 PDF 文件的結構、元資料與頁面資訊。

風險等級：low（唯讀操作）

JSON Schema¶

{
  "name": "parse_pdf",
  "description": "Parse a PDF document and return its structure, metadata, and page information.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Absolute or workspace-relative path to the PDF file."
      },
      "pages": {
        "type": "string",
        "description": "Page range to parse (e.g., '1-5', '3', '1,3,5'). Defaults to all pages.",
        "pattern": "^(\\d+(-\\d+)?)(,(\\d+(-\\d+)?))*$"
      },
      "include_structure": {
        "type": "boolean",
        "description": "Whether to include the document structure tree (headings, sections).",
        "default": false
      }
    },
    "required": ["path"]
  }
}

範例請求¶

{
  "tool": "parse_pdf",
  "arguments": {
    "path": "/workspace/reports/annual-2025.pdf",
    "pages": "1-3",
    "include_structure": true
  }
}

範例回應¶

{
  "success": true,
  "data": {
    "path": "/workspace/reports/annual-2025.pdf",
    "file_size_bytes": 2097152,
    "pdf_version": "2.0",
    "page_count": 48,
    "parsed_pages": [1, 2, 3],
    "metadata": {
      "title": "Annual Report 2025",
      "author": "Finance Department",
      "creator": "NextPDF v2.0",
      "created_at": "2025-12-31T00:00:00Z",
      "modified_at": "2026-01-05T10:30:00Z",
      "language": "zh-TW"
    },
    "properties": {
      "is_linearized": true,
      "is_encrypted": false,
      "has_forms": false,
      "has_signatures": true,
      "has_javascript": false,
      "is_tagged": true,
      "pdf_ua_compliant": true
    },
    "structure": {
      "headings": [
        { "level": 1, "text": "執行摘要", "page": 1 },
        { "level": 2, "text": "財務績效", "page": 2 }
      ]
    }
  }
}

錯誤碼¶

錯誤碼	HTTP 狀態	說明
`file_not_found`	404	指定路徑的 PDF 不存在
`access_denied`	403	路徑超出工作區沙盒範圍
`file_too_large`	413	超過 `NEXTPDF_MAX_FILE_SIZE_MB` 限制
`invalid_pdf`	422	檔案損毀或非合法 PDF 格式
`encrypted_pdf`	422	PDF 已加密且未提供密碼
`malicious_content`	422	偵測到嵌入 JavaScript 或惡意內容

`extract_text`¶

從 PDF 頁面提取純文字內容，支援保留版面資訊。

風險等級：low（唯讀操作）

JSON Schema¶

{
  "name": "extract_text",
  "description": "Extract plain text content from PDF pages.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": { "type": "string" },
      "pages": { "type": "string", "description": "Page range (e.g., '1-5'). Defaults to all." },
      "mode": {
        "type": "string",
        "enum": ["plain", "structured", "reading-order"],
        "default": "plain",
        "description": "plain: raw text; structured: with position data; reading-order: flow-corrected."
      },
      "include_coordinates": {
        "type": "boolean",
        "default": false,
        "description": "Include bounding box coordinates for each text block."
      }
    },
    "required": ["path"]
  }
}

範例回應（`mode: "structured"`）¶

{
  "success": true,
  "data": {
    "page_count": 3,
    "pages": [
      {
        "page_number": 1,
        "text": "Annual Report 2025\n\n執行摘要\n本年度...",
        "blocks": [
          {
            "text": "Annual Report 2025",
            "type": "heading",
            "font": "BarlowSemiCondensed-Bold",
            "font_size": 24.0,
            "x": 56.69, "y": 785.20,
            "width": 300.5, "height": 28.0
          }
        ]
      }
    ]
  }
}

`extract_metadata`¶

讀取 PDF 文件的所有元資料屬性，包含 XMP 元資料。

風險等級：low（唯讀操作）

JSON Schema¶

{
  "name": "extract_metadata",
  "description": "Read all metadata properties from a PDF, including XMP metadata.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": { "type": "string" },
      "include_xmp": {
        "type": "boolean",
        "default": false,
        "description": "Include full XMP metadata block."
      }
    },
    "required": ["path"]
  }
}

範例回應¶

{
  "success": true,
  "data": {
    "standard": {
      "title": "Annual Report 2025",
      "author": "Finance Department",
      "subject": "Financial Results",
      "keywords": ["annual", "finance", "2025"],
      "creator": "NextPDF v2.0",
      "producer": "NextPDF Core 2.0.0",
      "created_at": "2025-12-31T00:00:00Z",
      "modified_at": "2026-01-05T10:30:00Z",
      "trapped": "Unknown"
    },
    "custom": {
      "CompanyID": "ACME-001",
      "DocumentVersion": "1.3"
    }
  }
}

`compress_images`¶

壓縮 PDF 中的嵌入影像以縮減檔案大小。

風險等級：medium（修改文件，但原始檔保留）

JSON Schema¶

{
  "name": "compress_images",
  "description": "Compress embedded images in a PDF to reduce file size.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "input_path": { "type": "string" },
      "output_path": { "type": "string", "description": "Path for the compressed PDF. Defaults to input_path (overwrite)." },
      "jpeg_quality": {
        "type": "integer",
        "minimum": 1, "maximum": 100,
        "default": 85,
        "description": "JPEG compression quality (1-100). Lower = smaller file, lower quality."
      },
      "max_image_dpi": {
        "type": "integer",
        "default": 150,
        "description": "Downsample images above this DPI. 0 = no downsampling."
      },
      "convert_to_jpeg": {
        "type": "boolean",
        "default": false,
        "description": "Convert PNG images to JPEG for further size reduction."
      }
    },
    "required": ["input_path"]
  }
}

範例回應¶

{
  "success": true,
  "data": {
    "input_path": "/workspace/report.pdf",
    "output_path": "/workspace/report-compressed.pdf",
    "original_size_bytes": 10485760,
    "compressed_size_bytes": 3145728,
    "reduction_percent": 70.0,
    "images_processed": 42,
    "duration_ms": 3200
  }
}

`add_watermark`¶

在 PDF 頁面添加文字浮水印。

風險等級：medium（修改文件）

JSON Schema¶

{
  "name": "add_watermark",
  "description": "Add a text watermark to PDF pages.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "input_path": { "type": "string" },
      "output_path": { "type": "string" },
      "text": {
        "type": "string",
        "description": "Watermark text content.",
        "maxLength": 200
      },
      "pages": { "type": "string", "description": "Page range. Defaults to all pages." },
      "opacity": {
        "type": "number",
        "minimum": 0.0, "maximum": 1.0,
        "default": 0.3
      },
      "font_size": { "type": "integer", "default": 48 },
      "color": {
        "type": "string",
        "description": "CSS hex color (e.g., '#FF0000').",
        "default": "#808080"
      },
      "rotation_degrees": { "type": "integer", "default": 45 },
      "position": {
        "type": "string",
        "enum": ["center", "top-left", "top-right", "bottom-left", "bottom-right"],
        "default": "center"
      }
    },
    "required": ["input_path", "text"]
  }
}

`merge_pdfs`¶

合併多份 PDF 文件為單一文件。

風險等級：medium（創建新文件）

JSON Schema¶

{
  "name": "merge_pdfs",
  "description": "Merge multiple PDF files into a single document.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "input_paths": {
        "type": "array",
        "items": { "type": "string" },
        "minItems": 2,
        "maxItems": 100,
        "description": "Ordered list of PDF paths to merge."
      },
      "output_path": { "type": "string" },
      "preserve_bookmarks": { "type": "boolean", "default": true },
      "page_ranges": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Optional per-file page ranges (e.g., ['1-5', '2-4', null]). null = all pages."
      }
    },
    "required": ["input_paths", "output_path"]
  }
}

`split_pdf`¶

依頁面範圍將 PDF 拆分為多個文件。

風險等級：medium（創建新文件）

JSON Schema¶

{
  "name": "split_pdf",
  "description": "Split a PDF into multiple documents by page ranges.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "input_path": { "type": "string" },
      "output_dir": { "type": "string", "description": "Directory to save output files." },
      "split_by": {
        "type": "string",
        "enum": ["ranges", "every-n-pages", "bookmarks"],
        "default": "ranges"
      },
      "ranges": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Page ranges when split_by='ranges' (e.g., ['1-10', '11-20'])."
      },
      "pages_per_file": {
        "type": "integer",
        "minimum": 1,
        "description": "Pages per output file when split_by='every-n-pages'."
      },
      "filename_pattern": {
        "type": "string",
        "default": "{basename}-part-{index}",
        "description": "Output filename pattern. Supports {basename}, {index}, {page_start}, {page_end}."
      }
    },
    "required": ["input_path", "output_dir"]
  }
}

`protect_pdf`¶

設定 PDF 密碼保護與存取權限。

風險等級：high（修改安全設定，操作不易逆轉）

JSON Schema¶

{
  "name": "protect_pdf",
  "description": "Apply password protection and access permissions to a PDF.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "input_path": { "type": "string" },
      "output_path": { "type": "string" },
      "user_password": {
        "type": "string",
        "description": "Password required to open the document.",
        "minLength": 1,
        "maxLength": 255
      },
      "owner_password": {
        "type": "string",
        "description": "Password required to change permissions.",
        "minLength": 8,
        "maxLength": 255
      },
      "permissions": {
        "type": "object",
        "properties": {
          "print": { "type": "boolean", "default": true },
          "copy": { "type": "boolean", "default": false },
          "modify": { "type": "boolean", "default": false },
          "annotate": { "type": "boolean", "default": false },
          "fill_forms": { "type": "boolean", "default": false }
        }
      },
      "encryption": {
        "type": "string",
        "enum": ["aes-256", "aes-128"],
        "default": "aes-256"
      }
    },
    "required": ["input_path", "owner_password"]
  }
}

HITL 建議：此工具為 high 風險等級。AI 助理應在執行前向使用者確認，並確保密碼已安全保存，否則可能導致文件永久無法存取。

`generate_pdf`¶

從 HTML 或 Markdown 內容生成 PDF 文件。

風險等級：medium（創建新文件）

JSON Schema¶

{
  "name": "generate_pdf",
  "description": "Generate a PDF document from HTML or Markdown content.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "content": {
        "type": "string",
        "description": "HTML or Markdown source content."
      },
      "content_type": {
        "type": "string",
        "enum": ["html", "markdown"],
        "default": "html"
      },
      "output_path": { "type": "string" },
      "options": {
        "type": "object",
        "properties": {
          "page_size": {
            "type": "string",
            "enum": ["A4", "A3", "Letter", "Legal"],
            "default": "A4"
          },
          "orientation": {
            "type": "string",
            "enum": ["portrait", "landscape"],
            "default": "portrait"
          },
          "margin_mm": {
            "type": "object",
            "properties": {
              "top": { "type": "number", "default": 20 },
              "right": { "type": "number", "default": 20 },
              "bottom": { "type": "number", "default": 20 },
              "left": { "type": "number", "default": 20 }
            }
          },
          "language": {
            "type": "string",
            "description": "Document language hint (BCP 47, e.g., 'zh-TW', 'en').",
            "default": "en"
          }
        }
      }
    },
    "required": ["content", "output_path"]
  }
}

通用錯誤碼（所有核心工具）¶

錯誤碼	說明
`file_not_found`	輸入檔案不存在
`access_denied`	路徑超出工作區沙盒
`file_too_large`	超過大小限制
`invalid_pdf`	非合法 PDF 格式
`output_dir_not_found`	輸出目錄不存在
`disk_space_insufficient`	磁碟空間不足
`internal_error`	內部處理錯誤（附帶 `trace_id` 供除錯）

參見¶

Pro 工具參考 — 8 個 Pro 層級工具
Enterprise 工具參考 — 8 個 Enterprise 層級工具
工具目錄 — 所有工具的完整清單
MCP 安裝指南 — 設定 MCP 伺服器

MCP 核心工具（Core Tools）¶

parse_pdf¶

JSON Schema¶

範例請求¶

範例回應¶

錯誤碼¶

extract_text¶

JSON Schema¶

範例回應（mode: "structured"）¶

extract_metadata¶

JSON Schema¶

範例回應¶

compress_images¶

JSON Schema¶

範例回應¶

add_watermark¶

JSON Schema¶

merge_pdfs¶

JSON Schema¶

split_pdf¶

JSON Schema¶

protect_pdf¶

JSON Schema¶

generate_pdf¶

JSON Schema¶

通用錯誤碼（所有核心工具）¶

參見¶

`parse_pdf`¶

`extract_text`¶

範例回應（`mode: "structured"`）¶

`extract_metadata`¶

`compress_images`¶

`add_watermark`¶

`merge_pdfs`¶

`split_pdf`¶

`protect_pdf`¶

`generate_pdf`¶