CorpusGate

MarkItDown과 MCP 기반 LLM 국제 수준의 개인 문서 게이트웨입니다.

AI 도구를 위해 개인 문서를 변환, 인덱싱, 검색하며 문서 콘텐츠를 제3자 서비스로 보내지 않습니다.

CorpusGate는 자체 인프라에 있는 문서에 대한 통제된 AI 도구 접근이 필요한 개인과 팀을 위한 범용 자체 호스팅 문서 MCP 서버입니다. MarkItDown은 지원되는 파일을 재사용할 수 있는 Markdown으로 변환합니다. 그런 다음 게이트웨이는 해당 Markdown을 청크로 나누고 인덱싱하며, MCP는 서버가 강제하는 예산 안에서 관련성이 있고 출처가 표시된 청크만 반환합니다.

자체 호스팅을 통해 원본 문서, 생성된 Markdown, 쿼리, 메타데이터 및 인덱스는 운영자의 통제 하에 유지됩니다. 토큰 절감은 제한된 검색과 청크 선택에서 비롯되며 MarkItDown 혼자서 이루어지는 것이 아닙니다. 이 프로젝트는 챗봇, LLM 답변 생성기, 계약 분석 제품, SaaS 플랫폼 또는 사용자용 문서 패널이 아닙니다.

기능

• Microsoft MarkItDown를 통한 PDF, DOCX, PPTX, XLSX, TXT, Markdown, HTML 변환.

• 영구 Markdown 캐시, 토큰 인지 및 제목 보존 청크, SHA-256 중복 제거.

• 가벼운 기본 설치에서 SQLite FTS5/BM25 어휘 검색.

• 로컬 임베딩을 사용하는 선택적 CPU 전용 다국어 의미 검색 및 RRF 하이브리드 검색.

• 소스/위치 메타데이터, 커서, 중복 제거 및 이웃 제한이 적용된 예산 기반 MCP 응답.

• REST API 키 및 MCP Bearer 인증, 안전한 UUID 저장소, 경로/심볼릭 링크 보호, 요율 제한 및 구조화된 콘텐츠 안전 로그.

• AMD64/ARM64, Oracle Cloud, Tailscale, Caddy HTTPS에 적합한 강화된 Docker Compose 배포.

• 설정 도우미, 운영 doctor/scan/reindex/backup 명령, 버전화된 SQLite 스키마 및 CI.

Related MCP server: rag-retriever-mcp

작동 방식

REST upload or read-only inbox scan
        │
        ├─ type, signature, size, path, and free-space validation
        ├─ UUID storage + SHA-256 ── unchanged? ── reuse cached/indexed record
        │
        └─ MarkItDown ──> persistent Markdown ──> token-aware chunks
                                                   │
                              ┌────────────────────┴────────────────────┐
                              │                                         │
                    SQLite FTS5 / BM25                      optional local embeddings
                              │                                  + private Qdrant
                              └────────────────────┬────────────────────┘
                                                   │
                               ranking → dedup → token/char budget → MCP

코드는 단일 서버 제품을 분산형 시스템으로 만들지 않은 채 파서, 스토리지,리포지토리, 청크, 임베딩, 벡터 저장소 및 검색 계약을 인터페이스 뒤에 유지합니다. 문서는 기본 데이터 소스로 유지되며 Markdown과 벡터 인덱스는 다시 구울 수 있습니다.

지원 형식

암호화되거나 손상된 파일, 스캔 이미지만 있는 파일 또는 변환기가 지원하지 않는 파일은 다른 문서를 중단하지 않고 안전하게 실패합니다.

빠른 시작

요구 사항: Compose v2 및 OpenSSL가 포함된 Docker Engine. 호스트 Python은 필요하지 않습니다.

git clone https://github.com/mustafa0zdemir/corpusgate.git
cd corpusgate
./corpusgate init
./corpusgate up
curl --fail http://127.0.0.1:8000/health
./corpusgate doctor

./corpusgate init은 persistent/inbox 폴더를 생성하고 .env가 존재하지 않을 때만 .env.example을 복사하며, 출력하지 않고 개별 임의 REST/MCP 자격 증명을 생성하고, Docker/Compose 및 선택한 포트를 확인한 다음 Compose의 유효성을 검사합니다. 기존 .env를 덮어쓰지 않습니다.

동등한 수동 흐름은 .env.example을 .env로 복사하고 두 자격 증명 자리에 서로 다른 openssl cd -hex 32 값을 넣고 documents/를 만든 다음 docker compose up -d를 실행하는 것입니다. .env는 절대 커밋하지 마세요.

초기화 후에 선택적인 로컬 의미/하이브리드 검색도 한 번의 작업으로 완료됩니다.

./corpusgate init --semantic
./corpusgate up --semantic

첫 번째 의미 검색 시작 시 모델을 영구 캐시에 다운로드한 다음 내부 Docker 네트워크 네트워크의 Qdrant와 함께 게이트웨시를 오프라인으로 시작합니다. 이후 시작에서는 모델 볼륨과 벡터 볼륨을 모두 재사용합니다. 어휘 설치에는 위 두 의미 구성 요소를 설치하거나 실행하지 않습니다.

문서 추가

가장 간단한 운영자 워크플로는 읽기 전용 호스트 inbox를 사용하는 것입니다.

cp examples/documents/* documents/
./corpusgate scan
./corpusgate list-documents

검색은 숨김/시스템/임시 파일, 지원되지 않는 유형, 디렉터리 및 symlink를 건너뜁니다. 입력 파일은 documents/에 그대로 남아 있으며, 비공개 UUID 복사본은 영구 소스 볼륨에 저장됩니다. 완전한 lexical→semantic/hybrid→MCP 안내는 합성 데모를 참조하세요.

AI 도구가 파일 바이트를 모델 컨텍스트에 넣지 않고 호출할 수 있는 단일 파일 워크플로의 경우 로컬 파일을 실행 중인 REST API에 직접 스트리밍합니다(curl 필요):

./corpusgate upload /absolute/path/to/document.pdf

이 명령은 CORPORUSGATE_CLIENT_API_KEY, CorpusGate_API_KEY 또는 로컬 .env에서 REST 키를 읽고, 절대 출력하지 않을 뿐 아니라 리디렉션과 안전하지 않은 원격 HTTP를 거부하며, API 업로드 메타데이터만 반환합니다. 원격 개인 서버에는 --url https://YOUR-NODE.YOUR-TAILNET.ts.net을 전달하세요.

REST 업로드는 애플리케이션에서도 사용할 수 있습니다.

export CORPUSGATE_CLIENT_API_KEY='value-from-your-env'
curl --fail -X POST http://127.0.0.1:8000/api/v1/documents \
  -H "X-API-Key: ${CORPUSGATE_CLIENT_API_KEY}" \
  -F 'file=@examples/documents/private-network-guide.md'

REST는 /api/v1/documents 아래 페이지 처리된 메타데이터, Markdown, 청크, 어휘 검색 및 삭제를 제공합니다. 대화형 OpenAPI 문서는 /docs에 있으며, 보호되는 작업에는 여전히 X-API-Key가 필요합니다.

MCP 클라이언트 연결

원과 같은 개인/공용 호스트의 엔드포인트는 https://YOUR_PRIVATE_OR_PUBLIC_HOST/mcp이며 모든 요청에는 다음이 필요합니다:

Authorization: Bearer YOUR_MCP_TOKEN

권장 개인 경로로는 Tailscale Serve를 사용하십시오. Caddy HTTPS는 공개 대안이며, 두 경우 모두 게이트웨이 포트는 호스트 루프백에 바인딩되어 있습니다. 검증된 필드 매핑, Inspector 명령, Tailscale/HTTPS 예제 및 문제 해결 방법은 MCP 연결 가이드에 있습니다. 검증되지 않은 클라이언트 특정 비디오 JSON 래퍼 또는 소스 제어에 토큰을 저장하지 마세요.

MCP 도구

검색 항목에는 document_id, document_name, chunk_id, heading, position, 관련성/순위 필드, 제한된 content, content_length 및 검색 모드 메타데이터가 항상 포함됩니다. 빈 검색 결과는 비어있는 items 목록, 적용된 예산, 메트릭을 반환하며 커서는 없습니다. 잘못된 방법, 커서, 필터, 질의 또는 한도 초과 값은 통제 가능한 도구 오류를 발생시킵니다. 업로드 및 삭제는 REST 전용으로 유지됩니다.

권장 흐름:

AI tool → search_document(query, top_k=3, max_tokens=600)
        → ranked chunks + source positions + actual retrieval mode
        → optional bounded get_document_section

어휘, 의미, 하이브리드 검색

• lexical은 운영 기본값입니다: 제목 가중치 BM25과 함께 SQLite FTS5는 별도의 서비스 없이 정확한 식별자와 구문을 보존합니다.

• semantic은 구성 가능 많은 다국어 CPU 모델을 통해 로컬에서 질의와 청크를 임베딩하며 벡터를 사설 클라우드인 Qdrant에 저장합니다.

• hybrid는 Reciprocal Rank Fusion(RRF)을 통해 독립적인 어휘 순위와 의미 순위를 통합합니다. 중복 청크는 한 번만 반환되며 정확한 어휘 일치는 버리지 않습니다.

• lexical_fallback는 의미/하이브리드 검색이 요청되었으나 선택 로컬 모델, 벡터 저장소, 인덱스를 사용할 수 없고 폴백이 활성화된 경우 보고됩니다.

기본 모델은 Apache-2.0 라이선스인 sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2로, FastEmbed/ONNX를 통해 CPU에서 사용되는 384차원 다국어 모델입니다. 모델 교체, 오프라인 전송, 재인덱스 규칙, 측정값 및 Oracle 메모리 안내는 의미 검색에서 확인할 수 있습니다.

토큰 최적화

MarkItDown은 다양한 파일을 일관되게 파싱 가능하도록 만들지만, 이것으로 토큰은 줄어들지 않을 수 있습니다. 게이트웨이는 변환을 한 번만 캐시하고 청크 랭킹, 중복 제거, top_k, max_chars, 예상 max_tokens 적용, 인접 청크 제한, 긴 결과 집합 페이징을 통해 반환되는 문맥을 줄입니다. 전체 문서나 원시 파일을 반환되는 기본 MCP 도구를 노출하지 않습니다.

토큰 수는 로컬 결정론적 추정치이지 공급자별 과금 토크나이저가 아닙니다. 반복 가능한 측정 합성 시나리오와 정확한 범위는 검색 보고서에 있습니다; 어떤 보편적 절감 백분율도 주장하지 않습니다.

보안 및 개인 프라이버시

• 텔메트리, 문서 텍스트, 쿼리 텍스트, 클라우드 임베딩 API, 필수 LLM 공급자가 없습니다.

• 원본 파일의 UUID 경로를 사용합니다. 파일 경로 탐침, 절대 절대 결, 심볼릭 링크 탈출, 숨김/임시 파일, MIME/시그니처 불일치, 아카이브 확장, 업로드 크기, 디스크 부족을 검사합니다.

• REST는 API 키를 사용하고, 원격 MCP는 환경 변수 또는 Docker secret의 상수 시간 비교 Bearer 토큰을 사용합니다. 현재/이전 토큰을 둘 다 허용하여 회전가 의 다음 은 가능합니다.

• 구조 로그는 허용된 작업 메타데이터만 포함하며 문서 내용, 자격 증명, 완전한 쿼리, 클라디언 클라디언에 보이는 스택 Trace를 절대 포함하지 않습니다.

• 게이트웨이 컨테이너는 비루트, 무능력, no-new-privileges, 읽기 전용 루트이며 명시적 쓰기 가능한 볼륨/tmpfs와 리소스/로그 제한을 가집니다.

• 기본 Compose는 127.0.0.1:8000만 게시하며 Qdrant는 내부 전용입니다. 공용 배포에는 Caddy TLS가 필요하며 Bearer 인증/비율/응답 제한을 유지합니다.

저장 데이터에는 비공개 UUID 본, 생성된 Markdown, SQLite 메타데이터/청크/FTS, 선택적 로컬 벡터 및 모델 캐시, 백업, 운영자 구성이 포함됩니다. 완전한 삭제를 위해 REST API를 통해 먼저 문서를 삭제하세요; 명시적 백업 및 종료 후에만 지속적 볼륨을 제거하세요. 보안 취약점 신고는 SECURITY.md를 참조하세요.

Oracle Cloud 배포

권장 Oracle Ubuntu 배포는 앱을 루프백에 바인딩하고 개인 네트워크 전용 HTTPS를 위해 Tailscale Serve를 사용합니다. 공개 도메인이 필요한 경우에는 Caddy public 프로필을 사용하는 방법이 문서화되어 있습니다. Oracle Security Lists/NSGs는 TCP 8000 또는 Qdrant 6333을 노출해서는 안 됩니다.

VM 준비, AMD64/Ampere ARM64 참고 사항, Docker 설치, 파일시스템 소유권, 직렬, 방화, Tailscale/Caddy, 로깅, 최신화, 백업, 복원, 문제 해결은 Oracle 배포 가이드에 있습니다.

구성

모든 애플리케이션 환경 변수, 기본값, 필요 값, 범위, 용도, 예시, 그리고 보안 영향은 구성 명세와 .env.example에 정리되어 있습니다. 시작 시 신규 정보 없는/짧은 자격 증명, 잘못된 포트/경로, 불가능한 청크/예산 관계, 지원하지 않는 검색 모드 또는 잘못된 의미 벡터 저장소 구성을 감지하고, 시크릿 정보를 화면에 표시하지 않고 거부됩니다.

운영 명령:

./corpusgate version
./corpusgate status
./corpusgate doctor
./corpusgate mcp-smoke
./corpusgate upload /absolute/path/to/document.pdf
./corpusgate scan
./corpusgate reindex
./corpusgate reindex --semantic
./corpusgate list-documents --limit 20 --offset 0

백업 및 복원

./corpusgate backup
./corpusgate restore /backups/corpusgate-backup-TIMESTAMP.tar.gz --confirm-restore

복원은 현재의 영구 데이터를 대체하므로 프로덕션에서는 명시적인 확인 플래그와 중지된 writer가 필요합니다. 백업에는 비공개 소스 스토리지, Markdown 캐시, 트랜잭션 방식으로 복사된 SQLite 데이터베이스, 매니페스트, 비밀값이 없는 설정 예시가 포함됩니다. .env와 토큰 파일은 별도의 암호화된 비밀 백업에 보관하세요. 벡터 데이터는 청크에서 다시 빌드할 수 있습니다.

업데이트 및 롤백

현재 버전을 확인하고, 백업하고, 검토된 태그/이미지를 선택하며, 버전이 지정된 멱등 마이그레이션을 실행하고, 재시작한 뒤 ready/MCP 상태를 확인하고, 검증이 완료될 때까지 백업을 유지하세요. 최신 버전과 호환되지 않는 애플리케이션이 생성한 데이터베이스는 자동으로 수정되지 않고 거부됩니다.

정확한 명령어와 안전한 롤백/복원 경로는 업데이트 및 롤백 문서에 있습니다. 일반 업데이트 중에는 docker compose down -v를 실행하지 마십시오.

저장소에는 수동 방식으로 승인 게이트를 거치는 GHCR 워크플로도 포함되어 있습니다. 안정 태그, 이동하는 minor 태그, latest 동작은 컨테이너 게시 정책에 정의되어 있습니다. 이번 스프린트에서는 게시된 이미지가 없습니다.

문제 해결

• ./corpusgate doctor: 비밀값을 노출하지 않고 설정, 스토리지 권한, SQLite/스키마, 디스크, 선택적 모델/벡터 상태, 서비스 준비 상태 및 버전을 검증합니다.

• 401: REST X-API-Key 또는 MCP Authorization: Bearer를 사용하세요. 다른 유형의 자격 증명은 사용하지 마십시오.

• 호스트 거부: 정확한 Tailscale/도메인 호스트를 CORPUSGATE_ALLOWED_HOSTS에 추가하고 게이트웨이를 다시 생성하세요.

• 507: 재시도하기 전에 디스크 공간을 확보하거나 예약된 디스크 임계값을 검토하세요.

• lexical_fallback: 모델 캐시와 Qdrant 상태를 점검하세요. 어휘 검색(lexical retrieval)은 계속 사용할 수 있습니다.

• 변환 실패: 지원되는 확장자, MIME/시그니처, UTF-8/Office 아카이브 무결성, 크기, 암호화 여부 및 PDF에 텍스트가 포함되어 있는지 확인하세요.

• 로그: ./corpusgate logs --tail=100; 공유 전에 출력을 정리하세요.

이슈를 열기 전에 SUPPORT.md 및 배포 환경별 문제 해결 가이드를 참조하세요.

호환성

테스트되지 않은 플랫폼은 지원되는 것으로 표시되지 않습니다. 아티팩트를 게시하기 전에 릴리스 체크리스트를 검토하세요.

제한 사항

• 단일 노드 SQLite는 고가용성 또는 다중 writer 데이터베이스가 아닙니다.

• 업로드 변환은 0.1.0에서 동기 방식입니다. 큰 문서는 더 긴 클라이언트/프록시 타임아웃이 필요할 수 있습니다.

• OCR, 클라우드 스토리지 어댑터, 사용자 계정, UI, 답변 생성, reranker, 파인튜닝, SaaS 제어부재가 없습니다.

• 대략적인 토큰 예산은 특정 LLM 토크나이저와 다를 수 있습니다.

• 시맨틱 모델 다운로드에는 캐시를 오프라인으로 전송하지 않는 동안 임시 아웃바운드 접근이 필요합니다.

로드맵

• 단일 노드 사용자에게 Redis를 필수로 만들지 않는 백그라운드 변환 작업.

• 기존 인터페이스 뒤에 구성하는 선택적 PostgreSQL/pgvector 및 오브젝트 스토리지 어댑터.

• 더 많은 변환기 메타데이터 추출 및 운영자 제어형 OCR 어댑터.

• 서명된 릴리스, SBOM/출처, 확장된 크로스 아키텍처 및 업그레이드 픽스처 지원.

기여

CONTRIBUTING.md를 읽고 CODE_OF_CONDUCT.md를 준수하며 테스트를 추가하고, 합성적이고 민감하지 않은 픽스처만 사용하세요. 보안 보고서는 공개 이슈가 아닌 SECURITY.md의 비공개 경로를 사용해야 합니다.

라이선스

CorpusGate는 기존 MIT License에 따라 제공됩니다. 서드 파티 라이브러리와 선택적 임베딩 모델은 각자의 라이선스를 유지합니다.