EEager/pdf-mcp-server

PDF MCP 서버

|

PDF 파싱 도구를 MCP(Model Context Protocol) 서버로 래핑해서 Cursor IDE와 연동하는 실용적인 프로젝트입니다.

✅아키텍처 개요

PDF MCP 서버는 MCP 프로토콜을 통해 Cursor IDE와 PDF 파일 사이의 다리 역할을 합니다.

✅왜 만들었나?

Cursor IDE의 AI는 기본적으로 PDF 파일을 읽지 못합니다. 문서나 논문, PDF 자료를 분석하려고 할 때마다 답답했죠. 이 MCP 서버가 그 문제를 해결해줍니다.

현실적 고백: 혁신적인 건 아닙니다. 기존 PDF 파싱 라이브러리를 MCP 인터페이스로 감싼 것뿐이에요. 하지만 때로는 가장 실용적인 해결책이 가장 지루한 해결책이기도 하죠.

✅현재 상태

🔧완성된 것들:

• McpServer API 기반 MCP 서버 구조
• pdf-parse 라이브러리를 이용한 PDF 텍스트 추출
• PDF 메타데이터 추출
• PDF 파일 검증 기능
• 페이지별 텍스트 추출 (범위 지정, 특정 페이지 선택)
• 완전한 테스트 스위트 (8/8 테스트 통과)
• TypeScript 빌드 시스템
• Docker 기반 개발 환경
• Cursor IDE 연동 완료 및 실제 동작 확인

🔧 다음 단계:

• 표 데이터 추출
• 이미지 추출
• GitHub Actions CI/CD 설정

✅기능

현재 구현된 기능

• extract_pdf_text: PDF 파일에서 전체 텍스트 추출 (크기 제한: 100KB)
• extract_pdf_pages: PDF 특정 페이지 또는 페이지 범위 텍스트 추출 (크기 제한: 200KB)
• get_pdf_metadata: PDF 메타데이터 추출 (제목, 작성자, 생성일 등 + 텍스트 미리보기 200자)
• validate_pdf: PDF 파일 형식 및 크기 제한 검증

✅기술 스택

• TypeScript - 래퍼 프로젝트라도 타입 안정성은 중요하니까
• pdf-parse - 검증된 PDF 파싱 라이브러리
• @modelcontextprotocol/sdk v1.15.1 - 최신 MCP SDK
• zod - MCP 도구 스키마 검증
• Jest - 테스트 프레임워크
• Docker - 크로스 플랫폼 개발 환경

✅설치

필수 요구사항

• Docker Desktop (WSL 통합 활성화)
• Cursor IDE

개발 환경 설정

1. 리포지토리 클론:

git clone https://github.com/EEager/pdf-mcp-server.git
cd pdf-mcp-server

2. 의존성 설치:

docker run -it --rm -v ~/workspace/pdf-mcp-server:/app -w /app node:20 npm install

3. 프로젝트 빌드:

docker run --rm -v ~/workspace/pdf-mcp-server:/app -w /app node:20 npx tsc

4. 프로젝트 테스트(선택사항):

# 실행해보고 docker ps -a에서 잘 돌아가는지 확인하세요
docker run -it --rm -v ~/workspace/pdf-mcp-server:/app -w /app node:20 node dist/index.js

✅Cursor IDE 설정

[Cursor Settings] - [Tools & Integrations] - [Add Custom MCP] 를 통해 mcp.json 설정 파일을 수정할 수 있습니다.

중요: 파일 접근 권한 설정

PDF MCP 서버는 Docker 볼륨 마운트를 통해 파일에 접근합니다. 마운트된 디렉토리의 파일만 읽을 수 있습니다.

Cursor MCP 설정 파일(~/.cursor/mcp.json 또는 ~/.config/cursor/mcp.json)에 추가: (설정파일은 cursor update 상황에 따라 바뀔 수 있슴둥)

{
  "mcpServers": {
    "pdf-parser": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        // !본인의 pdf-mcp-server 설치 경로로 수정하세요. 아래의 경우 wsl환경의 workspace 경로입니다.
        "-v", "\\\\wsl$\\Ubuntu\\home\\eager\\workspace\\pdf-mcp-server:/app", 

        // !PDF 파일들이 저장된 폴더 경로로 수정하세요. 아래의 경우 cursor_mcp_dir 폴더 밑에 pdf 파일들이 존재합니다. 
        "-v", "D:\\cursor_mcp_dir:/workspace",
        "-w", "/app",
        "node:20",
        "node",
        "dist/index.js"
      ]
    }
  }
}

설정 설명:

• \\\\wsl$\\Ubuntu\\home\\eager\\workspace\\pdf-mcp-server:/app: MCP 서버 코드 마운트
• D:\\cursor_mcp_dir:/workspace: PDF 파일이 있는 디렉토리 마운트 (필수!)
• PDF 파일은 /workspace/ 경로로만 접근 가능

⚠️ 중요: D:\\cursor_mcp_dir를 실제 PDF 파일들이 있는 Windows 디렉토리로 변경하세요.

실행 중인 MCP 서버 확인

Cursor IDE는 자동으로 Docker 컨테이너를 실행합니다:

# 실행 중인 컨테이너 확인
docker ps

# 예시 출력:
# CONTAINER ID   IMAGE     COMMAND                  CREATED       STATUS       NAMES
# abc123def456   node:20   "node dist/index.js"     2 minutes ago Up 2 minutes suspicious_turing

✅cursor IDE에서 정상적으로 mcp등록이 된 경우

mcp.json를 저장한 후, 바로 mcp 등록이 된것을 확인할 수 있습니다.

✅사용법

설정이 완료되면 Cursor IDE에서 다음과 같이 사용할 수 있습니다:

1. PDF 전체 텍스트 추출 (extract_pdf_text)

사용자: "/workspace/document.pdf 파일의 내용을 읽어줄 수 있어?"

응답: PDF 파일에서 추출된 전체 텍스트(최대 100KB)와 페이지 수, 기본 메타데이터가 함께 제공됩니다.
큰 파일은 자동으로 잘림 처리됩니다.

2. PDF 페이지별 텍스트 추출 (extract_pdf_pages) ⭐ 신기능

사용자: "/workspace/document.pdf 파일의 5-10페이지만 읽어줄 수 있어?"
또는: "/workspace/document.pdf 파일의 1, 3, 5페이지만 추출해줘"

응답: 지정된 페이지들의 텍스트(최대 200KB)가 페이지별로 구분되어 제공됩니다.

페이지별 추출 옵션:

• 페이지 범위: startPage: 5, endPage: 10 (5-10페이지)
• 특정 페이지: pageNumbers: [1, 3, 5, 7] (1, 3, 5, 7페이지)
• 시작 페이지부터: startPage: 10 (10페이지부터 끝까지)

3. PDF 메타데이터 확인 (get_pdf_metadata)

사용자: "/workspace/document.pdf 파일의 메타데이터가 뭐야?"

응답: 제목, 작성자, 생성일, 수정일, 페이지 수와 텍스트 미리보기(200자)가 제공됩니다.

4. PDF 파일 검증 (validate_pdf)

사용자: "/workspace/document.pdf 파일이 유효한 PDF인가?"

응답: 파일 형식, 크기 제한, 접근 가능성을 확인한 검증 결과가 제공됩니다.

MCP 도구 목록

서버가 제공하는 MCP 도구들:

✅실제 시험 결과

예시: 962페이지 딥러닝 교재 분석

1. validate_pdf

입력:

{
  "filePath": "/workspace/01_study/ai_ml/pytorch_deep_learning_Intro.pdf"
}

결과:

{
  "isValid": true,
  "filePath": "/workspace/01_study/ai_ml/pytorch_deep_learning_Intro.pdf",
  "message": "PDF file is valid"
}

2. get_pdf_metadata

입력:

{
  "filePath": "/workspace/01_study/ai_ml/pytorch_deep_learning_Intro.pdf"
}

결과:

{
  "text": "Contents\n문서정보1\n00. 입문자들을위한조언(Q&A)2\n00.교육문의8\n00.\n유료\nE‑book\n안내\n9\n00.책과저자소개하기10\n01. [기초] ‑딥러닝을시작하기전에11\n01‑01코랩(Colab)과아나콘다12\n1.아나콘다(Anaconda)설치...",
  "pageCount": 962,
  "title": "딥 러닝 파이토치 교과서 - 입문부터 파인튜닝까지",
  "author": "이 책은 ...님이 구매하신 전자책입니다.",
  "creator": "WikiDocs",
  "producer": "xdvipdfmx (20210609)",
  "creationDate": "D:20250521134136+09'00'"
}

3. extract_pdf_text

입력:

{
  "filePath": "/workspace/01_study/ai_ml/pytorch_deep_learning_Intro.pdf"
}

결과:

{
  "text": "Contents\n문서정보1\n00. 입문자들을위한조언(Q&A)2...[100KB 제한으로 잘림]",
  "pageCount": 962,
  "metadata": { "title": "딥 러닝 파이토치 교과서...", "author": "..." },
  "truncated": true,
  "originalLength": 868068
}

4. extract_pdf_pages (신기능!) ⭐

입력 - 특정 챕터 읽기:

{
  "filePath": "/workspace/01_study/ai_ml/pytorch_deep_learning_Intro.pdf",
  "startPage": 50,
  "endPage": 60
}

입력 - 특정 페이지들만:

{
  "filePath": "/workspace/01_study/ai_ml/pytorch_deep_learning_Intro.pdf",
  "pageNumbers": [1, 5, 10, 100]
}

결과:

{
  "text": "--- 페이지 50 ---\n파이토치 기초 설명...\n\n--- 페이지 51 ---\n텐서 연산에 대한 내용...\n\n--- 페이지 52 ---\n...",
  "pageCount": 962,
  "extractedPages": [50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60],
  "metadata": { "title": "딥 러닝 파이토치 교과서...", "author": "..." },
  "truncated": false,
  "originalLength": 15420
}

Cursor IDE의 채팅에서 MCP 도구 사용 결과

✅개발

프로젝트 구조

pdf-mcp-server/
├── src/
│   ├── index.ts          # MCP 서버 진입점
│   ├── pdf-parser.ts     # PDF 파싱 로직
│   └── types.ts          # TypeScript 타입 정의
├── tests/
│   └── pdf-parser.test.ts # Jest 테스트 스위트
├── docs/
│   └── images/           # 문서 이미지
├── dist/                 # 빌드 결과물
├── package.json
├── tsconfig.json
└── README.md

개발 스크립트

# 빌드 (필수)
docker run --rm -v ~/workspace/pdf-mcp-server:/app -w /app node:20 npx tsc

# 테스트
docker run -it --rm -v ~/workspace/pdf-mcp-server:/app -w /app node:20 npm test

# 서버 실행 테스트 (선택사항 - Cursor가 자동으로 실행함)
docker run -it --rm -v ~/workspace/pdf-mcp-server:/app -w /app node:20 node dist/index.js

참고: Cursor IDE가 MCP 서버를 자동으로 Docker 컨테이너로 실행하므로, 개발 시에는 빌드만 하면 됩니다.

디버깅 및 로그 확인

Docker 컨테이너 로그 확인

# 실행 중인 컨테이너 확인
docker ps

# 컨테이너 로그 확인 (컨테이너 이름으로)
docker logs <CONTAINER_NAME>

# 실시간 로그 확인
docker logs -f <CONTAINER_NAME>

예시 로그 출력

{"result":{"content":[{"type":"text","text":"{\n  \"isValid\": true,\n  \"filePath\": \"/workspace/01_study/ai_ml/pytorch_deep_learning_Intro.pdf\",\n  \"message\": \"PDF file is valid\"\n}"}]},"jsonrpc":"2.0","id":16}

MCP Inspector로 테스트

# MCP 서버 기능 테스트
cd ~/workspace/pdf-mcp-server
npx @modelcontextprotocol/inspector node dist/index.js

✅구현 노트

해결된 환경 문제들

• WSL/Windows 경로 충돌: Docker 컨테이너화로 해결
• npm 권한 문제: Docker 격리로 파일 시스템 충돌 방지
• MCP SDK 버전 불일치: 존재하지 않는 0.2.0에서 최신 1.15.1로 업데이트
• API 변경: 레거시 Server에서 새로운 McpServer API로 마이그레이션
• 대용량 텍스트 처리: Cursor IDE 터짐 방지를 위한 텍스트 크기 제한
• 날짜 타입 오류: 안전한 날짜 변환 함수로 해결

아키텍처 결정사항

• 모듈러 설계: PDF 파싱 로직과 MCP 서버 로직 분리
• 포괄적 테스트: 목킹된 의존성으로 완전한 테스트 커버리지
• 타입 안전성: zod 검증과 함께 엄격한 TypeScript 설정
• 에러 핸들링: 파일 작업과 PDF 파싱에 대한 우아한 에러 처리
• 성능 최적화: 텍스트 크기 제한으로 클라이언트 안정성 확보
• 페이지별 처리: pdf-parse의 pagerender 콜백으로 페이지 단위 텍스트 추출

✅문제 해결

일반적인 문제들

PDF 파일을 읽을 수 없음:

• Docker 볼륨 마운트 설정 확인: "D:\\your_pdf_dir:/workspace"
• 파일 경로가 /workspace/ 로 시작하는지 확인
• Docker Desktop WSL 통합이 활성화되어 있는지 확인

MCP 서버 연결 실패:

• Docker Desktop이 실행 중인지 확인
• Cursor MCP 설정 파일 경로가 올바른지 확인
• Cursor IDE 재시작

빌드 오류:

• WSL에서 빌드: docker run --rm -v ~/workspace/pdf-mcp-server:/app -w /app node:20 npx tsc
• 의존성 재설치: docker run -it --rm -v ~/workspace/pdf-mcp-server:/app -w /app node:20 npm install

제한사항

• 파일 접근: Docker 볼륨 마운트된 디렉토리의 파일만 접근 가능
• 파일 크기: 큰 PDF(100MB 이상)는 성능상 이유로 거부됨
• 텍스트 크기: 전체 텍스트는 100KB, 페이지별 텍스트는 200KB로 제한 (Cursor IDE 안정성)
• 메타데이터: 텍스트 미리보기는 200자로 제한
• 복잡한 레이아웃: 표나 다단 레이아웃은 완벽하게 파싱되지 않을 수 있음
• 스캔된 PDF: OCR 지원은 계획 중이지만 아직 미구현

라이선스

MIT 라이선스 - 공유가 배려니까, 그리고 어차피 래퍼일 뿐이니까.

감사의 말

• pdf-parse - 실제 PDF 파싱의 무거운 작업을 담당
• MCP Protocol - 이런 연동을 가능하게 해준
• Cursor IDE - 확장할 가치가 있는 IDE를 만들어준
• Docker 커뮤니티 - 환경 호환성 악몽을 해결해준