Marker 및 ChromaDB를 사용하는 로컬 문서 MCP 서버

이 프로젝트는 OpenCode용 Python MCP 서버를 구현합니다. DOCS/ 아래에 있는 PDF, Word(.docx), PowerPoint(.pptx), EPUB 파일을 읽되, DOCS/mdDB/는 항상 제외합니다. 문서를 Marker로 Markdown으로 변환하고, 표와 수식을 LaTeX로 보존하며, 완전한 Markdown 파일을 DOCS/mdDB/ 아래에 저장하고, ChromaDB에 영구 의미 인덱스를 생성합니다.

검색은 구조를 인식합니다. ChromaDB는 쿼리와 가장 관련성이 높은 청크를 찾지만, MCP 서버는 분리된 청크를 반환하지 않습니다. 결과 메타데이터를 사용하여 원본 Markdown 파일을 열고 제목으로 구분된 전체 섹션을 재구성합니다. 응답에는 주변 텍스트, 표, 수식이 파일 경로 및 줄 범위와 함께 포함됩니다.

데이터 흐름

flowchart TD
    A["DOCS: PDF, DOCX, PPTX, EPUB"] --> B["Marker 2"]
    B --> C["Complete Markdown + images"]
    C --> D["DOCS/mdDB"]
    C --> E["Structural chunks"]
    E --> F["Local ChromaDB"]
    G["OpenCode query"] --> F
    F --> H["Chunk metadata"]
    H --> D
    D --> I["Complete Markdown section"]
    I --> G

각 청크는 최소한 source_path, markdown_path, section_title, section_path, section_start_line, section_end_line, chunk_start_line, chunk_end_line을 저장합니다. 또한 변경 사항을 감지하기 위해 소스 문서와 Markdown 파일의 SHA-256 해시를 저장합니다.

Related MCP server: Personal Semantic Search MCP

프로젝트 구조

current-project/
├── DOCS/
│   ├── article.pdf
│   ├── manual.docx
│   └── mdDB/
│       ├── article.md
│       ├── manual.md
│       └── .chroma/
├── .opencode/
│   └── MCP/
│       └── opencode-document-rag-mcp/
│           ├── src/doc_rag_mcp/
│           ├── tests/
│           ├── README.md
│           └── pyproject.toml
└── opencode.jsonc

소스 문서는 DOCS/ 바로 아래 또는 DOCS/mdDB/를 제외한 모든 하위 디렉터리에 둘 수 있습니다. 상대 디렉터리 구조는 출력에 그대로 유지됩니다. 예를 들어 DOCS/manuals/instrument.pdf는 DOCS/mdDB/manuals/instrument.md를 생성합니다. 추출된 이미지는 Markdown 파일 옆의 instrument_assets/ 아래에 저장되며, 해당 링크는 상대 경로로 다시 작성됩니다. DOCS/mdDB/ 트리 전체는 검색에서 제외되므로 MCP 서버는 자신의 출력을 처리할 수 없습니다.

요구 사항

Python 3.10–3.13과 uv가 필요합니다. Marker 2는 OCR 및 수식 처리를 위한 추론 백엔드가 필요합니다. macOS 또는 CPU 전용 시스템에서는 llama.cpp를 권장합니다. NVIDIA GPU가 있는 시스템에서는 Surya를 통해 구성된 VLLM 백엔드를 사용할 수 있습니다.

macOS에서:

brew install uv llama.cpp

Linux에서는 uv와 llama.cpp에서 제공하는 최신 llama-server 바이너리를 설치합니다. NVIDIA 시스템의 경우 Marker의 요구 사항에 따라 Docker와 NVIDIA Container Toolkit을 설치합니다.

설치

릴리스 아카이브를 현재 프로젝트의 루트에 직접 압축 해제합니다. 아카이브에는 이미 .opencode/MCP/opencode-document-rag-mcp/ 디렉터리 구조가 포함되어 있습니다:

cd /path/to/current-project
unzip opencode-document-rag-mcp-v1.1.2.zip -d .
uv sync --project .opencode/MCP/opencode-document-rag-mcp

압축 해제 후 MCP 서버는 정확히 다음 위치에 설치됩니다:

.opencode/MCP/opencode-document-rag-mcp

첫 번째 변환과 첫 번째 벡터화는 필요한 모델을 다운로드합니다. ONNX 임베딩 모델은 DOCS/mdDB/.chroma/.embedding_models/ 아래에 저장됩니다. Marker 모델은 Marker와 Surya가 구성한 캐시를 사용합니다. 초기 프로세스는 시간이 걸릴 수 있으며 수 기가바이트를 소비할 수 있습니다. DOCX, PPTX, EPUB 문서에는 marker-pdf[full] 변형이 필요하며, 이는 이미 pyproject.toml에 포함되어 있습니다.

OpenCode 구성

프로젝트 루트의 opencode.json 또는 opencode.jsonc 파일에 opencode.example.jsonc의 구성을 복사합니다. MCP 서버가 다른 위치에 저장된 경우 --project 뒤에 오는 경로만 변경합니다.

최소 구성:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "document-rag": {
      "type": "local",
      "command": [
        "uv",
        "run",
        "--project",
        ".opencode/MCP/opencode-document-rag-mcp",
        "doc-rag-mcp"
      ],
      "cwd": ".",
      "enabled": true,
      "timeout": 30000,
      "environment": {
        "DOC_RAG_PROJECT_ROOT": ".",
        "SURYA_INFERENCE_BACKEND": "llamacpp",
        "SURYA_INFERENCE_KEEP_ALIVE": "true"
      }
    }
  }
}

cwd: "." 설정은 OpenCode에서 열린 프로젝트의 루트를 기준으로 모든 경로를 해석합니다. 다음으로 연결을 확인합니다:

opencode mcp list

AGENTS.example.md 파일에는 문서에 관한 질문에 답하기 전에 OpenCode가 이 MCP 서버를 조회하도록 지시하는 선택적 정책이 포함되어 있습니다. 해당 내용을 프로젝트의 AGENTS.md 파일에 통합할 수 있습니다.

MCP 도구

OpenCode에서 MCP 서버 사용

소스 문서를 DOCS/ 아래에 두되, DOCS/mdDB/ 아래에는 절대 두지 마세요. 그런 다음 다음과 같은 요청을 사용할 수 있습니다:

Use document-rag to list the available documents.

Use ingest_all_documents to convert and index every source document under DOCS, excluding mdDB.

Search the documents for the definition of wave energy flux, preserving the related LaTeX equations and tables.

Search only manual_tecnico.pdf for the instrument's operating limits and cite the Markdown section and line range.

Read the Methods > Statistical analysis section from article.docx.

확장 검색

search_documents는 query, 1부터 20까지의 top_k 값, 선택적 document_name을 받습니다. 내부적으로 ChromaDB에 추가 결과를 요청하여 동일한 섹션의 여러 청크가 모든 결과 위치를 차지하지 않도록 합니다. 그런 다음 중복 섹션을 제거하고 최대 top_k개의 고유 섹션을 반환합니다.

각 결과에는 쿼리 시점에 디스크에서 읽은 완전한 섹션인 context가 포함됩니다. index_is_current는 Markdown 파일이 인덱싱되었을 때의 해시와 여전히 동일한지 여부를 나타냅니다. 이 값이 false이면 ingest_document 또는 ingest_all_documents를 실행하세요. 소스 문서가 변경되지 않은 경우 시스템은 Marker를 다시 실행하지 않고 기존 Markdown을 다시 인덱싱합니다.

변환 및 수식

Marker는 서식이 지정된 표와 $$로 구분된 LaTeX 수식을 생성합니다. 기본 모드는 balanced이며, 표, OCR, 수학적 충실도가 우선일 때 적합합니다. CPU 또는 Apple Silicon 시스템에서는 다음으로 처리 비용을 줄이세요:

"DOC_RAG_MARKER_MODE": "fast"

스캔된 문서 또는 읽을 수 없는 텍스트의 경우:

"DOC_RAG_FORCE_OCR": "true"

호환되는 LLM 서비스를 통한 Marker의 선택적 하이브리드 교정의 경우:

"DOC_RAG_USE_LLM": "true"

마지막 옵션은 자격 증명과 Marker가 지원하는 서비스가 필요합니다. 일반적인 MCP 서버 작동에는 필요하지 않습니다.

환경 변수

보안 및 일관성

서버는 지원되지 않는 확장자, .. 경로 탐색, DOCS/ 외부의 소스, DOCS/mdDB/ 내부의 모든 소스, DOCS/mdDB/ 외부의 Markdown 경로를 거부합니다. ChromaDB에 저장된 경로는 다시 검증되지 않고는 사용되지 않습니다. Markdown 쓰기는 원자적이며, 인덱스 교체는 해당 문서로 제한됩니다.

같은 디렉터리에 manual.pdf와 manual.docx처럼 기본 이름이 같은 두 파일이 있으면 둘 다 manual.md를 생성하게 됩니다. 서버는 이 충돌을 감지하고 쓰기 또는 인덱싱 전에 소스 파일 중 하나의 이름을 바꾸도록 요구합니다.

테스트

단위 테스트는 Marker나 ChromaDB를 로드하지 않습니다. 계층적 분할, 표와 수식 보존, 섹션 확장, 경로 보호를 검증합니다:

PYTHONPATH=src python -m unittest discover -s tests -v

다음 명령으로 전체 소스 트리의 구문을 확인할 수도 있습니다:

python -m compileall -q src tests

라이선스

이 프로젝트는 MIT 라이선스로 배포됩니다. Marker는 코드에 Apache-2.0 라이선스를 사용하고 모델 가중치에는 별도의 라이선스를 사용합니다. 대규모 상업적 사용 전에 Marker의 약관을 검토하세요.