mdcx

문서 컬렉션을 검증된 Markdown으로 변환하고, 단일 암호화 파일로 패키징한 다음, Model Context Protocol을 통해 에이전트가 쿼리할 수 있게 만듭니다.

문제

문서 컬렉션에 대해 질문에 답하는 에이전트는 두 가지 선택지가 있습니다. 컨텍스트 창에 문서를 넣는 방법은 비용이 많이 들고 창 크기에 제한됩니다. 또는 각 항목의 위치를 이미 알고 있는 컴포넌트에 쿼리하는 방법이 있습니다.

cl100k_base 토크나이저를 사용하여 실제 99개 문서, 180MB 컬렉션에서 특정 쿼리 하나—3D로 모델링할 최소 파이프 직경이 명시된 위치—를 측정한 결과:

435개는 질문 20개, 검색된 구절 274개, 답변 141개로 구성됩니다.

첫 번째 행이 컬렉션 전체를 소비하는 데는 구체적인 이유가 있습니다. PDF는 검색할 수 없습니다. 바이너리이기 때문입니다. 사전 변환 없이는 99개 문서 중 어느 문서에 답이 있는지 알 방법이 없습니다. 모두 추출해서 읽어야 합니다.

이것은 평균이 아닌 단일 측정값입니다. 절감 효과는 답변에 필요한 텍스트 양에 따라 달라집니다. 변하지 않는 것은 변화의 형태입니다. 작업이 사라지는 것이 아니라, 과금되고 유한한 컨텍스트 창에서 유한하지 않은 CPU로 이동합니다. 그래서 로컬 열이 내려가지 않고 올라가는 것입니다.

Related MCP server: md-mcp

세 단계

변환. 각 문서는 Markdown으로 변환되고, 변환을 수행한 엔진과 독립적인 라이브러리로 읽은 원본이 실제로 노출하는 텍스트와 대조 검증됩니다. 구조화 엔진이 누락한 콘텐츠는 손실로 보고되는 대신 그대로 추가됩니다.

개발 중 사용된 컬렉션(99개 문서, 1,144,553 참조 단어)에서 594단어가 복구되지 않아 전체 커버리지는 99.948%였습니다. 텍스트를 노출하는 184개 문서 중 116개가 정확히 100%로 나왔고, 99.5% 미만은 없었습니다. 나머지 4개는 파일에 텍스트가 전혀 없는 스캔된 도면으로, 광학 문자 인식으로 읽었으며 검증 불가로 표시됩니다. 측정할 원본 텍스트가 존재하지 않기 때문입니다.

패키징. 말뭉치, 검색 인덱스, 모든 구절의 출처가 AES-256-GCM으로 암호화된 단일 .mdcx 파일에 들어가며, 헤더는 키 없이 읽을 수 있습니다. Markdown 8.8MB에서 단일 파일 3.9MB로 줄어듭니다.

검색. 쿼리는 답변하는 구절을 정확한 출처와 함께 반환합니다. 튜닝에 사용된 실제 쿼리 20개 중 올바른 문서가 상위 5개 결과 안에 19건, 상위 10개 안에 20건 모두 나타납니다.

설치

이 패키지는 쿼리와 변환을 분리합니다. 요구 사항이 매우 다르기 때문입니다.

무거운 의존성을 끌어들이는 것은 변환입니다. .mdcx 파일을 받아 쿼리만 하면 되는 사람은 Docling도 PyTorch도 설치할 필요가 없습니다.

컬렉션 변환

pip install "mdcx[convert]"
mdcx-convert --input ./Documents --output ./Documents_md

출력은 입력 디렉터리 구조를 그대로 반영하고, 전역 인덱스를 추가하며, 각 파일에 대해 원본 대비 달성된 커버리지를 기록합니다.

패키징 및 쿼리

mdcx pack --output ./Documents_md --target corpus.mdcx --key "..."
mdcx info corpus.mdcx
mdcx search corpus.mdcx "where is the minimum diameter stated" --key "..."
mdcx export corpus.mdcx --target ./restored --key "..."

info는 키 없이 헤더를 읽으므로 파일을 열기 전에 발행자와 무결성을 확인할 수 있습니다. export는 원본 폴더를 재구성합니다. 떠날 수 없는 형식은 아무리 좋은 의도라도 함정이기 때문입니다.

MCP 서버로 사용하기

서버는 Python과 이 패키지가 필요합니다. 변환 스택은 필요하지 않으므로 용량은 약 50MB입니다.

{
  "mcpServers": {
    "mdcx": {
      "command": "python",
      "args": ["-m", "mdcx.mcp_server"],
      "env": {
        "MDCX_FILE": "/path/to/corpus.mdcx",
        "MDCX_KEY": "package-key"
      }
    }
  }
}

또는 uv를 사용하면 사전 설치 없이 서버가 실행됩니다. 이는 Python MCP 서버의 일반적인 구성입니다:

{
  "mcpServers": {
    "mdcx": {
      "command": "uvx",
      "args": ["--from", "mdcx[mcp]", "python", "-m", "mdcx.mcp_server"],
      "env": {
        "MDCX_FILE": "/path/to/corpus.mdcx",
        "MDCX_KEY": "package-key"
      }
    }
  }
}

세 가지 도구가 노출됩니다. search는 질문에 답하는 구절을 각각의 출처 문서와 휴대용 경로와 함께 반환합니다. info는 말뭉치와 변환의 정확도를 설명합니다. document는 구절로 충분하지 않을 때 전체 문서를 반환합니다.

서버는 수신 대기를 시작하기 전에 패키지를 검증하므로, 잘못된 경로나 키는 첫 번째 쿼리에서가 아니라 즉시 보고됩니다.

테스트

pip install pytest
python -m pytest tests/ -v

테스트 스위트는 적대적 입력을 다룹니다: 빈 파일과 손상된 파일, 다른 문자 체계의 이름, SQL 인젝션 시도를 포함한 잘못된 쿼리, 잘린 패키지와 변조된 패키지, 콘텐츠 손실에 대한 압축 등입니다.

경로

출력에는 절대 경로가 없습니다. 모든 문서는 @/로 시작하는 의사 경로로 식별되며, 이를 포함하는 폴더 또는 패키지를 기준으로 해석됩니다. 따라서 말뭉치는 로컬 디스크, 네트워크 공유, 클라우드 등 어디에 저장되든 유효합니다.

서명

패키지에 서명하여 발행자를 단순히 주장하는 것이 아니라 증명할 수 있습니다. 서명은 암호화된 본문의 다이제스트를 포함하므로 출처와 콘텐츠를 모두 증명하며, 암호화 키 없이 검증됩니다.

mdcx keygen
mdcx pack --output ./Documents_md --target corpus.mdcx --key "..." \
          --issuer "Acme Ltd" --signing-key <private-key>
mdcx verify corpus.mdcx --public-key <public-key>

검증에는 본문의 무결성도 필요합니다. 기록된 다이제스트만 다루는 서명은 헤더를 그대로 둔 채 콘텐츠가 교체된 패키지를 수용할 수 있기 때문입니다.

발행자 필드만으로는 자유 텍스트일 뿐 아무것도 증명하지 못합니다. 서명만이 증명합니다.

암호화

패키지는 저장 시 암호화되고 열 때 메모리에서 복호화됩니다. 디스크에 평문으로 기록되는 것은 없습니다. 이는 전송 중인 파일을 보호합니다. 복호화 없이 암호화된 데이터를 검색하는 것과는 다릅니다.后者는 문서화된 누출 공격과 쿼리당 수 초 단위의 비용이 있는 별개의 분야입니다.

키는 scrypt로 파생되어 추측 속도를 늦춥니다: 초당 약 8회 시도, 각 시도에 32MB 메모리가 필요하므로 GPU에서 병렬화를 방지합니다. 그럼에도 실제 강도는 암호문구입니다: 사전 기반 비밀번호는 하루 만에 뚫립니다.

저자

**Jorge Ellena G.**가 구상하고 지휘했으며, Claude(Anthropic)의 도움으로 프로그래밍되었습니다.

이 패키지의 모든 결정은 관례가 아닌 측정에 근거하여 이루어졌습니다: 어떤 변환 엔진을 사용할지, 어떤 라이선스가 어떤 것을 허용하는지, 검색 순위를 어떻게 매길지, 어떤 최적화를 수용하고 어떤 것을 폐기할지. 몇 가지는 정확히 측정되었기 때문에 폐기되었습니다—검색 후보 풀을 줄이는 것이 10배 빨라 보였지만 실제로는 정확도를 20건 중 19건에서 17건으로 낮췄습니다—그리고 이러한 측정값은 이를 정당화하는 결정과 함께 기록됩니다.

인용

영구 식별자로 Zenodo에 보관되었습니다. 개념 DOI는 항상 최신 버전으로 연결됩니다:

https://doi.org/10.5281/zenodo.22015991

라이선스

Apache 2.0. 저작권 고지를 유지하는 한 이 소프트웨어는 사용, 수정, 판매가 가능합니다.

PyMuPDF는 의도적으로 피했습니다. AGPL 라이선스는 이 소프트웨어를 사용하는 모든 사람이 자신의 소프트웨어를 AGPL로 공개해야 하며, 네트워크 서비스로만 제공하는 경우도 포함되기 때문입니다.