使用 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 配置的缓存。初始处理可能需要一些时间并占用数 GB 空间。DOCX、PPTX 和 EPUB 文档需要 marker-pdf[full] 变体，该变体已包含在 pyproject.toml 中。

OpenCode 配置

将 opencode.example.jsonc 中的配置复制到项目根目录的 opencode.json 或 opencode.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。当源文档未更改时，系统会重新索引现有的 Markdown，而无需再次运行 Marker。

转换和公式

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 License 分发。Marker 的代码使用 Apache-2.0 License，其模型权重使用单独的许可证。在进行大规模商业使用之前，请查阅 Marker 的条款。