doc-extract-mcp

LLM(대형 언어 모델)에 구조화된 데이터 추출 작업을 위한 결정적 문서 도구를 제공하는 MCP(Model Context Protocol) 서버입니다. LLM이 읽기와 추출 추론을 담당하며, 이 서버는 언어 모델에 맡기면 안 되는 부분 — 신 있는 파일 접근, 파싱, 청크, JSON Schema 검증, 안전한 파일 출력 — 을 제공합니다.

Koray Nar가 구축 중인 AI 문서 자동화 작업을 위한 포트폴리오 프로젝트로 제작되었습니다. — 목표 사협은 지저분한 PDFs(구매 주문서, 인보이스, 보과서)를 스키마 검증된 JSON으로 변환하는 것입니다. 공개 포트폴리오의 일부로 출計되었으며, Claude Code와 Claude Desktop, 그리고 기타다른 모든 MCP 클라이언트와 함께 사용 을 수 있습니다.

이♀

추출 playwright는 예측 가한 지점에서 실패합니다. — фай일 내용을 환각하거나, 긴 문서를 놓치거나, 목표 스키마와 거이 비슷한 JSON를 조용이 만들은 혹, 출력을 아니 기대는 않습니다. 이 서버는 이러한 실패 요인을 제거합니다.

• 파일 접근은 허용된 트 한개(DOC_EXTRACT_ROOT)로 제한됩니다.

• PDF 텍스트트에는 명시적 --- page N --- 마커서가 불어 있어, "page 3"와 인용은 실주로 3 page를 기리킵니다.

• 긴 문서는 오버플되지 않게 계산되며 오버lap과 page 힌트와 함께 청크됩니다.

• 추출된 JSON은 JSON Schema(Draft 2020-12)를 대조하여 검증되며 모든 오류가 JSON Pointer 경로와 함께 보고됩니다 — 첫 번째만이 아니라모든, 따라서 모델이 모든 오류를 한 번에 수정할 수 있습니다.

• (JSON 또는 CSV) 출력은 서버가 작성을 합니다. 이 역시 중국 럼— 파일 저장 내용의 patent — 내에서 이루어지며, 행/바이 헤수가 포함됩니다.

Related MCP server: BigContext MCP

도구

모든 경로 인자는 허용된 루트를 벗어나면 거부됩니다 (path traversal로부터 가드). glob_pattern 동일하게 제한됩니다: 절대 경로 패턴과 ..을 포함하는 패턴은 거부되고, 외로 해석되는 매치(예: symlink에 의해)는 목록에서 조용히 내어집니다. 가드 실패는 MCP 도구 오로로 승출되어, 호출한 모델이 마스킹된 일반화 오류가 아닌 실주 원인을 볼 수 있습니다.

시작하기

Python 3.11+ 및 uv가 필요합니다.

git clone https://github.com/koraynar/doc-extract-mcp.git
cd doc-extract-mcp
uv venv
uv pip install -e .

Standalone (stdio) 실행:

DOC_EXTRACT_ROOT=/path/to/your/documents uv run doc-extract-mcp

Claude Code

claude mcp add doc-extract --env DOC_EXTRACT_ROOT=/path/to/your/documents \
  -- uv run --directory /absolute/path/to/doc-extract-mcp doc-extract-mcp

Claude Desktop

claude_desktop_config.json에 다음을 추가합니다:

{
  "mcpServers": {
    "doc-extract": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/doc-extract-mcp",
        "doc-extract-mcp"
      ],
      "env": {
        "DOC_EXTRACT_ROOT": "/path/to/your/documents"
      }
    }
  }
}

DOC_EXTRACT_ROOT는 지정되지 않으면 서버의 작업 디렉터리를 기본으로 사용합니다. 문서 파일이 있는 폴더로 설정하면 그 안만 읽거나 쓸 수 있습니다.

일반 작업의 흐름

1. list_documents(".", "*.pdf") — 인수서 등을 찾습니다.

2. document_info("invoice.pdf") — 페이지 수를 확인합니다.

3. read_document("invoice.pdf", "1-3") 또는 chunk_document(...) — 텍스트를 읽습니다.

4. LLM이 필드를 JSON으로 구성합니다.

5. validate_json(data, json_schema) — 보고된 모든 오류를 수정하고 다시 검증합니다.

6. save_structured("out/invoice.json", data, "json") — 결과를 저장합니다.

한계 (솔직히)

• 텍스트 기반 PDF만 지원합니다. 추출은 pypdf를 사용하며, 스캔 또는 이미지 전용 PDF의 텍스트는 비어 있습니다. OCR은 없습니다.

• 추출 품질은 달라질 수 있습니다 PDF가 만들어진 방식에 따라 다릅니다. 복잡한 위젯(복층이 있는, 표 붙)는 읽는 순서가 완전하지 않을 수 있습니다. 이는 상속받은 pypdf의 특성입니다.

• .docx / .xlsx 지원은 없습니다. 지원되는 파일의 확장자는 .pdf, .txt, .md, .csv, .json입니다.

• 서버는 추출의 추론을 하지 않습니다. 인보이스의 총액을 대신 찾아주지 않습니다. 단지 그 작업을 실제 텍스트에서 수행하고 결과가 정의된 스키마대로 나오는지 보장합니다.

• 이 프로젝트는 제가 구축 중인 AI 문서 자동화 작업을 위한 실제 도구이며, 포트폴리오의 일부로 게시되었습니다. 새롭게 만들어진 도구여서 아직 실마리는 많지 않습니다. 테스트와 경로 제한 가드는 갖추었지만 그 부가 하드닝되지는 않았습니다. 민감한 디렉토리에 연결해서 사용하기 전에 검토하세요.

개발

uv venv
uv pip install -e '.[dev]'
uv run pytest

테스트 스위트는 두 페이지짜리 아주 작은 PDF 픽스처(추가 의존성 없이 손으로 작성해 만든 미니 PDF)를 메모리상으로 생성하여, 전체 6가지 도구와 경로 트래버스 가드, glob 패턴 제한(심볼릭 링크 우회를 포함), 페이지 범위 오류, 다중 오류 스키마 검증, CSV 반올림, 그리고 MCP 서버 객체를 통한 도구 등록 및 오류 전달까지 전부 확인합니다.

라이선스

MIT © 2026 Koray Nar