pdfnative-mcp

PDF 생성, PDF/A 보관, 장기 검증을 포함한 PAdES 서명, AcroForms, 병합/분할, 암호화 및 레이아웃 미리보기용 MCP 서버 — pdfnative 엔진(제로 의존성, ISO 32000-1 준수) 기반의 28개 도구로, Claude Desktop, Cursor, ChatGPT 및 모든 Model Context Protocol 클라이언트에서 사용할 수 있습니다.

✨ 기능

pdfpdfnative-mcp는 모든 MCP 호스트에 프로덕션급 도구 28개를 제공합니다:

v1.6.0의 새로운 기능:

• 원 전체 엔진 커버리즈 — 13종 블록 — generate_basic_pdf는 pdfnative가 제공하는 모든 DocumentBlock을 허용합니다. table, image, link, toc, barcode, svg, formField 블록은 각 각전용 도구(add_table, embed_image, add_barcode, add_form)와 본문을 공유하므로, 독립 아티팩트/인라인이든 동일한게 검증/렌더링됩니다. 규칙: link는 http: / https: / mailto:만 받습니다(제어 문자가 포含되면 가부). image는 크기 제이(각 12 M base64 문자열, 호출당 24 MiB 해동; PNG는 8버트/non-interlaced/alpha/paleteless pay be used, 그렇지 않을면 해석안내와 함게 버됨). svg는 path, 기본 도형, <text>를 담당합니다 (transform, <g>, 그라데이션, CSS는 무시 — 외부에서 리소스를 가여 오지 않음). toc은 outline: 'auto'와 짝을 이룸니다. PDF/A 청구가 있는 문서에서 formField를 사용하면 PDFA_UNEMBEDDED_FORM_FONT(을를) 보고합니다. barcode에는 alt가 없습니다(엔진 제한).

• 📐 레이이웃 옵션 — 9개 문서 도구에 pageSize(포멧 기본, 특수: A4 기본?, Letter, Legal, A3, Tabloid), margins(네 면 모두, 0–200pt), headerTemplate / footerTemplate 및 {page} {pages} {title} {date}(footerTemplate을 지정하면 기본 footer가 교체되고 footerText는 무시됩니다. {date}는 빌드 당시 벽시계 시간이지 creationDate가 아닙니다), compress(FlateDecode스트림 — 파일 을 축소, 바이트는 달라짐, PDF/A에서XMP는 평문 유지)와 debug`(가이디 도형/무표시 컨텐츠, PDF/UA 아님) 지이. 기본값은 본래 없기 때문에 기본 출력은 바이트 단위로 완전히 동일합니다.

• 🔐 빌드 시 암호화 — encrypt 옵션이 7개 문서 도구(generate_basic_pdf, add_table, add_form, add_international_text, embed_image, add_barcode, add_chart)에 추가되었습니다. 표준 보안 핸들러, AES-128 기본(또는 AES-256), AcroForm을 유지(encrypt_pdf는 페이지 트리를 재구축하는 것과 대조됨). pdfA와 동시 사용 불가능(VALIDATION_ERROR), 캐시 없음, prepare_signature_placeholder(서명 가능을 유지해야 함)와 add_attachment(PDF/A-3)에는 제공되지 않습니다.

• 📏 inspect_layout — 열여덟 번째 도구: 동일한 blocks와 레이아웃 입력을 읽기 전용으로 페이지네이션 예시(dry run) 실행. PDF를 랜더링하지 않고 totalPages와 각 블록의 page / x / top / width / height를 반환합니다. 알려진 엔진 간극: toc 블록이 0pt로 측정되므로, 목차가 포함된 문서는 미리보기보다 한 페이지 늦게 페이지네이션될 수 있습니다.

• 🔎 inspect_pdf annotations: true — 모든 페이지 주석을 나열합니다(하위 유형, 0-시작 페이지, rect, 200자로 수정된 contents, title, color, color, color, link URL) 및 annotationCount; 새로 check: 'annotations' 추가됨었습니다.

• 이미지 워터마크 — generate_basic_pdf와 add_table에서 watermark.image(JPEG/PNG, 기본 불투명도 0.10, 자체 8 MB 상한)를 단독 또는 text(기본 불투명도 0.16)와 함께 니다. position: 'background' | 'foreground'는 etc. 불투명도 1.0 미만은 pdfa1b 아래 거부됩니다.

• 원 **PDFNONATIVE_MCP_MAX_INFLATE_BYTES** — 엔진의 스트림 당 100 MiB 풀기 상한를 오버라이터가 덮어쓰능(자연수 ≥1024; 잘못된 값은 시작되지 않습니다). 컴압된 첨부 스트림은 extract_attachments includeData: true에서 PDF_PARSE_FAILED로 실패하고, extract_text`은 페이트 텍스트로 감지됩니다(엔진은 각 페이지 디코딩 오류를 삼승).

• 원 Form — add_form и formField block 에 listbox/placeholder 추가. fieldType: 'textarea' enters engine as multilineText (formerly not map귏 so one-line field로 그려짐 — 해당 입력에 대해 byte를 변경하는 버그 수정 포함). embed_image에는 align and word alt추가.

• 🔏 PAdES 장기 검증 라더 — sign_pdf에 profile: 'pades'(ETSI EN 319 142-1 기반, ESS signing-certificate-v2, ETSI.CAdES.detached), timestamp: true(이-T, RFC 3161), RSA-SHA384/512, certChainDerBase64, fieldName/allowMultiple(여러 sign) 지원. 새 add_ltv는 /DSS(이-LT, mode: 'online (operator provider) or mode: 'offline with caller- provided BER) 등 supports. 새 timestamp_pdf은 /DocTimeStmap를 뒤에추가(B-LTA). verify_pdf ltv: true는 profile, timestamp, revoc 상태와 ltLevel을 reports. docs/guides/LTV.md 참조.

• 외부 네트워크 차트 — 기본적으로 어떤 외부 요청도 발생하지 않습니다. 서버가 할 수 있는 유일한 외부 접속은 운영커 구성한 RFC 3161 / OCSP / CRL 엔드포인트(PDFNATIVE_MCP_TSA_URL, PDFNATIVE_MCP_REVOCATION, PDFNATIVE_MCP_NETWORK_ALLOWED_HOSTS)뿐이며, SSRF 가드가 있습니다. 도구 주장에서 URL을 제공할 는 없습니다.

• 원 인1 프로덕션 — 모든 도구에서 print(TrimBox)/BleedBox/ArtBox/CropBox, 그리고 bleed 생략 표기, crop + marks, /UserUnit), metadata(/Author, /Key, /Subject, /Trapped), outputIncent(파/A의 custom RGB ICC) and deviewer etc. viewerPrefereces는 duplex, pickTrayByPDFSize, printPageRange, numCopyies를 사용. inspect_pdf pages: true the find the box; merge/split/extract가 프리즈를 보존. PRINT.md` 참조.

• ✍지 update_metadata — 기존 PDF의 /Info와 XMP를 incremental update로 교체(이전 판본과 서명을 그대로 유지).

• 차트 v2 — stackedBar / stackedBarH / area / s, top, axis.scale: 'log', xAxis.type: 'linear' | 'time', dataLabels', labelStride/labelRotation`; overlapping Labels는 자동으로 생략니다.

• 직한 PDF/A — embedFonts: true는 Noto Sans Latin을 embeddes(기본 14 Helvetica가 embed되있지 않으므로 일반 Animals 텀스트와 PDF/A가 veraPDF에 검증되어 거부됩니다). strict: true는 비준수 파일을 생산하지 않고 실패합니다. strict진 – includeDiagnostics: trueengine diagnostics.scripts (npm run validate:pdfa) — 24문자(^) 등 : 26-file corpus 대한 검증(24국가,3 pass negative ) , have : page-tree 2 건 생략) and VERAPDF_REQUIRED=1fails-closed(모드. CI workflow sha-1 고정, v1.6번에서 비치단 – 문). Injury gap:add_form은 embedFonts가 있어도 PDF/A-2b 실패?(/DR /Helv안 엔베드),prepare_signature_placeholder` 결과는 한번 sign 해야만 compliant.

• 🧰 inspect_pdf — signatures: true (리스트 표시), dss/docTimestampCount/trapped(존재시에만 노출), 새 check 값 dss, docTimestamp, trapped, checks 요청 키만 나열합니다. 참고: signed는 구조적인 것입니다(서명된 필드 존재; 유효성 검증은 verify_pdf 담당).

• 반복 가능한 출력 — 9개 문서도구의 creationDate가 /CreationDate, XMP 날짜, trailer /ID를 고정. prepare_signature_placeholder의 signingTime (sign_time too, now timezone) 및 signing_pdf의 signingTime에 /Sig /M 고정). 동일 host timezone에서는 byte가 동일. reproducible_output 프롬프트에서 제공.

• 강화된 경계 — 딱딱한 input z칭(예: 모르는/오타 키는 조용히 무시하지 않고 VALIDATION_ERROR); data:…;base64,prefixل, "PEM where DER"와 double-encoded payload는 정확한 해결 방법과 함께 거부, page tree tools의 page index 오류는 0-based 힌트와 함께VALIDATION_ERROR, 미지의 tool name은 JSON-RPC 프로토콜 오류(-32602, [UNKNOWN_TOOL]`).

• 🔑 HTTP Bearer Media — 선택 PDFNATIVE_MCP_HTTP_TOKEN을 Streamable HTTP endpoint 401/WWW-Authenticate를 열어 주는 켜는 토큰이 없으면 loopback은 인증이 없습니다(참 SECURITY 참조).

• 카탈로그 — localhost/list 는 1.5.0 108KB 대비 1.6.0 파일은 ~245kB. 전 블록 종류, 레이이아웃 옵션, encrypt fragment are inline advertised, policy 상 $ref/$defs 없음 — inputSchema를 function-call API에 전달하는 host는 ref를 만하지 않습니다. server Instructions는 12.9 KB에서 ~6.7KB. Structure is guard by scripts/tool-shape.mjs + tests/catalogue-parity.test.ts, and tests/catalogue-susert.test.ts proves live catalog super set of 1.5.0 catalog; tool _meta.examples max 2, the others in examples/. New recipe prompts 4개: pades_ladder, print_ready, reproducible_output, pdfa_valid.

• Fixes — pdfnative < 1.7에서 surrounder metadata (signerName/reason/location/contactInfo)가 /Sig 사전에 도달하지 못했으므로, placeholder time에 기록 하도록 수정. verify_pdf B-LTA문서에서 잘못된 allValid: false (DocTimeStamp가 CMS signature로 parse된 등)을 수정.

• MCP 2026-07-28 — MCP TypeScript SDK v2 (@modelcontextprotocol/server)에 automatic fallback to 2025-era initialize handshake, existing hosts는 그대로 동작. MCP 프로토콘 준수 참조.

• ⬆ 엔진 업그레이드 — pdfnative v1.7.0 (LTV, 인쇄 production, charts v2, digest agility, flag/ZWJ emoji sequences, UAX #9 fixes).

새로운 v1.5.0:

• 📊 Native vector charts — add_chart 를 사용해 bar/horizontal-bar/line/pie/donut charts를 PDF path operators로 렌더링(no rasterisation, PDF/A, aut alt text) . generate_basic_pdf는 chart block을 함께 컴포지션할 수 있습니다.

• 📝 Fill & flatten form — read_form_fields는 기존 AcroForm intent; fill_form은 비-파 incremental update로 채우고/펠che(add_form 카운터파트).

• 🔐 암호화 라운드-trip — encrypt_pdf AES-128/256 암호화 재실 . (RC4 not출력), decrypt_pdf 암호화 되지 않은 복사가 가능. password를 받아 read-only tools에서 암호화 원본 열, plus merge_pdfs/split_pdf/extract_pages에 password+encrypt 추가.

• 🔤 실제 텍스트 추출 — extract_text은 이제 각 글의 /ToUnicode CMap을 리졸브(ney 더 glyph-index)하읿, position. text output support.

• 🔗 네이티브 MCP resources — sandboxed PDF files pdfnative://output/…의 (resource resources/list+resources/read). 파일 모드 결과에 resource_link 포함.

• 구 주석 달 — 모든 도구에 readOnlyHint/destructiveHint/idempotentHint/openWorldHint 선택지정.

• 엔진 업그레이드 — pdfnative v1.6.0 (decrypt/re-도구-엔, extractText, fill/flatten, charts; color-emoji subset 221 → 1167) .

새로운 v1.4.0:

• 🤝 AI 거버넌스 + 사람-in-the-loop — draft_governace_issue는 완전히 규합된 GitHub 이슈를 로컬(주)로 초안(.md + 기기 판독 compliance report)한다. 로트는 그리 로무로, 스스스트로 제출는 불가; 서버는 GitHub에 젂0 쓰기 (그리고 v1.6.0 이후에는 운영자가 구한 TSA/OCSP/CRL 만) 수행. governance_contract 및 draft_issue_workflow MCP 프롬프트로 지원.

• ✏️ Markup annotation — annotate_pdf 는기존 PDF에 highlight, stickynote, uline, Plato, squi글 (..., line, and freext annotations를 incremental update로 입힌. 이 것을 에디토 리와 레이어(? visual review layer) not redaction — bottom bytes나 그대로 유지.

• 🔢 inspect_pdf의 page labels — /PageLabels (로만, decimal, prefixed) 읽‑only.

• Math / scientific script — add_international_text에 lang: 'math'(명시) for fot is part of emoji (Noto Sans Math font는 on-demand embed).

• MCP prompts — 서버는 prompts 능력을 광고, governance_contract 및 draft_issue_workflow (이트).

• 엔진 업그레이드 — pdfnative v1.5.0.

v1.3.0의 새 기능:

• ** 페이지 트리 도구 3개** — merge_pdfs, split_pdf, extract_pages (pdfnative v1.4.0의 페이지 트리 API 기반; v1.5.0에서 password가 추가되기 전까지 암호화된 입력은 거부되었습니다).

• 🔖 북마르크, 페이지 라벨 ... — generate_basic_pdf에 outline('auto또는 명시적 트리),pageLabels, 다단계 list항목,viewerерPreferences`가 추가되었습니다.

• 📐 표 셀 테두리 및 정렬 — add_table에 cellBorders, cellVAlign, viewerPreferences가 추가되었고, add_international_text에 viewerPreferences가 추가되었습니다.

• 🔐 상수 시간 서명 — sign_pdf는 node:crypto 프로바기더를 통해 RSA 및 EC-DER를 키로 서명하며, 투명한 순수 JS 폴백이 있습니다 (raw P-256 스칼라 서명은 순수 JS이며, 검즉도 순수 JS). 서명은 계속 상호 운영 가능합니다.

• 엔진 업그레이드 — pdfnative v1.4.0.

• 🆕 Tool extract_attachments — "PDF에서 임베드된 파일을 다시 읽어낸다" (Factur-X / ZUGFeRD 왕복을 완성) : Byte 단위 그대로의 페이로드, filename 필터, includeData: false 메타데이터 전용 프로브.

• 💧 워터마크 — generate_basic_pdf 및 add_table은 선택 적 watermark(텍스트, 불투명도, 각도, 색, 위차; v1.6.0 이후 image)를 모든 페이지에 렌더링할 수 있습니다.

• 🌐 Unicode normalize — generate_basic_pdf와 add_international_text에서 선택적 NFC/NFD/NFKC/NFKD 정규화를 지원합니다.

• 토큘 절약형 읽기 — 읽기 전용 도구들을 담당합니다 (inspect_pdf, verify_pdf, validate_pdf, extract_text, extract_attachments; v1.5.0부터 read_form_fields) 옵션 verbosity: 'summary' 및 fields: […]를 수용하여 큰 결과에서 응답 크기를 약90% 줄이면서, 에이전트가 분기하는 데 쓰는 필드는 잃지 않습니다. 기본값은 다른 점 없습니다.

• base64 중복 없음 — 생성된 PDF(base64 모드)는 structuredContent에도 복사되는 대신, 임베드드 resource 콘텐츠 블록으로 한 번만 반환됩니다.

• 🔧 MCP 레지스트리 발행 수정 — mcpName이 표준 GitHub 로그인 대소문자(io.github.Nizoka//pdfnative-mcp)를 사용하므로 레지스트리의 대소문자 구분 검증이 npm 패키지를 승인합니다.

• Well존성 — zod 4로 업그레이드.

v1.1.0의 새 기능:

• 🆕 Tool validate_pdf — 읽기 전용 PDF/UA (ISO 14289-1) 구조 적합성 검사.

• 🆕 6개의 새 스크립트 — 텔르구, 신hasil, 티베트, 크메르, 미얼마, 이티오피아 (총 24개 스크립트).

• 🆕 COLRv1 색상 이모지 — 기본 색상 이모지 + 단색 폴백.

• 🆕 새 줄 처리기 — 문단에 내장된 \n이 자동으로 별도의 문단으로 분해됩니다 (PDF/AA 안전).

• add_international_text 자동 NFC 정규화.

• 엔진 업그레이드 — pdfnative v1.3.0: 유로 기호/CP-1252 심볼이 이제 올르게 추출되고, 줄바 테이블 는 행별 고유 MCID를 갖게 됨니다 (PDF/UA 안전).

v1.0.0의 새 기능:

• 새 도구 3개: verify_pdf, add_attachment (Factur-X / ZUGFeRD), extract_text.

• 🆕 스마트 테이블 필드: wrap, repeatHeader, zebra, caption, minRowHeight, cellPadding.

• 을 inspect_pdf**이제 hasSignaturePlaceholder 및 첨부 파일별 요약을 보고합니다; 새 check 값 'placeholder', 'attachments' 추가.

• 서명 사용성개선 — sign_pdf가 ECDSA SEC1 / PKCS#8 DER 키를 수용하며, 누락된 /Sig placeholder를 필요 시 자동으로 삽입합니다 (모든 PDF을 한 번의 호출로 서명).

• **Opt-in cache** (PDFNATIVE_MCP_CACHE_DIR`): SHA-256 키, 1시간 TTL, 256 MiB LRU.

• **_meta.apiVersion** 및 도구별 **_meta.examples** — AI 에이에이전트 탐지를 위해 — [docssolete/API_STABILITY.md`](docs/API_STABILITY.md) 참조.

• **AI 에디 지도**: [docs/AI_GUIDE.md`](docs/AID_GUIDE.md) — 결정 트리 + 함의 사용 요인 참조. 트의 AGENTS.md 운영 설명서론.

• 🆕 PDF/A 작성 가이드 — docs/guid/PDFA.md.

• 환경 변수 이름 옮: PDFNATIVE_MCP_OUTUT_DST (기존 PDFNATIVE_MPC_OOUTPUT_DIR, 구 이는 일회 반환 경고와 함께 계속 동작).

• ✅ 이제 출시됨: merge_pdfs, split_pdf, extract_pages (v1.3.0), annotate_pdf (v1.4.0), add_chart / read_form_fields / fill_form / encrypt_pdf / decrypt_pdf 는그리고 암호화 왕보 방 및 네이티브 MC P 리소스 (v1.5.0), add_ltv / timepstamp_pdf / update_metadata / 인도 및 차트 v2 (v1.6.0). redact_pdf는 보류 상태로 — pdfnative는 콘텐츠를 덮어쓰기/평탄화할 수 있지만 제거는 할 수 없고, 덮어쓰기만 하는 "redaction"은 허위 보안을 만들기 대문에 의도적 출시하지 않았습니다(상위 콘텐츠 제거 요청로 추저).

모든 도구는 두 가지 출력 모드를 지원합니다:

• base64 (기본) — 생성된 PDF는 한 번만 resource 콘텐츠 블록 (data:application/pdf;base64,… URI)로 반환됩니다. structuredContent는 { mode, sizeBytes }만을 담습니다(includeDiagnostics: true일 때 diagnostics[], add_ltv에 summary 추가).

• file — PDF은 PDFNATIVE_MCP_OUTPUT_DIR로 지정된 샌드박스 폴더에 기록됩니다. PDFNATIVE_MCP_OUTPUT_DIR가 setting되지 않으면 파일 출력이 비활성화됩니다; 절대 경로, 경로 트래버셜, .pdf 아닌 확장자, NUL 바이트는 모두 거부됩니다.

v1.1.1.0에서 업그레이드하는 사례: 유일한 동작 변경은 base64 모드 바이트가 더 이상 structuredContent.base64에 중복되지 않는 것입니다. 대신 내장된 resource 블록에서 읽으세요:

- const base64 = response.structuredContent.base64;   // v1.1.0
+ const block = response.content.find((c) => c.type === 'resource');
+ const base64 = block.resource.blob;                  // v1.2.0

토큔 절약형 읽기 (v1.2.0). 일곱 개 읽기 전용 도구 (inspect_pdf, verify_pdf, validate_pdf, extract_text, extract_attachments, read_form_fields, inspect_layout)는 두 개의 선택 입력을 지원합니다:

• verbosity: 'summary' — 스칼라 전용의 경량 결과를 반환합니다(대용량 배열/전문 텐스트 생략). 예: verify_pdf → { signureCount, allValid, invalid, summary } (ltv: true 필요시 ltvLevel 추가); inspect_pdf는 docTimestampCount / ddState / trapped / checksPassed가 있면 보존합니다.

• fields: ['a','b.c'] — 구조된 결과를 지정된 dot-path로 투영; verbosity 후 적용됩니다. 일치 하한 경로 누락되고 _meta.unmatchedFields에 보고됩니다(_meta.availableFields 포함).

가장 작은 "이 PDF가 서명되고 유효한가?" 프로버: { "pdfBase64": "…", "verbosity":"summary", "fields": ["allValid"] }.

"formatted Not classic" etc.

Doe pdfnative?

pdfnative-cp는 하부 엔진의 모드를 보증합니다:

• 엔진의 럁타임 의존성 제거 — 순수 JavaScript, 네이티트 바인딩 없음 (이 서버는 MC P SDK와 zod만 추가하여 총 럁타임 의존성이 3개).

• ISO 32000-1 (PDF 1.7) 수준 출력.

• PDF/A-1b/2b/2u/3b, AES-128/256 암호화, AcroForm, 전자 서명.

• 24개 스크립트 (emo 및 math동 총 25개 lang 코드) — 기본 BiDi 재병렬, Arabic 위상 조성, Thai/Devanagogari/Bengali/Tamil OTL shaping 지원.

• Tree-shakeele ESM 빌르.

Related MCP server: rendoc

🚀 Install

# Run directly with npx (recommended for MCP clients)
npx -y pdfnative-mcp

# Or install globally
npm install -g pdfnative-mcp
pdfnative-mcp

요구 사항: Node.js ≥ 22.

⚙️ 구성

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 %APEDATA%\Claude\claude_desktop_config.json (Windows) 편집:

{
  "mcpServers": {
    "pdfnative": {
      "command": "npx",
      "args": ["-y", "pdfnative-mcp"],
      "env": {
        "PDFNATIVE_MCP_OUTPUT_DIR": "/Users/you/Documents/mcp-pdfs"
      }
    }
  }
}

Cursor / Continue / Zed / Windsurf / Cline / Roo Code

stdio 서버를 지원하는 어떤 MCP-호환 클라이언트든 작동합니다. 동일한 command + args + env 삼중값을 사용합니다. Cursor의 예 (~/.cursor/mcp.json):

{
  "mcpServers": {
    "pdfnative": {
      "command": "npx",
      "args": ["-y", "pdfnative-mcp"],
      "env": { "PDFNATIVE_MCP_OUTPUT_DIR": "/Users/you/Documents/mcp-pdfs" }
    }
  }
}

Windsurf / Cline / Roo Code도 각각의 MCP 구성 파일에서 같은 형태를 사용합니다.

🌐 지원되는 AI 생태계 및 클라이언트

pdfnative-mcp는 MCP-네이티브 환경용으로 설계되었으며, stdio 또는 Streamable HTTP를 지원하는 클라이언트와 작동합니다.

커니티 확인된 호환성:

• Ontheia — 자체 호스팅오, 오.소스 AI 에이Д전트 플랏트홀ဘ (개인정보 우선). issue #41에 규인된 작동 확인 및 Ontheia의 호환 MCP 서버 목록.

🔌 MCP 프로토콜 준수

v1.6.0서버는 MCP TypeScript SDK v2(@modelcontext/sdk) 기반으로 구축되어 MCP 2026-07-28을 지원합니다:

• Stateless 서빙 — server/discover가 session handshake를 대체. 모든 결과에 resultType, _meta, serverInfo의 _meta envelope 포함. HTTP에서는 2026-07-28 린라이언트가 각 POST /mcp에 McP-Method / Mcp-Name 헤더를 전송.

• Cache 힌트 — tools/list / promts/list는 public + TTL 24h *server/discover는 public+ 1h,resources/list/resources/templates/list/resources/read는 private ttlMs: 0` (생성된 PDF는 호스트별 사용자 데이터).

• 리소스 오류 — unknow resource URI는 2026-07-28스펙 요구에 따라 JSON-PC 오류 (-32602, Invalid params)로 보고.

• 레거시 자동 폴백 — initialize(2025-11-25, 2025-06-18, 2025-03-26)로 시작하는 by클라이언트는 SDK의 레서 경로로 제공 (stdio 및 HTTP 모두). 기존 호스트는 변동 없음.

• HTTP — GET / DELET /mcp는 405 응답 (SSE 재개 수 없음; server stateless). loopback binding 및 Host / Origin 가로드는 동일하지만 Origin 포트는 이제 서버 포트와 일치해야 합니다 (SDK 검사만으로는 다를 수 있음); PDFNATIVE_MCP_HTTP_TOKEN은 선택적 bearer-token gate를 추가 (401 + WWW-Authenticate if without). HTTP에서 JSON-RPC batch arrays(2025-03-26)가 수용됩니다. doof-lived keep-alive연결은 더 이상 socket listener를 남긴지 않습니다.

• stdio — 이전 SDK 릴리이스와 마찬가찌, initialize 전 request는 응답 없이 드롭되며, stdio에서 JSON-RPC batch arrays를 않습니다 (1.5.0과 동일).

• 프로토콜 오류 — tools/call에 알려지 도구 이름은 JSON-RCP 오류 (-32602, [UNKNOWN_TOOL] Unknown tool…)로,spec에서 분류한 대isError 결과가 아니다. isError: true는실행 실패에만 예 서됩니다. * 출력 스키마 — 모든 structuredContent는 도구의 outputSchema (2026-07-28 필수)를 준수하며, verbosity: 'summary' 및 fields 투자도 포함 (7개 읽기 도구는 모든 속성이 선택의 additionalProperties: false 프로젝팅 스키마를 선언). 입력 스키마는 정책상 $schema 없이 제공됩니다 (MCP ≥ 2025-11-25는 JSON Schema 2020-12; 일부 호스트는 unknown 키워드를 거부하는함수-호출 APIs로 inputSchema를 전달). serverInfo에 websiteUrl 포함; 리소스 템플릿는 pdfnative://output/{+path}.

tools/call 페이로드 (content, structuredContent, isError)는 2026-07-28 경로와 레거시 경로에서 동일합니다; tests/http-modern.tests.s가 이를 어서트하며, tests/schema-conformance.tests.s가 JSON Schema 2020-12 발리데이터로 structuredContent를 검증합니다.

환경 변수

🛠 도구 참조

generate_basic_pdf

{
  "title": "Q1 2026 Report",
  "blocks": [
    { "type": "heading", "text": "Executive summary", "level": 1 },
    { "type": "paragraph", "text": "Revenue grew 24% year over year." },
    { "type": "list", "style": "bullet", "items": ["Strong APAC", "Stable EU", "Soft NA"] },
    { "type": "pageBreak" },
    { "type": "heading", "text": "Details", "level": 2 }
  ],
  "footerText": "Confidential — Internal use only",
  "outputMode": "base64"
}

13가지 블록 종류: heading, paragraph, list, table, image, link, toc, barcode, svg, formField, chart, pageBreak, spacer. 복합 보고서:

{
  "title": "Quarterly report",
  "blocks": [
    { "type": "toc" },
    { "type": "heading", "text": "Sales", "level": 1 },
    { "type": "table", "headers": ["Region", "Revenue"], "rows": [["EMEA", "1.2 M"], ["APAC", "0.9 M"]], "zebra": true },
    { "type": "image", "imageBase64": "<base64 JPEG>", "mimeType": "image/jpeg", "width": 300, "alt": "Revenue chart" },
    { "type": "svg", "data": "M10 10 H 90 V 90 H 10 Z", "viewBox": [0, 0, 100, 100], "fill": "#0a7e8c" },
    { "type": "barcode", "format": "qr", "data": "https://example.com/q1", "align": "center" },
    { "type": "link", "text": "Full dataset", "url": "https://example.com/data" },
    { "type": "formField", "fieldType": "text", "name": "reviewer", "label": "Reviewed by" }
  ],
  "outline": "auto",
  "pageSize": "Letter",
  "headerTemplate": { "right": "{title} — page {page}/{pages}" },
  "embedFonts": true
}

블록 규칙: table, barcode, formField, chart는 add_table / add_barcode / add_form / add_chart와 동일한 본문을 사용합니다. link URL은 http:, https: 또는 mailto:여야 합니다. image 블록은 각각 base64 것 12M자씩, 호출당 24MiB 디코딩 상한이 있습니다(PNG: 8비트 그레이스케일/RGB, 비-인터레이스, 알파가 없고 팔레트가 없음 — 그렇지 않으면 해결책과 함께 VALIDATION_ERROR). svg는 <path>, <rect>, <circle>, <ellipse>, <line>, <polyline>, <polygon>, <text>/<tspan>을 지원하며 transform, <g>, <use>, <image>, 그래디언트, 불투명도, CSS를 조용히 무시합니다(외부 참조를 가져오지 않습니다). toc은 heading 블록으로 만들이지며 outline: 'auto'와 함께 사됩니다. pdfA에서 formField는 PDFA_UNEMBEDDED_FORM_FONT를 보고합니다(strict: true이면 실패). barcode에는 alt가 없습니다. 렌더링 전에 동일한 입력을 inspect_layout에 넘겨 페이네이션을 미리 볼 수 있습니다.

add_barcode

{
  "format": "qr",
  "data": "https://pdfnative.dev",
  "caption": "Scan to learn more",
  "ecLevel": "H",
  "outputMode": "file",
  "outputPath": "tickets/event-42.pdf"
}

지원 형식: qr, code128, ean13, datamatrix, pdf417.

add_international_text

{
  "title": "مرحبا بالعالم",
  "lang": "ar",
  "paragraphs": [
    "هذا اختبار للنص العربي مع تشكيل OpenType ومحارف ثنائية الاتجاه.",
    "Mixed content: العربية + English ✓"
  ]
}

지원하는 lang 코드(25개): ar, he, th, ja, zh, ko, el, hi, bn, ta, ru, ka, hy, tr, pl, vi, latin, te, si, bo, km, my, am, emoji, math. 폰트는 항상 임베드됩니다(embedFonts 입력 없음). 바이트 단위로 동일한 출역에는 creationDate를 정하십시오.

다중 스크립트 문서 — 베열 또는 콤마로 구분된 목록을 전달하세요:

{
  "title": "Mixed Script",
  "lang": ["ar", "emoji"],
  "paragraphs": ["العربية مع رموز 🎉🚀"],
  "pdfA": "pdfa2u"
}

sign_pdf

v1.6.0부터 sign_pdf은 /Sig 자리표시자가 없으면 자동으로 추입합니다 — 단일 호출으로 어떤 PDF든 서명할 수 있습니다:

{
  "pdfBase64": "<any base64 PDF>",
  "algorithm": "rsa-sha256",
  "certDerBase64": "<base64 X.509 cert in DER>",
  "rsaKeyPkcs1DerBase64": "<base64 PKCS#1 RSAPrivateKey DER>",
  "signerName": "Alice",
  "reason": "Approval",
  "location": "Paris, FR",
  "signingTime": "2026-01-15T10:30:00Z"
}

ECDSA P-256의 경우: algorithm: "ecdsa-sha256"을 사용하고 ecPrivateKeyDerBase64(SE/C1 또는 PKCS#8 DER또는ecPrivateScalerHex`(64자 16진수) 중 하을 제공하세요.

PEM → DER 변환:

openssl x509 -in cert.pem -outform DER | base64 -w0                 # cert
openssl rsa  -in key.pem  -outform DER -traditional | base64 -w0    # RSA PKCS#1
openssl pkey -in key.pem  -outform DER | base64 -w0                 # ECDSA

prepare_signature_placeholder는 자리 표시자를 조정해야 할 때만 사용하세요(예: 4096비트 이상 RSA 키용 더 큰 placeholderBytes, subFilter: 'ETSI.CAdES.detached', reserveTimestamp: true). 그 외에는 sign_pdf를 직접 사용하세요.

PAdES 단계 (v1.6.0). profile: "pades"를 사용한 sign_pdf는 B-B 서명을 생성하며, timestamp: true를 추가하면 B-T(PDFNATIVE_MCP_TSA_URL 필요), 그 다음 add_ltv (B-LT), timestamp_pdf (B-LTA) 순서로 진행합니다:

// 1. sign_pdf  { ..., "profile": "pades", "timestamp": true, "certChainDerBase64": ["<intermediate DER>"] }
// 2. add_ltv   { "pdfBase64": "<signed>", "mode": "online" }            // or "offline" + certificatesDerBase64 / ocspResponsesDerBase64 / crlsDerBase64
// 3. timestamp_pdf { "pdfBase64": "<ltv>" }                              // re-run before the TSA certificate expires
// 4. verify_pdf { "pdfBase64": "<final>", "ltv": true }                  // -> ltvLevel: "B-LTA"

서명자 메타데이터(signerName, reason, location, contactInfo)는 자리표시자에 포함됩니다. fieldName은 서명되지 않은 여러 자리표시자 중 하나를 선택하며(PLACEHOLDER_AMBIGUOUS는 그 외의 경우), allowMultiple: true는 서명을 더 추가합니다. 자세한 내용은 docs/guides/LTV.md를 참조하세요.

add_table

{
  "title": "Monthly Sales",
  "headers": ["Region", "Units", "Revenue"],
  "rows": [
    ["APAC", "1200", "$240,000"],
    ["EMEA", "800", "$160,000"]
  ],
  "infoItems": [{ "label": "Period", "value": "January 2025" }],
  "footerText": "Internal use only",
  "outputMode": "base64"
}

add_form

{
  "title": "Employee Onboarding",
  "fields": [
    { "fieldType": "text", "name": "fullName", "label": "Full Name", "required": true },
    { "fieldType": "dropdown", "name": "dept", "label": "Department", "options": ["Engineering", "Sales", "HR"] },
    { "fieldType": "checkbox", "name": "agree", "label": "I agree to the terms", "checked": false },
    { "fieldType": "listbox", "name": "skills", "label": "Skills", "options": ["TypeScript", "PDF", "MCP"] },
    { "fieldType": "textarea", "name": "notes", "label": "Notes", "placeholder": "Anything we should know?" }
  ],
  "outputMode": "base64"
}

필드 유형: text, textarea(여러 줄, /Ff 4096), checkbox, radio, dropdown, listbox; placeholder는 필드가 비어 있는 동안 힌트 텍스트를 표시합니다. encrypt를 추하하면 AcroForm을 유지하는 암호 보호 폼양식이 생성됩니다. PDF/A 선언 하에서 위젯 외관 폰트가 임베드되지 않습니다(PDFA_UNEMBEDDED_FORM_FONT).

embed_image

{
  "title": "Product Photo",
  "imageBase64": "<base64-encoded JPEG bytes>",
  "mimeType": "image/jpeg",
  "caption": "Front view of Model X",
  "width": 400,
  "align": "center",
  "alt": "Front view of the Model X chassis",
  "outputMode": "base64"
}

참고: 엔진의 PNG디코더는 8비트, 비-인터레이스 그레이 스케일 / RG이미지만을 지원합니다. 알파 채널(컬러 타입 4/6), 팔레트(타입 3), 16비트 그리고 인터레이스 PNG는 VALIDATION_ERROR와 함께 경고에서 거부됩니다(평면화하거나 다시 인출하는 안내 포함) — 동일한 규칙이 image 블록과 이미지 워터마크에도 적용됩니다. embed_image.imageBase64는 바운드 없는 1.5.0 계약을 유지하며, 12M 자 상한은 인라인 image 블록과 워터마크 이미지에만 적용됩니다.

prepare_signature_placeholder

{
  "title": "Service Agreement",
  "signerName": "Alice Dupont",
  "reason": "Approved",
  "location": "Paris, FR",
  "blocks": [
    { "type": "paragraph", "text": "By signing below, I accept the terms and conditions." }
  ],
  "outputMode": "base64"
}

sign_pdf에 반환된 PDF 바이트를 전달하하여 서명 워크플로를 완료하세요.

inspect_pdf

읽기 전용 구조 및 보안 검사 — 다운스트림 검증, CI 어서션, PDF에 행동하기 전에 그내용을 파아야 하는 AI 에이전트에 유용합니다.

{
  "pdfBase64": "<base64 PDF>",
  "pages": true,
  "check": ["pdfa", "signed", "attachments"]
}

반환 값:

{
  "version": "1.7",
  "pageCount": 3,
  "encryption": "none",          // 'none' | 'aes-128' | 'aes-256' | 'rc4' | 'unknown'
  "pdfA": "3B",                  // null when no PDF/A claim is present
  "signatureCount": 1,
  "hasSignaturePlaceholder": false,
  "attachments": [{ "filename": "factur-x.xml", "mimeType": "application/xml", "sizeBytes": 1234, "relationship": "Source" }],
  "info": { "Producer": "pdfnative", "Title": "Invoice INV-2025-001" },
  "perPage": [{ "index": 0, "width": 595, "height": 842 }],
  "checks": { "pdfa": true, "signed": true, "attachments": true },
  "checksPassed": true
}

check[]는 'pdffa', 'igned', 'encrypted', 'placeholder', 'attachments', 'Dss', 'DocTimestamp', 'Trapped', 'annotations' 중 하나를 허용합니다(마지막 네 개는 v1.6.0부터). checksPassed는 요청한 모든 검사 결과의 AND입니다. signatures: true는 필드별 인밴토리(subFilter, isDocTimestamp, isPlaceholder, byteRange, vriKey)를 추고합니다. annotations: true는 annotations[](모든 /Annots 항목: 0 기반 page, subtype, rect, 그리고 해당 시 contents(200자로 잘림), url, quadPoints, 링크 url)와 annotationCount를 추고합니다. dss, docTimestampCount, trapped는 존재하는 경우에만 표시됩니다. pages: true면 각 perPage 항목도 trimBox / bleedBox / artBox / cropBox / userUnit를 설정된 때 함게 실어 갑니다.

inspect_layout

읽기 전용 페이지 임의 드라이 러 — generate_basic_pdf의 동일한 blocks 추가로 블록을 옴기는 모든 입력(title, footerText, pdfA, normalize, embedFonts, pageSize, margins, headerTemplate, footerTemplate)을 포함합니다. PDF는 생산되지 않습니다. generate_basic_pdf에 전달할 것과 동일한 값을 전달하면 totalPages가 일치합니다.

{ "title": "Memo", "blocks": [{ "type": "paragraph", "text": "Short note." }], "pageSize": "Letter", "verbosity": "summary", "fields": ["totalPages"] }

전체 결과는 pageWidth, pageHeight, margin, totalPages, pages[].blocks[](type, page, x, top, width, height, 포인트, 소수점 두 자리에서 반올림)를 로합니다. 알려진 엔진 격: toc 블록은 여기에스 0포인트로 측저되므로, 인된 목차가 있는 문서는 미리 보기보다 한 페이지 늦漫가 나니다.

validate_pdf

읽기 전용 PDF/UA (ISO 14289-1) 구조 검사: 태그된 PDF를 위한 검사입니다. 임의 도구로 pdfA(예: pdfA: 'pdfa2u')를 사용하야 접근 가능한 문서를 생산한 후 결과를 검중하세요:

{ "pdfBase64": "<tagged-pdf-base64>" }

Return:

{
  "standard": "pdf-ua-1",
  "valid": true,
  "errors": [],          // blocking structural violations (empty when valid)
  "warnings": [],        // non-blocking best-practice recommendations
  "summary": "PDF/UA structural prerequisites hold."
}

카탈로그의 /MarkInfo /Marked true, /StructTreeRoot (+ /ParentTree), /Metadata (XMP), /Lang, 그리고 페이지별 MCID 고유성을 검증합니다. 이는 개발자 시간 절약을 위한 빠른 게이트로, 글트·색상·렌더링까지 추가로 검사하는 완전한 참조 구현 검증기(veraPDF)의 대체 가 아닙니다.

annotate_pdf

기존 PDF에 증분 업데이트 방삭으로 마크업 주석을 오버레이합니다. 이는 시각적리 검토 레이어이지 교체(redaction)가 아닙니다 — 기존 콘텐츠는 그대로 유지됩니다.

{
  "pdfBase64": "<base64 PDF>",
  "annotations": [
    { "type": "highlight", "page": 0, "rect": [72, 700, 520, 715], "color": [1, 1, 0], "contents": "Check this figure" },
    { "type": "text", "page": 0, "rect": [540, 700, 560, 720], "contents": "Reviewer note" }
  ]
}

유형: text, highlight, underline, strikeout, squiggly, square, circle, line, freetext. 페이지 인덱스는 0부터 시작합니다. 암호화된 소스는 거부됩니다(ENCRYPTED_SOURCE) — 먼저 decrypt_pdf를 실행(서명/AcroForm은 제거됨)하여 주석을 단 후, 다시 encrypt_pdf를 실행하세요.

draft_governance_issue

거버넌스 요구사항을 충족하는 GitHub issue를 사람이 검토하고 제출할 수 있도록 로컬에서 초안을 작성합니다. 서버는 GitHub에 연락하지 않습니다 (유일한 외부 연결 경로는 운영자가 PAdES 장기 검증용으로 구성한 TSA / OCSP / CRL 엔드포인트뿐이며 — 외부 네트워크 및 이그레스 참고); 초안 Markdown과 함께 기계가 읽을 수 있는 규정 준수 보고서를 반환합니다.

{
  "title": "add_table drops the caption on the second page",
  "issueType": "bug",
  "summary": "The table caption is only rendered on page 1 when repeatHeader is true.",
  "reproduction": { "command": "add_table with caption + repeatHeader over 2 pages (examples/bordered-table.json, then inspect_pdf)", "result": "Page 2 has no caption row." },
  "expectedBehavior": "The caption repeats with the header on every page.",
  "duplicateSearchPerformed": true
}

런타임 의존성을 추가하거나, 재현 절차를 누락하거나, duplicateSearchPerformed: false로 지정하는 초안은 GOVERNANCE_VIOLATION 오류로 거부됩니다. 전체 human-in-the-loop 계약은 docs/guides/AI_GOVERNANCE.md에서 확인하세요.

verify_pdf, add_attachment, extract_text

자세한 내용은 docs/AI_GUIDE.md의 해당 섹션과 docs/KNOWLEDGE_BASE.md의 참조 자료를 확인하세요. 바로 실행할 수 있는 예제는 examples/에 있습니다.

🔐 보안 모델

pdfnative-mcp는 호스트 프로세스 내부에서 실행되며 stdio MCP 서버(또는 루프백 전용 HTTP 엔드포인트)를 제공합니다. 구성된 샌드박스 외부에서는 어떤 I/O도 수행하지 않습니다.

• 파일 쓰기는 PDFNATIVE_MCP_OUTPUT_DIR에 의해 제한됩니다. 이 값이 설정되지 않으면 file 출력 모드는 SecurityError 오류로 거부됩니다.

• 경로 붙석은 절대경로, 상위 경로 탐색(..), NUL 바이트, 그리고 .pdf 외의 확장자를 거부합니다.

• 출력 크기는 호출당 50 MB로 제한됩니다.

• 입력은 모든 도구의 경계에서 엄격한 JSON Schema와 Zod 런타임 체크를 통해 검증됩니다. 알 수 없거나 잘못 표기된 키(최상위·중첩)는 VALIDATION_ERROR 오류로 거부되며, base64 / DER 페이로드는 파서가 실행되기 전에 정전성 검사를 받습니다(data: 접두사 허용, PEM또는 이중 인코딩된. (입력은 해결책과 함께 거부됩니다).

• HTTP 전송 (PDFNATIVE_MCP_PORT)는 프백에만 바인딩됩니다. PDFNATIVE_MCP_HTTP_TOKEN이 설정되지 않은 경우 인증이 없으며, 설정된 경우 유효한 Bearer 토큰이 없으면 401이 반환됩니다.

외부 네트워크 및 이그레스

서버는 기본적으로 외부 네트워크 호출을 수행지 않습니다. 수행할 수 있는 유일한 이그레스는 운용자가 PAdES 장기 검증을 위해 환경에 설정한 RFC 3161 / OCSP / CRL 엔드포인트로만 이동합니다(PDFNATE_MCP_TSA_URL, PDFNATIVE_MCP_REVOCATION, PDF_NATIVE_MCP_NETWORK_ALLOWED_HOSTS) — 도구 인자로 제공된 URL에는 절대 연락하지 않으며, GitHub나 원격지에 있는 것도 무엇에로 이동하지 않습니다. 이런 구성이 없이 sign_pdf timestamp: true, timestamp_pdf, add_ltv mode: 'online'은 멈버에 TSA_NOT_CONFIGURED / REVOCATION_NOT_CONFIGURED 오류와 함의 실패하며 문서에는 아무 것도 하지 않습니다. add_ltv mode: 'offline'은 네트워크 접이 전혀 없이 호출자에게 받은 MRI를 내장합니다.

OCSP / CRL URL은 PDF 내부의 신되지 문화된 인가 인증서 확장 영역(AIA / CRL 배포 지점)에서 옵니다. 따라서 모든 요청은 SSRF 가드를 통과해야 합니다:

• 호스트는 운영자 Ann- allow-list(host, host:port 또는 *.suffix)와 일치해야 하며, 륀일 와일드카드(*)만으로 된 항로그 거부됩니다. 항목은 호스트이며 (not URL)입니다. host:port 항목은 명시적으로 포트와 함께 명기된 URL일 경우에만 일치합니다 (URL 박서는 :80/443 기본 포트를 생략하므로 해당 포트는 호스트만 len항 등록). 와이드카드 항목은 포트를 포함할 수 없으며, IDN 호스트명은 퓨니코드(xn--…)로 등록, IPv6 리터럴은 대괄호([2001:db8::1])로 표시해야 합니다.

• http: / https: 프로토콜만 허용하며, independently 내장 인증 정보는 허용되지 않고, 리다이렉트는 절속 방생하지 않습니다.

• loopback, 기밀 link-local, 비공개 private, unique-local, 통신사업자(CG-), unspecified, 그리고 “멀티브 (मulticast) 주소 리터럴 — 거부되든 decimal / octal / hex 표기와 IPv4-ma은-apped IPv6를 포함 — These are allowed to be allowed only if exactly. Guard checks literals only: a listed hostname that resolves to an internal address (DNS rebinding)를 감지하지 않습니다 (리졸버를 추가하지 않으면 이를 거부할 방법이 업기 때문; 당신이 제어할 수 있는 호스트 only 등록).

• 요청별 타임아웃 (PDFNATIVE_MCP_NETWORK_TIMEOUT_MS) 및 응답 크기 상한(TSA 256 KiB, OCSP 1 MiB, CRL 16 MiB)은 스트리밍밍에서 강제됩니다. 따라서 매우 큰 응답은 버퍼에 저장되는 대신 보통할 수 있습니다.

• 응답자(responder)가 반환한 OCSP 응답과 CRL은 add_lt_mode: 'online'에서 사용하기 전에 파서 검사를 수행합니다.

• TSAR URL은 운영자 신외 근거로 검사됩니다(scheme + 접차 확인만 하며, 인증 정보는 확인하지 않음). PDFNATE_MCP_TSA_AUTH 시크릏 정보는 로그나 오류 메시지에 나타나지 않습니다.

Providers(자원 공급자)는 호출 시 각 영향을 생성되고 pdfnative의 per-call 옵션으로 전달됩니다. 프로세스 전역 providers setter는 업 사용되지 않으므로, 동시 처리되는 요청들은 사이에 상태 공유가 없습니다. server/discover 응답은 현재 이그레스 정책을 (항목의 종류만, 시크릏(secrets)는 제외) 보고합니다.

책임 있는 문정보 자례: SECURITY.md에, 운영자 설정계 안내는 docs/guides/LTV.md를 참고하세요.

🧪 개발

git clone https://github.com/Nizoka/pdfnative-mcp.git
cd pdfnative-mcp
npm install
npm run typecheck
npm run lint
npm test
npm run build
npm run validate:pdfa     # advisory: veraPDF over the 26-file PDF/A corpus (24 validated; skips when veraPDF is absent; VERAPDF_REQUIRED=1 fails closed)
node scripts/tool-shape.mjs --write   # only after a deliberate tools/list schema change (catalogue parity fixture)

stdio로 밍 “스모크 테스트”를 실행하세요:

node dist/cli.js
# In another terminal, send a JSON-RPC initialize request via stdin (e.g. with mcp-inspector).

기여자: 로컬 검증 워크플로우 전체(game gate, examples-as-tests, 생성된 PDF 형식가ộc 구조 검증 (assertValidPdf, inspect_pdf, validate_pdf, verify_pdf), 뷰어에서 결과를 열어 확인, veraPDF 외부 PDF/A 검사, MCP Inspector)는 docs/guides/LOCAL_TESTING.md을 확인하세요.

📣 릴리이스 프로세

pdfnative-mcp은 pdfnative과 동일한 릴리이스 방식을 따릅니다:

• 태그별 릴리스 노트 파일: release-notes/vX.Y.Z.md

• CHANGELOG.md 은 각 릴리미스 릴리스트를 반영합니다.

• GitHub Release 게시명은 release-notes/vX.Y.Z.md에서 가져옵니다.

• npm 배포는 NPM_TOKEN 없이 GitHub Actions Trusted Discloser(OIDC)를 통해 수행합니다.

정식 구성과 배포 체크리스트 병목은 release-notes/TEMPLATE.md를 확인하세요.

📁 프로젝크 트 구조

src/
├── cli.ts                      # entrypoint: stdio (default) or Streamable HTTP (PDFNATIVE_MCP_PORT)
├── http.ts                     # Node http <-> Web Request/Response bridge + Host/Origin loopback guard
├── auth.ts                     # opt-in HTTP bearer token (PDFNATIVE_MCP_HTTP_TOKEN)
├── base64.ts                   # base64 / DER boundary decoding with agent-facing diagnostics
├── index.ts                    # public library exports
├── server.ts                   # Server factory, tool registry, cache hints, SERVER_INSTRUCTIONS
├── network.ts                  # operator-configured TSA / OCSP / CRL egress + SSRF guard
├── print.ts                    # print-production schema (boxes, bleed, marks, userUnit, outputIntent, metadata, creationDate)
├── diagnostics.ts              # PDF/A diagnostics sink, strict / includeDiagnostics / embedFonts
├── chart.ts                    # charts v2 schema + ChartBlock mapper
├── blocks.ts                   # the 7 extended document blocks (table, image, link, toc, barcode, svg, formField)
├── layout.ts                   # pageSize / margins / header & footer templates / compress / debug / encrypt (PdfLayoutOptions)
├── table.ts, barcode.ts, form.ts, image.ts   # bodies shared by a dedicated tool and its inline block
├── watermark.ts                # text and/or image watermark + position, PDF/A-1b transparency guard
├── encryption.ts               # password + encrypt schema (Standard Security Handler), decrypt error mapping
├── inflate-cap.ts              # PDFNATIVE_MCP_MAX_INFLATE_BYTES (engine decompression cap) + PDF_PARSE_FAILED mapping
├── output.ts                   # sandboxed file writer / base64 emitter (single + multi)
├── text.ts                     # newline sanitizer (Safe PDF/A)
├── doc-features.ts             # nested lists, outline, page labels, viewer prefs (+ print-dialog defaults)
├── pagetree.ts                 # page-tree error mapping (merge/split/extract)
├── crypto-provider.ts          # node:crypto signing provider for DER keys (SHA-256/384/512); verification stays pure JS
├── projection.ts               # verbosity / fields projection for the seven read tools
├── errors.ts                   # ToolError, SecurityError, GovernanceError
└── tools/
    ├── generate-basic-pdf.ts
    ├── inspect-layout.ts
    ├── add-barcode.ts
    ├── sign-pdf.ts
    ├── add-ltv.ts
    ├── timestamp-pdf.ts
    ├── update-metadata.ts
    ├── add-international-text.ts
    ├── add-table.ts
    ├── add-form.ts
    ├── read-form-fields.ts
    ├── fill-form.ts
    ├── add-chart.ts
    ├── embed-image.ts
    ├── inspect-pdf.ts
    ├── verify-pdf.ts
    ├── validate-pdf.ts
    ├── add-attachment.ts
    ├── extract-attachments.ts
    ├── extract-text.ts
    ├── merge-pdfs.ts
    ├── split-pdf.ts
    ├── extract-pages.ts
    ├── annotate-pdf.ts
    ├── encrypt-pdf.ts
    ├── decrypt-pdf.ts
    ├── draft-governance-issue.ts
    └── prepare-signature-placeholder.ts
scripts/
├── verify-issue.mjs            # governance draft checker (npm run verify:issue)
├── validate-pdfa.mjs           # veraPDF run (npm run validate:pdfa; PASS/FAIL/XFAIL/XPASS/INFRA/SKIP)
├── generate-pdfa-corpus.mjs    # builds the 26-file PDF/A corpus (24 validated incl. 3 negative canaries, 2 page-tree outputs)
└── tool-shape.mjs              # structural tools/list fingerprint (--write refreshes tests/_fixtures/tool-shape.json)
.github/workflows/ci.yml        # Linux (Node 22 / 24) + Windows quality gate
.github/workflows/verapdf.yml   # non-blocking veraPDF CI job (SHA-256-pinned installer, VERAPDF_REQUIRED=1)
tests/                          # vitest suites (one per tool / module; document-blocks, layout-options, inspect-layout,
                                #   watermark, inflate-cap, catalogue-parity + catalogue-superset vs the 1.5.0 fixture)

Pe Ploadmap

v1.6.0은 출시되었습니다 (전체 엔진 커버밍 — 13 종류의 블록, 레이아웃 옵션, inspect_layout — PAdES LTV ladder, 인쇄 production, 카트트 v2, update_metadata, MCP 2026-07-28). 전체 계획 — 출시된 이정도, 진행 중인 작업, 장기 방향 — 로드맵인 ROADMAP.md에서 확인할 수 있습니다.

아직은 보류되어 있습니다:

• redact_pdf — pdfnative에는 콘텐츠 제거 API가 없습니다. 오버레이만 하는 “redaction은 안전을 가장하게 만드는 것 입니다.

• 네이티브 ECDSA 검증 — pdfnative는 ecdsaVerifyHash를 내보내지 않으므로, verify_pdf는 P-256용 순수-JS 경로를 유지합니다.

• HTTP 페이지 스트리밍 dump — MCP 2026-07-28은 여전히 partial structuredContent를 지원하지 않으므로 대규모 결과는 원샷으로만 반환합니다.

새로운 기능에 대한 아이디어가 있으세요? 이슈 또는 PR을 열고 알려주세요.

⭐ 스타(Star) 주세요

pdfnative-mcp가 유용하다면, ⭐ 이 저장소를 눌러주세요. 그리고 밑에 있는 엔진 Nizoka/pdfnative도 함께 고려해 주세요. 별빌은 다른 사람들이 프로젝트를 발견하고 지속 개발을 지속하는 데 도움이 됩니다.

✉ 참여 방법

기여는 언제나 환영합니다. CONTRIBUTING.md를 읽고 오 이슈를 확인한 뒤 행동 강령을 준수해 주세요.

📄 라이센스

MIT © 2026 Nizoka

pdfnative-mcp은 pdfnative와 [Model Context Protocol TypeScript SDK](https://github.com/modelcontext protocol/typecript-sdk) 기반으로 구축되었습니다.