doc-extract-mcp

Сервер MCP (Model Context Protocol), который предоставляет LLM детерминированные инструменты для работы с документами в процессах извлечения структурированных данных. LLM выполняет чтение и логику извлечения; этот сервер предоставляет те части, которые никогда не должны оставаться на усмотрение языковой модели: надёжный доступ к файлам, разбор, разбиение на фрагменты, валидацию JSON Schema и защищённую запись файлов.

Создан Koray Nar как портфолио-проект для тех рабочих процессов автоматизации документов с помощью ИИ, которые он развивает, — целевой сценарий: преобразование неструктурированных PDF-файлов (заказов на покупку, счетов, отчётов) в JSON, прошедший валидацию по схеме. Опубликован как часть публичного портфолио. Работает с Claude Code и Claude Desktop, а также с любым другим MCP-клиентом.

Why

Агент извлечения данных сбоят в предсказуемых местах: он галлюцинирует содержимое файлов, теряет нить длинных документов, молча выдаёт JSON, который почти соответствует целевой схеме, и пишет результат куда попало. Этот сервер устраняет такие сбои:

• Доступ к файлам ограничен одним разрешённым корневым каталогом (DOC_EXTRACT_ROOT).

• Текст PDF приходит с явными маркерами --- page N ---, поэтому ссылка на «страницу 3» означает страницу 3.

• Длинные документы разбиваются на фрагменты детерминированно, с перекрытием и подсказками о страницах.

• Извлечённый JSON проверяется по JSON Schema (Draft 2020-12), и каждая ошибка сообщается с указанием пути JSON Pointer — не только первая, — чтобы модель могла исправить все ошибки за один проход.

• Результат записывается сервером (JSON или CSV), в том же корневом каталоге, с проверяемым количеством строк и байтов.

Related MCP server: BigContext MCP

Tools

Все аргументы с данными путями разрешаются и отклонются, если они выходят за пределы разрешённого корня (защита от path traversal). Аргумент glob_pattern ограничен так же: абсолютные шаблоны и шаблоны, содержащие .., отвергаются, а любое совпадение, которое резолвится за пределми корня (например, через симлинк), молча отбрасывается из выдачи. Сбой защиты предается как ошибка MCP-инструмента, поэтомы вызывая модель видит реальную причину, а замаскированную общую ошибку.

Quickstart

Требуется Python 3.11+ и uv.

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

Запуск без клиента (транспорт 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

Add to 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 по умолчанию равен рабочей директории сервера, если не задан. Установите его в папку, где лежат ваши документы; ничто за её пределами не могёт быть прочитано или записано.

Typical workflow

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") — запишите результат.

Limitations (честное по поводу ограничений)

• Только текстовые PDF. Извлечение использует pypdf; сканы и PDF только с изображениями возвращают пустой текст. OCR нет.

• Качество извлечения варьируется от того, как создание PDF. Сложные макеты (многоколоночные, плотные таблицы) могут дать неидеальный порядок чтения — это особенность pypdf, и сервер наследует её.

• Нет поддержки .docx / .xlsx. Поддерживаются типы .pdf, .txt, .md, .csv, .json.

• Сервер не выполняет логику извлечения. Он не найД итог по счету; он гарантирует, что модель, которая его находит, работает с реальным текстом и что результат соответствует вашей схеме.

• Это рабочий инструмент, создан для развития работы по автоматизации ИИ и опубликован как часть моего портфолио; он новый и ещё не успел потрудиться в проде. У него есть тесты и защита от выхода за корневой каталог, но не более того — прежде чем направлять его на чувствительные каталоги, просмотрите код.

Development

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

Тестовая насыщает построить в памяти небольшую PDF-фикстуру (минимальный вручную созданный PDF, без дополнительных зависимостей) и покрывает все шесть инструментов, защиту доступа к файлам, ограничения glob-шаблонов (включая symlink-побеги), ошибения диапазона странц, валидацию схем с несколькими ошибками, раунт-трип CSV, а также регистрацию инструментов и распрораненение ошибок через объект MCP-сервера.

License

MIT © 2026 Koray Nar