NextPDF Connect — MCP 전송

한눈에 보기

MCP 전송은 bin/nextpdf-mcp를 로컬 하위 프로세스로 실행합니다. 표준 입력과 출력을 통해 JSON-RPC 2.0으로 통신합니다. 서버는 날짜로 버전이 지정된 MCP 리비전 2025-06-18을 구현합니다.

설치

composer require nextpdf/server

개념 개요

MCP stdio 모델에서 클라이언트는 서버를 하위 프로세스로 실행합니다. 클라이언트는 줄바꿈으로 구분된 JSON-RPC 메시지를 주고받습니다. 메시지는 한 줄에 하나이며, 내부 줄바꿈 없이 UTF-8입니다. 서버는 표준 출력에 유효한 MCP 메시지만 쓰고 로깅에는 표준 오류를 사용합니다. 이 구현은 로그 줄이 프로토콜 스트림을 절대 손상시키지 않도록 감사 로거를 표준 오류로 정확히 라우팅합니다. 이 프레이밍은 공식 MCP 사양 리비전 2025-06-18에 정의되어 있습니다. 이 사양은 게이팅된 표준 코퍼스에 포함되지 않으므로 URL로 인용됩니다: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports.

NextPDF Connect는 stdio 전송을 구현합니다. MCP 사양은 Streamable HTTP 전송도 정의합니다. 사양은 클라이언트가 가능한 한 stdio를 지원해야 하며, 서버는 stdio만 구현해도 된다고 명시합니다. 동일한 도구에 네트워크로 접근하려면 대신 REST 또는 gRPC 전송을 사용하십시오 — /transports/rest/ 및 /transports/grpc/를 참조하십시오.

API 표면

메서드

메서드	동작
`initialize`	프로토콜 버전, 기능, 서버 정보를 반환합니다
`notifications/initialized`	알림(`id` 없음); 응답 없이 확인됩니다
`tools/list`	등록된 도구를 나열합니다; 선택 사항인 `params.category` 필터
`tools/call`	도구를 실행합니다 — 이름은 `params.name`, 인수는 `params.arguments`

그 밖의 메서드는 method-not-found(-32601)를 반환합니다. 유효한 JSON-RPC 2.0이 아닌 메시지는 invalid-request(-32600)를 반환합니다; 파싱할 수 없는 입력은 parse-error(-32700)를 반환합니다. 중복된 요청 id는 다시 실행하지 않고 64개 항목 버퍼에서 캐시된 이전 응답을 반환합니다.

initialize 응답

이 initialize 결과는 protocolVersion 2025-06-18, serverInfo.name: NextPDF Connect, 그리고 capabilities 객체를 보고합니다. 표준 tools 기능 외에도 서버는 capabilities.nextpdf 블록을 추가합니다:

tiers — 티어별로 런타임에 등록된 도구 수(core / pro / enterprise)입니다.
tool_count — 런타임에 계산되는 등록된 도구의 총 개수입니다.
risk_model_version — 서버가 적용하는 위험 모델의 버전입니다.
hitl_enabled — true; 확인 게이트가 활성화되어 있습니다.

tool_count는 이 배포에 대한 권위 있는 숫자입니다. 이 값은 문서화된 상수가 아니라 런타임 카운트입니다. /connect/tool-catalog/를 참조하십시오.

코드 샘플 — 빠른 시작

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

코드 샘플 — 프로덕션

카테고리로 목록을 필터링하면 카탈로그 범위가 하나의 도메인으로 좁혀집니다:

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"category":"diagnostic"}}
EOF

카테고리 값은 각 도구가 선언한 카테고리를 따릅니다(예: document, diagnostic).

엣지 케이스와 주의 사항

API 키 없음. stdio 전송에는 네트워크 리스너도 베어러 토큰도 없습니다. 신뢰 경계는 MCP stdio 모델에 따라 운영 체제의 프로세스 경계입니다. 이를 네트워크에 연결하지 마십시오.
확인 챌린지는 인밴드 방식입니다. ApprovalRequired 도구는 오류가 아니라 챌린지 텍스트와 일회용 토큰을 내용으로 하는 성공적인 JSON-RPC 응답을 반환합니다. /connect/hitl-risk-tiers/를 참조하십시오.
알림은 무응답입니다. id가 없는 메시지는 응답을 생성하지 않습니다. 핸드셰이크는 initialize(id 포함), 그다음 initialized 알림, 그다음 id가 포함된 호출 순입니다.

성능

MCP 서버는 파이프를 통해 한 번에 하나의 요청을 처리하는 단일 프로세스입니다. 네트워크 왕복은 없습니다. 지연 시간은 기반 엔진 작업에 좌우됩니다.

보안 참고 사항

이 전송은 이를 실행하는 클라이언트의 신뢰를 상속합니다. 하위 프로세스를 로컬에 유지하십시오. API 키가 없더라도 고위험 도구는 여전히 사람의 확인으로 게이팅됩니다. /connect/security-and-operations/를 참조하십시오.

적합성

stdio 프레이밍과 initialize/lifecycle 동작은 공식 Model Context Protocol 사양 리비전 2025-06-18을 준수합니다:

Transports(전송): https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
Lifecycle(수명 주기): https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

MCP 사양은 게이팅된 표준 코퍼스에 없으므로 reference_id를 갖지 않습니다; 위의 공식 URL이 공식 인용입니다.

상업적 맥락

tools/list는 nextpdf/premium이 서버와 함께 설치된 경우에만 Pro 및 Enterprise 도구를 반환합니다. 전송 자체는 설치된 티어와 관계없이 동일합니다.